Cloud Endpoints supporta la transcodifica del protocollo in modo che i client possano accedere all'API gRPC tramite HTTP/JSON. Extensible Service Proxy (ESP) transcodifica HTTP/JSON in gRPC.
Questa guida descrive:
- Come utilizzare le annotazioni nel file
.proto
per specificare la conversione dei dati da HTTP/JSON a gRPC - Come eseguire il deployment del servizio in Endpoints per utilizzare questa funzionalità
- Dove trovare ulteriori informazioni sulla progettazione e sull'implementazione della transcodifica per i servizi gRPC
Presuppone che tu abbia già completato i nostri tutorial gRPC e che tu conosca i concetti di base degli endpoint per le API gRPC.
Progettazione di un'API compatibile con la transcodifica
La transcodifica implica la mappatura delle richieste HTTP/JSON e dei relativi parametri ai metodi gRPC, nonché ai loro parametri e ai tipi restituiti. Per questo motivo, anche se è possibile mappare una richiesta HTTP/JSON a qualsiasi metodo API arbitrario, è utile farlo se l'API gRPC è strutturata secondo un orientamento alle risorse, proprio come un'API REST HTTP tradizionale. In altre parole, il servizio API deve essere progettato in modo che utilizzi un numero ridotto di metodi standard, corrispondenti ai verbi HTTP, come GET
e PUT
, che operano sulle risorse e sulle raccolte di risorse del servizio, che a loro volta rappresentano un tipo di risorsa. Questi metodi standard sono List
,
Get
, Create
, Update
e Delete
.
Se necessario, l'API può anche avere alcuni metodi personalizzati non standard, anche se non sono così semplici da mappare.
Puoi trovare molte altre informazioni sulla progettazione orientata alle risorse e sulle mappature di transcodifica standard nella guida alla progettazione delle API. Questa guida alla progettazione è lo standard di progettazione seguito in Google durante la progettazione di API pubbliche come le API Cloud. Anche se non è necessario seguire questa guida per utilizzare la transcodifica gRPC, ti consigliamo vivamente. In particolare, le pagine seguenti possono aiutarti a comprendere questi principi di progettazione e aggiungere utili mappature di transcodifica ai tuoi metodi:
- Design orientato alle risorse
- Metodi standard
- Metodi personalizzati
- Verbi HTTP: questa pagina fornisce linee guida aggiuntive per le implementazioni dei metodi se accedino tramite HTTP.
Potrebbe esserti utile anche la seguente pagina di riferimento:
- Riferimento regola HTTP: un riferimento completo per le regole di mappatura HTTP,
Nella parte restante di questo documento utilizzerai l'esempio di libreria che hai usato nei nostri tutorial, in cui vengono già applicati questi principi.
Libreria ha raccolte "scaffale" di risorse "libro", che gli utenti possono
List
, Get
, Create
o Delete
.
Dove configurare la transcodifica
La transcodifica gRPC è abilitata per impostazione predefinita e puoi utilizzarla senza alcuna configurazione. Segui le istruzioni per eseguire il deployment di un servizio utilizzando la transcodifica.
In seguito, quando invii una richiesta HTTP POST
al percorso dell'URL GRPC_SERVICE_FULL_NAME/METHOD_NAME>
con gli eventuali valori del campo del messaggio di richiesta del metodo (se presenti) come JSON nel corpo della richiesta HTTP, l'ESP invia il messaggio della richiesta al metodo gRPC appropriato. Nell'esempio precedente, GRPC_SERVICE_FULL_NAME
è il nome completo del servizio gRPC e METHOD_NAME
è il nome del metodo.
Ad esempio, se invii un POST
all'URL ListShelves
della libreria come segue:
curl -XPOST http://mydomain/endpoints.examples.bookstore.Bookstore/ListShelves
Verrà restituito un elenco aggiornato degli scaffali in formato JSON.
Tuttavia, in termini di progettazione dell'interfaccia HTTP, è vivamente preferibile configurare esplicitamente le mappature, come descritto nel resto di questo documento.
Lo standard di configurazione dell'API gRPC per la configurazione del servizio ti consente di specificare esattamente in che modo i dati devono essere tradotti da HTTP/JSON a gRPC. A questo scopo sono supportati due
meccanismi: annotazioni dirette nel file .proto
e in YAML come parte del file
di configurazione dell'API gRPC. Consigliamo di utilizzare le annotazioni proto
per semplificare la lettura e la manutenzione.
Per ulteriori informazioni sulla configurazione YAML e su quando potrebbe essere necessario utilizzarlo, consulta Configurazione della transcodifica in YAML.
Ecco un esempio utilizzando l'approccio consigliato dalla Libreria:
// Returns a specific bookstore shelf.
rpc GetShelf(GetShelfRequest) returns (Shelf) {
// Client example - returns the first shelf:
// curl http://DOMAIN_NAME/v1/shelves/1
option (google.api.http) = { get: "/v1/shelves/{shelf}" };
}
...
// Request message for GetShelf method.
message GetShelfRequest {
// The ID of the shelf resource to retrieve.
int64 shelf = 1;
}
L'annotazione indica a ESP che l'invio di una richiesta HTTP GET
con l'URL http://mydomain/v1/shelves/1
chiama il metodo GetShelf()
del server gRPC, con un GetShelfRequest
contenente l'ID scaffale richiesto shelf
(in questo caso, 1
).
Aggiunta di mappature di transcodifica
Questa sezione descrive alcune annotazioni di mappatura aggiuntive tratte dall'esempio di Bookstore. Nell'esempio del Bookstore sono presenti due file proto
di esempio in modo che tu possa implementarlo sia con o senza le mappature di transcodifica e confrontare le differenze tra i file proto
:
bookstore.proto
: utilizzato nei tutorial di Endpoints e non ha mappature di transcodifica.http_bookstore.proto
: associazioni di transcodifica aggiunte.
Per una guida più completa alla specifica delle mappature di transcodifica, consulta Metodi standard, Metodi personalizzati e Riferimento alle regole HTTP.
Mappa un metodo List
Il metodo List
è definito nel file .proto
con il suo tipo di risposta:
// Returns a list of all shelves in the bookstore. rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) { // Define HTTP mapping. // Client example (Assuming your service is hosted at the given 'DOMAIN_NAME'): // curl http://DOMAIN_NAME/v1/shelves option (google.api.http) = { get: "/v1/shelves" }; } ... message ListShelvesResponse { // Shelves in the bookstore. repeated Shelf shelves = 1; }
L'annotazione in grassetto specifica la mappatura HTTP per questo metodo.
option (google.api.http)
specifica che questo metodo è un'annotazione di mappatura HTTP gRPC.get
specifica che questo metodo è mappato a una richiesta HTTPGET
."/v1/shelves"
è il modello di percorso dell'URL (aggiunto al dominio del tuo servizio) utilizzato dalla richiestaGET
per chiamare questo metodo. Il percorso dell'URL è anche noto come percorso della risorsa perché in genere specifica l'elemento o la risorsa che vuoi utilizzare. In questo caso, tutte le risorse sugli scaffali della nostra libreria.
Ad esempio, se un client chiama questo metodo inviando un GET
all'URL http://mydomain/v1/shelves
, ESP chiama il metodo gRPC ListShelves()
. Il backend gRPC restituisce quindi gli scaffali, che
ESP converte in formato JSON e restituisce al client.
Mappa un metodo Get
Il metodo GetShelf
del Bookstore è definito nel file .proto
con i suoi tipi di richiesta e risposta:
// Returns a specific bookstore shelf. rpc GetShelf(GetShelfRequest) returns (Shelf) { // Client example - returns the first shelf: // curl http://DOMAIN_NAME/v1/shelves/1 option (google.api.http) = { get: "/v1/shelves/{shelf}" }; } ... // Request message for GetShelf method. message GetShelfRequest { // The ID of the shelf resource to retrieve. int64 shelf = 1; } ... // A shelf resource. message Shelf { // A unique shelf id. int64 id = 1; // A theme of the shelf (fiction, poetry, etc). string theme = 2; }
L'annotazione in grassetto specifica la mappatura HTTP per questo metodo.
option (google.api.http)
specifica che questo metodo è un'annotazione di mappatura HTTP gRPC.get
specifica che questo metodo è mappato a una richiesta HTTPGET
."/v1/shelves/{shelf}"
è il percorso dell'URL della richiesta, come in precedenza, ma specifica/v1/shelves/
e poi{shelf}
. Questa notazione di parentesi graffa indica a ESP che qualsiasi elemento presente in{shelf}
è il valore che deve fornire pershelf
nel parametroGetShelfRequest
del metodo.
Se un client chiama questo metodo inviando un GET
all'URL http://mydomain/v1/shelves/4
, ESP crea un GetShelfRequest
con un valore shelf
pari a 4
, quindi chiama il metodo gRPC GetShelf()
con questo valore. Il backend gRPC restituisce quindi il valore Shelf
richiesto con
l'ID 4
, che ESP converte nel formato JSON e restituisce
al client.
Questo metodo richiede che il client shelf
fornisca un solo valore del campo di richiesta, specificato nel modello di percorso dell'URL con la notazione "capture" con parentesi graffe. Puoi anche acquisire più parti dell'URL,
se necessario, per identificare la risorsa richiesta. Ad esempio, il metodo GetBook
richiede che il cliente specifichi sia l'ID dello scaffale sia l'ID del libro nell'URL:
// Returns a specific book.
rpc GetBook(GetBookRequest) returns (Book) {
// Client example - get the first book from the second shelf:
// curl http://DOMAIN_NAME/v1/shelves/2/books/1
option (google.api.http) = { get: "/v1/shelves/{shelf}/books/{book}" };
}
...
// Request message for GetBook method.
message GetBookRequest {
// The ID of the shelf from which to retrieve a book.
int64 shelf = 1;
// The ID of the book to retrieve.
int64 book = 2;
}
Oltre ai valori letterali e all'acquisizione di parentesi graffe per i valori dei campi, i modelli di percorso dell'URL possono utilizzare caratteri jolly per indicare che qualsiasi elemento in questa parte dell'URL deve essere acquisito. La notazione {shelf}
utilizzata nell'esempio precedente è in realtà una
scorciatoia per {shelf=*}
. Puoi trovare ulteriori informazioni sulle regole per i modelli di percorso nel riferimento alle regole HTTP.
Nel caso di questo tipo di metodo, non esiste un corpo della richiesta HTTP specificato. Puoi
trovare altre linee guida per mappare i metodi Get
, compreso l'utilizzo parametri di ricerca,
in Metodi standard.
Mappa un metodo Create
Il metodo CreateShelf
di The Bookstore viene mappato su HTTP POST
.
// Creates a new shelf in the bookstore. rpc CreateShelf(CreateShelfRequest) returns (Shelf) { // Client example: // curl -d '{"theme":"Music"}' http://DOMAIN_NAME/v1/shelves option (google.api.http) = { post: "/v1/shelves" body: "shelf" }; } ... // Request message for CreateShelf method. message CreateShelfRequest { // The shelf resource to create. Shelf shelf = 1; } ... // A shelf resource. message Shelf { // A unique shelf id. int64 id = 1; // A theme of the shelf (fiction, poetry, etc). string theme = 2; }
option (google.api.http)
specifica che questo metodo è un'annotazione di mappatura HTTP gRPC.post
specifica che questo metodo è mappato a una richiesta HTTPPOST
."/v1/shelves"
è il percorso dell'URL per la richiesta, come in precedenza.body: "shelf"
viene utilizzato nel corpo della richiesta HTTP per specificare la risorsa da aggiungere, in formato JSON.
Ad esempio, se un client ha chiamato questo metodo in questo modo:
curl -d '{"theme":"Music"}' http://DOMAIN_NAME/v1/shelves
ESP utilizza il corpo JSON per creare un valore Shelf
con il tema "Music"
per CreateShelfRequest
, quindi chiama il metodo CreateShelf()
di gRPC. Tieni presente che il client non fornisce il valore id
per Shelf
.
Gli ID scaffale della libreria sono forniti dal servizio durante la creazione di un nuovo scaffale.
Puoi fornire questo tipo di informazioni agli utenti del tuo servizio nella documentazione dell'API.
Usa carattere jolly nel corpo
Il nome speciale *
può essere utilizzato nella mappatura del corpo per indicare che ogni campo non associato al modello di percorso deve essere mappato al corpo della richiesta.
Ciò consente la seguente definizione alternativa del metodo CreateShelf
.
// Creates a new shelf in the bookstore. rpc CreateShelf(CreateShelfRequest) returns (Shelf) { // Client example: // curl -d '{"shelf_theme":"Music", "shelf_size": 20}' http://DOMAIN_NAME/v1/shelves/123 option (google.api.http) = { post: "/v1/shelves/{shelf_id}" body: "*" }; } ... // Request message for CreateShelf method. message CreateShelfRequest { // A unique shelf id. int64 shelf_id = 1; // A theme of the shelf (fiction, poetry, etc). string shelf_theme = 2; // The size of the shelf int64 shelf_size = 3; }
option (google.api.http)
specifica che questo metodo è un'annotazione di mappatura HTTP gRPC.post
specifica che questo metodo è mappato a una richiesta HTTPPOST
."/v1/shelves/{shelf_id}"
è il percorso dell'URL della richiesta. Qualunque cosa sia in{shelf_id}
è il valore del camposhelf_id
inCreateShelfRequest
.body: "*"
viene utilizzato nel corpo della richiesta HTTP per specificare tutti i campi di richiesta rimanenti, ad eccezione dishelf_id
, in questo esempio, che sonoshelf_theme
eshelf_size
. Per i campi del corpo JSON con questi due nomi, i valori verranno utilizzati nei campi corrispondenti diCreateShelfRequest
.
Ad esempio, se un client ha chiamato questo metodo in questo modo:
curl -d '{"shelf_theme":"Music", "shelf_size": 20}' http://DOMAIN_NAME/v1/shelves/123
ESP utilizza il corpo JSON e il modello di percorso per creare un CreateShelfRequest{shelf_id: 123 shelf_theme: "Music" shelf_size: 20}
, quindi lo utilizza per chiamare il metodo CreateShelf()
gRPC. Per maggiori dettagli, consulta la sezione HttpRule.
Configurazione della transcodifica in YAML
In alternativa, puoi specificare le mappature da HTTP a gRPC nel file YAML della configurazione dell'API gRPC anziché nel file .proto
. Potrebbe essere necessario configurare la transcodifica in un file YAML se hai una singola definizione dell'API proto
utilizzata in più servizi, con mappature diverse per ogni servizio.
Il campo rules
nella sezione http
del file YAML specifica come mappare le richieste HTTP/JSON
ai metodi gRPC:
http:
rules:
...
#
# 'GetShelf' is available via the GET HTTP verb and '/shelves/{shelf}' URL
# path, where {shelf} is the value of the 'shelf' field of 'GetShelfRequest'
# protobuf message.
#
# Client example - returns the first shelf:
# curl http://DOMAIN_NAME/v1/shelves/1
#
- selector: endpoints.examples.bookstore.Bookstore.GetShelf
get: /v1/shelves/{shelf}
...
Un esempio più completo dell'utilizzo di questo approccio per il servizio Libreria di esempio
si trova in
api_config_http.yaml
.
Deployment di un servizio che utilizza la transcodifica
Il deployment di un servizio gRPC che utilizza la transcodifica è molto simile a quello di qualsiasi altro servizio gRPC, con una differenza importante. Nei Tutorial, l'esempio necessario per accettare le richieste gRPC dal client di esempio. Tuttavia, se vuoi che la libreria accetti anche le richieste HTTP, devi eseguire una configurazione aggiuntiva per ESP. I client utilizzano il protocollo HTTP1.1
per inviare richieste JSON/HTTP a ESP, quindi ESP deve essere configurato in modo da utilizzare SSL (la porta SSL può supportare entrambi i tipi di richieste) o deve avere una porta speciale attivata per accettare queste chiamate. Il deployment è in gran parte uguale a quello del tutorial per l'ambiente che hai scelto.
Assicurati che venga eseguito il deployment delle regole HTTP
Se hai già scaricato l'esempio di libreria per i
tutorial, tieni presente che devi scaricare una
versione leggermente diversa del file .proto
con annotazioni,
http_bookstore.proto
.
Devi inoltre clonare il repository googleapis
da GitHub prima di eseguire protoc
, poiché è necessario annotations.proto
nel percorso di inclusione.
git clone https://github.com/googleapis/googleapis
GOOGLEAPIS_DIR=<your-local-googleapis-folder>
Quindi creerai un nuovo descrittore .pb
da http_bookstore.proto
quando esegui il deployment della configurazione su Endpoints:
protoc \
--include_imports \
--include_source_info \
--proto_path=${GOOGLEAPIS_DIR} \
--proto_path=. \
--descriptor_set_out=api_descriptor.pb \
http_bookstore.proto
Se stai utilizzando il metodo alternativo per configurare le mappature HTTP nel file YAML della configurazione dell'API gRPC, devi anche assicurarti che venga eseguito il deployment delle regole pertinenti quando esegui il deployment della configurazione su Endpoints. Per fare una prova con il servizio Bookstore, le regole di base si trovano nel file api_config.yaml
e le regole HTTP nel file api_config_http.yaml
:
gcloud endpoints services deploy api_descriptor.pb api_config.yaml api_config_http.yaml
Utilizzo di SSL
Se SSL è abilitato per la comunicazione tra i client e l'ESP, i client possono utilizzare la stessa porta per effettuare chiamate gRPC o HTTP1.1
. Puoi trovare informazioni su come configurare SSL per un servizio Endpoints in Abilitazione di SSL.
Specifica una porta affinché ESP accetti le chiamate SSL utilizzando il flag --ssl_port
nel file di configurazione di Google Kubernetes Engine (GKE) o il comando docker run
(Compute Engine/Docker).
args: [
"--http_port", "8080",
"--ssl_port", "443", # enable SSL port at 443 to serve https requests
"--backend", "grpc://127.0.0.1:8081", # gRPC backend.
"--service", "SERVICE_NAME",
"--rollout_strategy", "managed",
]
Configurazione di una porta HTTP1.1
Se non utilizzi SSL, devi configurare una porta separata per le richieste HTTP1.1
perché gRPC e HTTP1.1
non possono condividere la stessa porta senza SSL. Utilizza il flag --http_port
nel file di configurazione di GKE o il comando docker run
per specificare una porta per accettare le chiamate HTTP1.1
. Se vuoi anche che ESP accetti le chiamate gRPC, devi utilizzare anche il flag --http2_port
per specificare una porta gRPC.
args: [
"--http_port", "8080", # for HTTP 1.1
"--http2_port", "8090", # for gRPC
"--backend", "grpc://127.0.0.1:8081", # gRPC backend.
"--service", "SERVICE_NAME",
"--rollout_strategy", "managed",
]
Chiamata a un servizio utilizzando la transcodifica
Questa sezione descrive la configurazione del servizio e come effettuare chiamate HTTP al servizio.
Configurazione del servizio
Questo presuppone che tu abbia già completato i tutorial del servizio gRPC di base per l'ambiente scelto e che tu disponga di un cluster GKE o di un'istanza di Compute Engine per eseguire l'esempio.
- Innanzitutto, assicurati di aver eseguito su Endpoints il deployment della configurazione del servizio Bookstore abilitato per HTTP, come descritto in Assicurarsi che venga eseguito il deployment delle regole HTTP.
Esegui il deployment del backend e dell'ESP come descritto nel tutorial per la piattaforma scelta, utilizzando il flag
--http_port
per abilitare una porta per le richiesteHTTP1.1
:- Deployment di GKE: segui le istruzioni in Deployment dell'API di esempio e dell'ESP nel cluster, assicurandoti che il flag
"--http_port"
sia specificato nel file di configurazione di GKE. - Deployment di Compute Engine: segui le istruzioni in Esecuzione dell'API e dell'ESP di esempio in un container Docker.
Assicurati che il flag
--http_port
sia specificato nel comandodocker run
durante l'esecuzione del container Docker ESP preconfigurato.
- Deployment di GKE: segui le istruzioni in Deployment dell'API di esempio e dell'ESP nel cluster, assicurandoti che il flag
Effettuare chiamate HTTP al servizio
- Prendi l'indirizzo IP esterno dell'ESP e impostalo su
$ESP_IP
. Effettua la seguente richiesta HTTP con
curl
curl http://$ESP_IP/v1/shelves
(oppure utilizza lo stesso URL con
https://
se utilizzi SSL). Il server risponde con:{"shelves":[{"id":"1","theme":"Fiction"},{"id":"2","theme":"Fantasy"}]}
Se l'output mostra una risposta binaria, controlla la configurazione della porta, perché è possibile che sia stata raggiunta la porta HTTP2 anziché la porta HTTP.
Prova un metodo
Create
.CreateShelf
richiede una chiave API, quindi devi creare una chiave per il progetto e impostarla come$KEY
. Ora chiama:curl -d '{"theme":"Music"}' http://$ESP_IP/v1/shelves?key=$KEY
Se chiami di nuovo
GetShelves
, dovresti vedere la nuova sezione.