Configurazione di Cloud Endpoints

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:

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 dominio cloud.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

  1. Crea un file .proto per il tuo servizio. Per informazioni dettagliate, leggi la Guida per gli sviluppatori
    .

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

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.

  1. Salva una copia di api_config.yaml.

  2. Inserisci il nome del servizio nel campo name. Ad esempio:

    name: bookstore.endpoints.example-project-12345.cloud.goog

  3. Inserisci il titolo visualizzato nella pagina Endpoint > Servizi nella console Google Cloud. Ad esempio:

    title: Bookstore gRPC API

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

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

Esempi di gRPC aggiuntivi