Configurazione di Cloud Endpoints

Questa pagina descrive 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é Endpoints utilizza nomi compatibili con il DNS per identificare i servizi, ti consigliamo di utilizzare il nome di dominio o del sottodominio dell'API come nome del servizio. Con questo approccio, il nome del servizio visualizzato nella pagina Endpoint Servizi corrisponde al nome utilizzato nelle richieste alla tua API. Inoltre, se il nome del servizio e il nome di dominio sono uguali, 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, deve soddisfare i seguenti requisiti:
    • Deve iniziare con una lettera minuscola.
    • Non deve terminare con un trattino.
    • Gli altri caratteri possono essere lettere minuscole, numeri o trattini.
    • La lunghezza massima è di 63 caratteri.

Puoi registrare un tuo dominio personalizzato (ad esempio example.com) o utilizzare un dominio gestito da Google.

Utilizzare 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 mondiale, questo requisito garantisce che il nome del servizio sia 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 utilizzare un dominio personalizzato (ad esempio myapi.mycompany.com) di cui disponi dell'autorizzazione all'utilizzo. Prima di eseguire il deployment della configurazione dell'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 maggiori dettagli, consulta la Guida per gli sviluppatori
    .

  2. Compila i buffer di protocollo utilizzando il compilatore protoc per la tua lingua. 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 corrente. Nell'ambiente di compilazione gRPC, se utilizzi una directory diversa per i file di input .proto, modifica --proto_path in modo che il compilatore esegua la ricerca nella directory in cui hai salvato il file .proto.

    Se il comando protoc per generare il file descrittore non va a buon fine, assicurati che:

    • La versione di protoc è aggiornata.
    • Hai specificato --proto_path o il relativo formato breve -I per le directory principali dei file .proto importati. Scopri di più nella documentazione relativa ai buffer di protocollo.
    • Hai specificato --include_imports.

    Se vuoi che i tuoi client accedano al tuo servizio gRPC utilizzando HTTP con JSON, devi specificare in che modo i dati vengono tradotti da HTTP con JSON a gRPC. Ti consigliamo di annotare le API definite nel tuo 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. In questo file specifichi il nome del servizio e le restrizioni di utilizzo, ad esempio la richiesta di una chiave API. Puoi utilizzare il file api_config.yaml dell'esempio Libreria come modello.

  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 Endpoints > Servizi nella console Google Cloud. Ad esempio:

    title: Bookstore gRPC API

  4. Inserisci il nome dell'API nel campo apis:name. Il testo inserito 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 saperne di più, consulta la sezione Regole e selettori.

Passaggi successivi

Altri esempi gRPC