Per creare un servizio gRPC, indipendentemente dall'utilizzo o meno di Cloud Endpoints, devi specificare la definizione dell'interfaccia in uno o più file proto
, ovvero file di testo con estensione .proto
. In un file proto
, definisci l'interfaccia della tua API, incluse le strutture di dati, i metodi, i parametri dei metodi e i tipi di ritorno. Quindi, compila il file proto
utilizzando il compilatore di buffer di protocollo specifico per la lingua, protoc
. Per ulteriori informazioni, consulta Che cos'è gRPC? e Concetti di gRPC.
Per fare in modo che il servizio gRPC sia gestito da Endpoints, 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, specifica le informazioni di base sul service, come il nome e il titolo. Puoi configurare altri aspetti del servizio in sottosezioni del file YAML, ad esempio:
- Quali API vengono gestite.
- Come vengono chiamanti autenticati.
- Come limitare o concedere l'accesso alle API con le chiavi API.
- Modalità di accesso alle API mediante l'uso REST HTTP.
- Per le API che utilizzano il dominio
cloud.goog
, la configurazione DNS.
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
Ogni sottosezione corrisponde in genere a un
messaggio .proto
in cui puoi configurare 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 attivare e disattivare in modo selettivo la convalida delle chiavi API.
Lo schema ufficiale per la configurazione del servizio è definito dal .proto
messaggio
google.api.Service
.
Configurazione di base
L'esempio di libreria, utilizzato nei tutorial di gRPC, include un file di definizione dell'interfaccia di base e un file di configurazione del servizio.
La definizione dell'interfaccia Bookstore,
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; }
La configurazione del servizio Bookstore,
api_config.yaml
:
type: google.api.Service config_version: 3 name: bookstore.endpoints.MY_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
bookstore.endpoints.MY_PROJECT_ID.cloud.goog
, doveMY_PROJECT_ID
rappresenta l'ID del progetto Google Cloud. - Specifica che il servizio espone l'API
endpoints.examples.bookstore.Bookstore
, come definito inbookstore.proto
. - Fornisci un titolo descrittivo che viene visualizzato nella pagina Endpoint > Servizi nella console Google Cloud dopo il deployment della configurazione. Esamina il versioni GitHub complete di ogni file per commenti più dettagliati.
Regole e selettori
In alcuni casi, potresti dover associare la configurazione ai singoli elementi di un servizio, ad esempio per applicare l'autenticazione su determinati metodi, ma non su 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 alla fine di un 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 tutti gli elementi applicabili, specifica *
da solo.
Esempio 1 (che interessa l'intero servizio):
usage:
rules:
# Allow unregistered calls for all methods.
- selector: "*"
allow_unregistered_calls: true
Esempio 2 (che interessa 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 e viene applicata l'ultima corrispondente nell'ordine di dichiarazione.
Utilizzo di più file YAML
Può essere utile utilizzare più di un file YAML per configurare diversi
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 implementare le regole HTTP solo se vuoi attivare la transcodifica da JSON/HTTP a 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 file, viene utilizzato il valore nel secondo file specificato durante il deployment della configurazione. I messaggi incorporati singolarmente vengono uniti, mentre i campi ripetuti vengono
concatenate.
Come per le regole, l'unione è sensibile all'ordine. Se sono presenti 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
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 sola implementazione o se tutte le implementazioni devono avere la stessa 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, consulta Transcodifica di HTTP/JSON in gRPC.
Convalida della configurazione
Tu
esegui il deployment della configurazione del servizio e hai compilato proto
file
utilizzando
gcloud endpoints services deploy
per creare la configurazione di runtime del tuo servizio. Il comando gcloud endpoints services
deploy
convalida la configurazione del servizio e segnala eventuali errori e
avvisi.
Gli avvisi sono suddivisi in avvisi regolari e linter. Avvisi Linter
utilizza un identificatore nel formato <group>-<rule>
, dove <group>
indica il gruppo di configurazione e <rule>
il linter specifico
personalizzata. Ad esempio, di seguito il gruppo è versioning
e la regola è
http-version-prefix
:
WARNING: bookstore.proto:51:3: (lint) versioning-http-version-prefix: method
'endpoints.examples.bookstore.BookStore.ListShelves' has a different version
prefix in HTTP path ('v2') than api version 'v1'.
Puoi eliminare gli avvisi del linter aggiungendo una direttiva alla documentazione di un elemento dell'API. Puoi aggiungere la direttiva nel file proto
o nel
file YAML di configurazione del servizio. Ad esempio, il seguente comando elimina l'avviso precedente:
service Bookstore {
// Returns an object.
// (== suppress_warning versioning-http-version-prefix ==)
rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) {
option (google.api.http) = { get: "/v1/shelves" };
}
}
Per eliminare gli avvisi per un intero gruppo, puoi utilizzare un carattere jolly (*
)
dei nomi delle regole. Ad esempio, versioning-*
elimina tutti gli avvisi relativi al gruppo versioning
.
Le direttive di eliminazione collegate agli elementi principali si applicano anche a tutti
bambini. Ad esempio, l'esempio seguente elimina tutti gli avvisi di gruppo versioning
in tutti i metodi all'interno del servizio:
// (== suppress_warning versioning-* ==)
service Bookstore {
// Returns an object.
rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) {
option (google.api.http) = { get: "/v1/shelves" };
}
}
Per eliminare un avviso a livello globale, allegalo alla documentazione di riepilogo del configurazione del servizio:
type: google.api.Service
name: your_api.endpoints.<producer-project-id>.cloud.goog
title: Bookstore gRPC API
apis:
- name: endpoints.examples.bookstore.BookStore
documentation:
overview: |
A simple Bookstore gRPC API.
(== suppress_warning documentation-presence ==)
Tieni presente che le direttive nella documentazione, come suppress_warning
, devono essere visualizzate su una riga separata, altrimenti non verranno riconosciute. Gli indicatori letterali di blocco YAML come >
rimuovono tutti
a capo, quindi se utilizzi overview: >
nell'esempio precedente,
l'eliminazione non funziona. Per ulteriori informazioni sui valori letterali blocchi in YAML, consulta Delimitazione con rientro.
Passaggi successivi
- Configurazione di Endpoints
- Esegui il deployment della configurazione di Endpoints
- Riferimento per la configurazione del servizio gRPC