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 che configuri File YAML di configurazione API gRPC come nome del tuo servizio.

Il nome del servizio API deve essere univoco su Google Cloud. Poiché Endpoints utilizza nomi compatibili con DNS per identificare i servizi. consigliamo di utilizzare il nome di dominio o il nome del sottodominio dell'API come servizio nome. Con questo approccio, il nome del servizio visualizzato nella sezione Endpoint Servizi corrisponda al nome utilizzato nelle richieste all'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, ha quanto segue: 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 del e l'API YOUR_PROJECT_ID è il tuo 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 sul 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 disponi dell'autorizzazione a utilizzare. Prima di eseguire il deployment della configurazione dell'API, segui i passaggi descritti in Verifica la proprietà del dominio.

Configurazione del buffer di protocollo

  1. Crea un file .proto per il tuo servizio. Leggi Guida per gli sviluppatori
    per maggiori dettagli.

  2. Compila i buffer di protocollo utilizzando il comando 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. Nel tuo ambiente di build gRPC, se utilizzi una directory diversa per .proto file di input, modifica --proto_path in modo che il compilatore cerchi 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 tua versione di protoc è aggiornata.
    • Hai specificato --proto_path o la sua forma abbreviata -I per le directory principali dei file .proto importati. Puoi scoprire di più nel 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 la modalità di traduzione dei dati HTTP con JSON a gRPC. Ti consigliamo di annotare le API definite nel tuo file .proto. Letto Transcodifica di HTTP/JSON in gRPC per ulteriori informazioni.

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

    Leggi l'articolo Regole e selettori. per ulteriori informazioni.

Passaggi successivi

Altri esempi gRPC