Transcodifica di HTTP/JSON in gRPC

OpenAPI   |  gRPC

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.

Avviso: l'utilizzo del metodo HTTP POST con il percorso dell'URL GRPC_SERVICE_FULL_NAME/METHOD_NAME> è supportato per impostazione predefinita. Non aggiungere un'altra mappatura per questo metodo nell'annotazione google.api.http del file di protocollo o nella sezione http.rules del file YAML della configurazione del servizio. Questo genererà un errore di "pattern http duplicato".

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 HTTP GET.
• "/v1/shelves" è il modello di percorso dell'URL (aggiunto al dominio del tuo servizio) utilizzato dalla richiesta GET 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 HTTP GET.
• "/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 per shelf nel parametro GetShelfRequest 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 HTTP POST.
• "/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 HTTP POST.
• "/v1/shelves/{shelf_id}" è il percorso dell'URL della richiesta. Qualunque cosa sia in {shelf_id} è il valore del campo shelf_id in CreateShelfRequest.
• body: "*" viene utilizzato nel corpo della richiesta HTTP per specificare tutti i campi di richiesta rimanenti, ad eccezione di shelf_id, in questo esempio, che sono shelf_theme e shelf_size. Per i campi del corpo JSON con questi due nomi, i valori verranno utilizzati nei campi corrispondenti di CreateShelfRequest.

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

Nota: (ESPv2) non supporta questo approccio.

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

Il comando gcloud riportato sopra supporta solo un descrittore di proto file e deve essere il primo file negli argomenti del comando gcloud. Se disponi di più servizi gRPC in file proto diversi, utilizza lo strumento a riga di comando "protoc" per combinarli in un unico file descrittore.

Utilizzo di SSL

Nota: è necessario solo per ESPv1. (ESPv2) --listener_port funziona sia per http che per grpc.

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

Nota: è necessario solo per ESPv1. (ESPv2) --listener_port funziona sia per http che per grpc.

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.

1. 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.

2. 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 richieste HTTP1.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 comando docker run durante l'esecuzione del container Docker ESP preconfigurato.

Effettuare chiamate HTTP al servizio

Nota: ogni campo fornito in un messaggio di richiesta deve contenere un valore valido. Ad esempio, se un messaggio di richiesta proto include il campo int64 book_id, devi specificare un valore intero valido o rimuovere completamente il campo. Ad esempio, mygateway.dev?book_id=0 contiene un valore valido, ma mygateway.dev?book_id= non lo contiene e deve essere rimosso o fornire un valore intero valido.

1. Prendi l'indirizzo IP esterno dell'ESP e impostalo su $ESP_IP.

2. 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.

3. 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.