In questa pagina vengono descritti i file di configurazione necessari per creare un servizio gRPC gestito da Endpoints.
Prerequisiti
Per iniziare, questa pagina presuppone che tu abbia:
- Un progetto Google Cloud.
- Conoscenza di base della configurazione di un servizio API gRPC.
- Ha installato gli strumenti gRPC e gRPC. Per i dettagli, consulta la Guida introduttiva all'utilizzo di gRPC.
Scegliere il nome del servizio
Cloud Endpoints utilizza il nome configurato nel file YAML di configurazione dell'API gRPC come nome del servizio.Il nome del servizio API deve essere univoco su Google Cloud. Poiché gli endpoint utilizzano nomi compatibili con DNS per identificare i servizi, ti consigliamo di utilizzare il nome di dominio o di sottodominio dell'API come nome di servizio. Con questo approccio, il nome del servizio visualizzato nella pagina Servizi endpoint corrisponde a quello utilizzato nelle richieste all'API. Inoltre, se il nome del servizio e il nome di dominio sono gli stessi, puoi creare un portale Cloud Endpoints per gli utenti dell'API. Endpoints ha i seguenti requisiti per il nome del servizio:
- La lunghezza massima del nome di dominio è 253 caratteri.
- Il nome di dominio deve iniziare con una lettera minuscola.
-
Ogni sezione del nome di dominio, delimitata da punti, ha i seguenti
requisiti:
- Deve iniziare con una lettera minuscola.
- Non deve terminare con un trattino.
- I caratteri rimanenti possono essere lettere minuscole, numeri o trattini.
- La lunghezza massima è di 63 caratteri.
Puoi registrare un dominio personalizzato (ad esempio example.com
) oppure
utilizzare un dominio gestito da Google.
Utilizza un dominio gestito da Google
Google possiede e gestisce il dominiocloud.goog
. Se vuoi utilizzare un dominio gestito da Google, devi utilizzare l'ID progetto Google Cloud come parte del nome del servizio. Poiché i progetti Google Cloud hanno un ID progetto univoco a livello globale, questo requisito garantisce di avere un nome di servizio univoco.
Se vuoi utilizzare il dominio cloud.goog
, il nome del servizio deve essere nel formato, dove YOUR_API_NAME
è il nome dell'API e YOUR_PROJECT_ID
è l'ID progetto Google Cloud:
YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog`
Per utilizzare questo dominio come nome di dominio dell'API, leggi
Configurazione del DNS nel dominio cloud.goog
.
Utilizzo di un dominio personalizzato
Se non vuoi utilizzare un dominio gestito da Google, puoi usare un dominio personalizzato
(ad esempio, myapi.mycompany.com
) che hai l'autorizzazione a utilizzare.
Prima di eseguire il deployment della configurazione API, segui i passaggi descritti in Verificare la proprietà del dominio.
Configurazione del buffer di protocollo
Crea un file
.proto
per il tuo servizio. Per informazioni dettagliate, leggi la Guida per gli sviluppatori
.Compila i buffer di protocollo utilizzando il compilatore
protoc
per il tuo linguaggio. Ad esempio:protoc --proto_path=. \ --include_imports \ --include_source_info \ --descriptor_set_out=api_descriptor.pb \ bookstore.proto
Nel comando precedente,
--proto_path
è impostato sulla directory di lavoro attuale. Se utilizzi una directory diversa per i file di input.proto
nel tuo ambiente di build gRPC, modifica--proto_path
in modo che il compilatore cerchi nella directory in cui hai salvato il file.proto
.Se il comando
protoc
per generare il file descrittore ha esito negativo, assicurati che:- La tua versione di
protoc
è aggiornata. - Hai specificato
--proto_path
o la sua forma breve-I
per le directory principali dei file.proto
importati. Puoi trovare ulteriori informazioni nella documentazione relativa ai buffer di protocollo. - Hai specificato
--include_imports
.
Se vuoi che i client accedano al tuo servizio gRPC utilizzando HTTP con JSON, devi specificare come vengono tradotti i dati da HTTP con JSON a gRPC. Ti consigliamo di annotare le API definite nel file
.proto
. Per ulteriori informazioni, consulta Transcodifica di HTTP/JSON in gRPC.- La tua versione di
Configurazione del file di configurazione del servizio gRPC
Devi creare un file YAML di configurazione del servizio gRPC. Puoi specificare il nome del servizio e le limitazioni di utilizzo, ad esempio la richiesta di una chiave API in questo file.
Puoi utilizzare come modello il file api_config.yaml
dall'esempio di Bookstore.
Salva una copia di
api_config.yaml
.Inserisci il nome del servizio nel campo
name
. Ad esempio:name: bookstore.endpoints.example-project-12345.cloud.goog
Inserisci il titolo visualizzato nella pagina Endpoint > Servizi nella console Google Cloud. Ad esempio:
title: Bookstore gRPC API
Inserisci il nome dell'API nel campo
apis:name
. Il testo che inserisci deve corrispondere esattamente al nome completo dell'API nel file.proto
. Ad esempio:apis: - name: endpoints.examples.bookstore.Bookstore
Configura il resto del file. Ad esempio:
# # API usage restrictions. # usage: rules: # ListShelves methods can be called without an API Key. - selector: endpoints.examples.bookstore.Bookstore.ListShelves allow_unregistered_calls: true
Per ulteriori informazioni, consulta Regole e selettori.
Passaggi successivi
- Deployment della configurazione di Endpoints
- Deployment del backend dell'API
- Configurazione dell'autenticazione
Esempi di gRPC aggiuntivi
- Versione Java dell'esempio di Bookstore.
L'esempio
getting-started-grpc
è disponibile su GitHub nelle seguenti lingue: