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 DNS per identificare i servizi, ti consigliamo di utilizzare il nome di dominio o il nome del sottodominio della tua API come nome del servizio. Con questo approccio, il nome del servizio visualizzato nella pagina Servizi endpoint corrisponde al nome utilizzato nelle richieste alla tua API. Endpoints ha i seguenti requisiti per il nome del servizio:

  • The maximum length of the domain name is 253 characters.
  • The domain name must start with a lowercase letter.
  • Each section in the domain name, which is delimited by dots, has the following requirements:
    • Must start with a lowercase letter.
    • Must not end with a dash.
    • The remaining characters can be lowercase letters, numbers, or dashes.
    • The maximum length is 63 characters.

Puoi registrare un tuo dominio personalizzato (ad esempio example.com) oppure 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 globale, questo requisito garantisce che tu abbia 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 della tua API e YOUR_PROJECT_ID è il tuo ID progettoGoogle Cloud :

YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog`

Per utilizzare questo dominio come nome di dominio dell'API, leggi Configurazione del DNS sul 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) per cui disponi dell'autorizzazione. 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 ulteriori dettagli, consulta la Guida per gli sviluppatori
    .

  2. Compila i protocol buffer utilizzando il protoc compiler 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 cerchi la 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 la sua forma abbreviata -I per le directory radice dei file .proto importati. Per scoprire di più, consulta la documentazione sui buffer di protocollo.
    • Hai specificato --include_imports.

    Se vuoi che i tuoi 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 tuo file .proto. Per saperne di più, leggi 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 l'obbligo di una chiave API. Puoi utilizzare il file api_config.yaml dell'esempio della libreria come modello.

  1. Salva una copia di api_config.yaml.

  2. Inserisci il nome del tuo 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 API completo del 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ù, leggi Regole e selettori.

Passaggi successivi

Altri esempi di gRPC