Configurazione di un servizio gRPC
Per creare un servizio gRPC, indipendentemente dal fatto che utilizzi o meno API Gateway,
specificare la definizione dell'interfaccia in uno o più file proto
, ovvero file di testo
file con estensione .proto
. In un file proto
definisci la superficie di un
l'API, tra cui strutture di dati, metodi, parametri dei metodi e
di testo. Quindi, compila il file proto
utilizzando le regole
compilatore del buffer di protocollo, protoc
. Per ulteriori informazioni, vedi
Che cos'è gRPC?
e
Concetti di gRPC.
Per fare in modo che il servizio gRPC sia gestito da API Gateway, oltre a al file di protocollo compilato, devi specificare una configurazione del servizio in uno o più file YAML. La configurazione di un servizio è una specifica che ti consente il comportamento di un servizio gRPC, tra cui autenticazione, quote altro ancora.
Panoramica della configurazione del servizio
Nella parte superiore del file YAML, puoi specificare le informazioni di base servizio, come il nome e il titolo. Altri aspetti del servizio sono configurati in sottosezioni del file YAML, ad esempio:
- Quali API vengono gestite.
- Modalità di autenticazione dei chiamanti.
- Tutorial limitare o concedere l'accesso alle API con le chiavi API.
- Modalità di accesso alle API mediante REST HTTP.
Ad esempio:
type: google.api.Service config_version: 3 name: calendar.googleapis.com title: Google Calendar API apis: - name: google.calendar.v3.Calendar authentication: providers: - id: google_calendar_auth jwks_uri: https://www.googleapis.com/oauth2/v1/certs issuer: https://securetoken.google.com rules: - selector: "*" requirements: provider_id: google_calendar_auth backend: rules: - selector: "*" address: grpcs://my-service-98sdf8sd0-uc.a.run.app
In genere, ogni sottosezione corrisponde a una
.proto
messaggio
in cui configuri i vari aspetti del servizio. Ad esempio:
authentication
: specifica la modalità di autenticazione dei chiamanti.backend
: controlla il routing del backend remoto.http
: definisce le regole per mappare un metodo RPC a una o più API REST HTTP di machine learning.usage
: consente di abilitare e disabilitare selettivamente la convalida delle chiavi API.
Lo schema ufficiale per la configurazione del servizio è definito dall'.proto
messaggio
google.api.Service
Configurazione di base
La Esempio di libreria, che viene utilizzato Introduzione ad API Gateway e Cloud Run for gRPC include un file di definizione dell'interfaccia di base e un file di configurazione del servizio.
Definizione dell'interfaccia Libreria,
bookstore.proto
:
syntax = "proto3"; package endpoints.examples.bookstore; option java_multiple_files = true; option java_outer_classname = "BookstoreProto"; option java_package = "com.google.endpoints.examples.bookstore"; import "google/protobuf/empty.proto"; service Bookstore { rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) {} rpc CreateShelf(CreateShelfRequest) returns (Shelf) {} rpc GetShelf(GetShelfRequest) returns (Shelf) {} rpc DeleteShelf(DeleteShelfRequest) returns (google.protobuf.Empty) {} rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {} rpc CreateBook(CreateBookRequest) returns (Book) {} rpc GetBook(GetBookRequest) returns (Book) {} rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {} } message Shelf { int64 id = 1; string theme = 2; } message Book { int64 id = 1; string author = 2; string title = 3; }
Configurazione del servizio Libreria,
api_config.yaml
:
type: google.api.Service config_version: 3 name: *.apigateway.PROJECT_ID.cloud.goog title: Bookstore gRPC API apis: - name: endpoints.examples.bookstore.Bookstore
L'esempio di codice precedente è la configurazione del servizio più semplice, in quanto:
- Definisce un servizio denominato
*.apigateway.PROJECT_ID.cloud.goog
dove PROJECT_ID è il nome del tuo ID progetto Google Cloud. - Specifica che il servizio espone l'API
endpoints.examples.bookstore.Bookstore
, come definito inbookstore.proto
.
Regole e selettori
In alcuni casi, potrebbe essere necessaria la possibilità di associare la configurazione
singoli elementi di un servizio, ad esempio per applicare l'autenticazione
solo su alcuni metodi, ma non con altri. Per farlo nella configurazione del servizio,
alcune parti della configurazione del servizio,
authentication
e
http
,
ti consentono di specificare regole e selettori. Un selettore identifica
gli elementi del servizio, ad esempio il nome di un metodo
a cui si applica la regola.
Un selettore è un elenco separato da virgole di nomi qualificati definiti nel servizio:
metodo, messaggio, campo, enum o enum. L'ultimo segmento del nome può essere
il carattere jolly *
, che corrisponde a qualsiasi suffisso. I caratteri jolly sono consentiti solo nel campo
nome e solo per un intero segmento del nome. Ad esempio: foo.*
è
Ok, ma non foo.b*
o foo.*.bar
. Per configurare un valore predefinito per tutte le
devi specificare *
da solo.
Esempio 1 (riguarda l'intero servizio):
usage:
rules:
# Allow unregistered calls for all methods.
- selector: "*"
allow_unregistered_calls: true
Esempio 2 (riguarda un singolo metodo):
usage:
rules: # IMPORTANT: ONLY LAST MATCHING RULE IS APPLIED
# Disable API key validation on just the ListShelves method
# while requiring an API key for the rest of the API.
- selector: "*"
allow_unregistered_calls: false
- selector: "endpoints.examples.bookstore.BookStore.ListShelves"
allow_unregistered_calls: true
L'esempio precedente mostra come richiedere la convalida delle chiavi API per tutti i metodi
tranne il metodo ListShelves
.
Le regole vengono valutate in sequenza, l'ultima corrispondente nell'ordine della dichiarazione .
Utilizzo di più file YAML
Può essere utile utilizzare più di un file YAML per configurare diversi
più caratteristiche per lo stesso servizio. L'uso di più file YAML semplifica
per riutilizzare i file e modificarli per diversi ambienti. Ad esempio, nel
Esempio di libreria, la configurazione di base è specificata in
api_config.yaml
e le relative regole HTTP sono specificate nel
api_config_http.yaml
. In questo modo puoi eseguire il deployment delle regole HTTP solo se vuoi attivare JSON/HTTP
alla transcodifica gRPC per la Libreria.
Se utilizzi più file YAML per la configurazione del tuo servizio, quando
configurazione corrente
distribuito
ogni file viene convertito
google.api.Service
:
i messaggi proto, quindi tutti i messaggi vengono uniti utilizzando il proto che unisce la semantica.
In altre parole, tutti i campi scalari singolari in quest'ultima istanza sostituiscono quelli della
precedenti. Pertanto, se fornisci valori singolari diversi per la stessa regola in due
, il valore nel secondo file specificato durante il deployment
. I messaggi incorporati singolarmente vengono uniti, mentre i campi ripetuti vengono
concatenate.
Come per le regole, l'unione è sensibile all'ordine. Se esistono due configurazioni del servizio, la seconda configurazione del servizio sostituisce la prima.
Annotazioni (solo regole HTTP)
In alternativa all'utilizzo di un file YAML per configurare le opzioni HTTP, puoi
configurarle direttamente nel tuo file proto
, utilizzando il metodo
meccanismo opzioni.
Le annotazioni dell'API sono definite
annotations.proto.
Utilizza le annotazioni se l'opzione di configurazione deve essere invariata rispetto a tutte
usi della definizione dell'interfaccia del buffer di protocollo. Ad esempio, se un'API ha
una singola implementazione o tutte le implementazioni devono avere lo stesso
Interfaccia HTTP, puoi annotare la configurazione HTTP nel file proto
.
Se viene fornita un'opzione di configurazione, sia nel file proto
che nel servizio
di configurazione YAML, la configurazione del servizio esegue l'override dell'annotazione.
Annotazione di esempio in un file proto
:
rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) {
option (google.api.http) = { get: "/v1/shelves" };
}
# The preceding annotation is equivalent to the following service configuration:
http:
rules:
- selector: endpoints.examples.bookstore.BookStore.ListShelves
get: '/v1/shelves'
Per ulteriori informazioni, vedi Transcodifica di HTTP/JSON in gRPC.
Passaggi successivi
- Introduzione ad API Gateway e Cloud Run for gRPC
- Deployment di un'API in un gateway
- Riferimento per la configurazione del servizio gRPC