Configurazione di un servizio gRPC

Per creare un servizio gRPC, indipendentemente dall'utilizzo o meno di API Gateway, devi specificare la definizione dell'interfaccia in uno o più file proto, ovvero file di testo 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 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 consente di definire il comportamento di un servizio gRPC, tra cui autenticazione, quote e 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:

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 generalmente a una .proto messaggio in cui configuri i vari aspetti del servizio. Ad esempio:

  • authentication: specifica in che modo 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 REST HTTP.
  • usage: consente di attivare e disattivare in modo selettivo la convalida delle chiavi API.

Lo schema ufficiale per la configurazione del servizio è definito dall'.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 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: *.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'APIendpoints.examples.bookstore.Bookstore, come definito nel filebookstore.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 configurazione associata alla 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 (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 della chiave 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'utilizzo di più file YAML semplifica il riutilizzo dei file e la loro modifica per ambienti diversi. Ad esempio, nel sample Libreria, la configurazione di base è specificata nel file api_config.yaml e le relative regole HTTP sono specificate nel file 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 servizio, quando la configurazione viene implementata, ogni file viene convertito in messaggi proto google.api.Service e tutti i messaggi vengono uniti utilizzando la semantica di unione di proto. In altre parole, tutti i campi scalari singolari nell'ultima istanza sostituiscono quelli della precedente. 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.

Passaggi successivi