Configurare un servizio gRPC

Per creare un servizio gRPC, indipendentemente dal fatto che tu stia utilizzando o meno API Gateway, devi specificare la definizione dell'interfaccia in uno o più proto file, che sono file di testo con estensione .proto. In un file proto, definisci la superficie della tua API, incluse le strutture di dati, i metodi, i parametri dei metodi e i tipi restituiti. Poi, compila il file proto utilizzando il compilatore di buffer di protocollo specifico per la lingua, protoc. Per saperne di più, consulta Che cos'è gRPC? e Concetti di gRPC.

Per fare in modo che il tuo servizio gRPC venga gestito da API Gateway, oltre al file proto compilato, devi specificare una configurazione del servizio in uno o più file YAML. Una configurazione del servizio è una specifica che ti consente di definire il comportamento di un servizio gRPC, inclusi autenticazione, quote e altro ancora.

Panoramica della configurazione del servizio

Nella parte superiore del file YAML, puoi specificare informazioni di base sul servizio, come il nome e il titolo. Altri aspetti del servizio vengono configurati nelle sottosezioni del file YAML, ad esempio:

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 in genere corrisponde a un .proto messaggio in cui configuri vari aspetti del servizio. Ad esempio:

  • authentication: specifica come vengono autenticati i chiamanti.
  • backend: controlla il routing del backend remoto.
  • http: definisce le regole per mappare un metodo RPC a uno o più metodi API HTTP REST.
  • usage: consente di attivare e disattivare selettivamente la convalida della chiave API.

Lo schema ufficiale per la configurazione del servizio è definito dal .proto messaggio google.api.Service.

Configurazione di base

L' esempio di libreria, utilizzato nel tutorial Introduzione ad API Gateway e Cloud Run per gRPC, include un file di definizione dell'interfaccia di base e un file di configurazione del servizio.

La definizione dell'interfaccia della 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;
}

La configurazione del servizio della 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 perché:

  • Definisce un servizio denominato *.apigateway.PROJECT_ID.cloud.goog dove PROJECT_ID è il nome dell'ID progetto. Google Cloud
  • Specifica che il servizio espone l'API endpoints.examples.bookstore.Bookstore, come definito nel file bookstore.proto.

Regole e selettori

In alcuni casi, potresti aver bisogno di associare la configurazione a singoli elementi di un servizio, ad esempio per applicare l'autenticazione a determinati metodi, ma non ad altri. Per configurare questa opzione nella configurazione del servizio, alcune parti della configurazione del servizio, come authentication e http, consentono di specificare regole e selettori. Un selettore identifica gli elementi del servizio, ad esempio un nome di metodo a cui si applica la configurazione associata alla regola.

Un selettore è un elenco separato da virgole di nomi qualificati definiti nel servizio: metodo, messaggio, campo, enum o valori 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.* è consentito, 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 della chiave API per tutti i metodi tranne il metodo ListShelves.

Le regole vengono valutate in sequenza e viene applicata l'ultima regola corrispondente nell'ordine di dichiarazione.

Quote

Per applicare una quota al tuo servizio gRPC, definisci le metriche nella sezione di primo livello metrics della configurazione del servizio, i limiti in quota.limits e il costo di ogni metodo in quota.metric_rules. Ad esempio:

metrics:
  - name: "read-requests"
    display_name: "Read requests"
    value_type: INT64
    metric_kind: DELTA
quota:
  limits:
    - name: "read-limit"
      metric: "read-requests"
      unit: "1/min/{project}"
      values:
        STANDARD: 1000
  metric_rules:
    - selector: "endpoints.examples.bookstore.Bookstore.ListShelves"
      metric_costs:
        "read-requests": 1

Per istruzioni dettagliate su ciascuno di questi campi, consulta la documentazione di Cloud Endpoints alla pagina Configurare le quote.

Utilizzare più file YAML

Potrebbe essere utile utilizzare più file YAML per configurare funzionalità diverse per lo stesso servizio. L'utilizzo di più file YAML semplifica il riutilizzo e la modifica dei file per ambienti diversi. Ad esempio, nell' esempio della libreria, la configurazione di base è specificata nel api_config.yaml file e le regole HTTP sono specificate nel api_config_http.yaml file. In questo modo, puoi eseguire il deployment delle regole HTTP solo se vuoi attivare la transcodifica JSON/HTTP in gRPC per la libreria.

Se utilizzi più file YAML per la configurazione del servizio, quando la configurazione viene eseguito il deployment ogni file viene convertito in google.api.Service messaggi proto, quindi tutti i messaggi vengono uniti utilizzando la semantica di unione proto. In altre parole, tutti i campi scalari singoli nell'istanza successiva sostituiscono quelli nell'istanza precedente. Pertanto, se fornisci valori singoli diversi per la stessa regola in due file, viene utilizzato il valore nel secondo file specificato durante il deployment della configurazione. I messaggi incorporati singoli vengono uniti e i campi ripetuti vengono concatenati.

Come 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 la configurazione delle opzioni HTTP, puoi configurarle direttamente nel file proto utilizzando il meccanismo delle opzioni. Le annotazioni API sono definite in annotations.proto.

Utilizza le annotazioni se l'opzione di configurazione è destinata a essere invariante in tutti gli utilizzi della definizione dell'interfaccia del buffer di protocollo. Ad esempio, se un'API ha una singola 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 sia nel file YAML di configurazione del servizio, la configurazione del servizio sostituisce l'annotazione.

Esempio di annotazione 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 saperne di più, consulta Transcodifica di HTTP/JSON in gRPC.

Passaggi successivi