Configurazione di Cloud Endpoints

Cloud Endpoints supporta le API descritte utilizzando la versione 2.0 della specifica OpenAPI. Descrivi la superficie delle API e configuri le funzionalità degli endpoint, come le regole di autenticazione o le quotas in un documento OpenAPI.

Endpoints utilizza un uso speciale dei seguenti campi obbligatori nel documento OpenAPI:

  • host
  • info.title
  • info.version
  • operationId

Questa pagina fornisce informazioni su come Endpoints utilizza i campi precedenti. Con queste informazioni, puoi completare la preparazione del documento OpenAPI per il deployment.

Prerequisiti

Per iniziare, questa pagina presuppone che tu abbia:

host

Cloud Endpoints utilizza il nome che configuri nel campo host del documento OpenAPI 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 è di 253 caratteri.
  • Il nome di dominio deve iniziare con una lettera minuscola.
  • Ogni sezione del nome di dominio, delimitata da punti, prevede 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 i domini cloud.goog e appspot.com. 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.

Il nome di dominio che utilizzi dipende dal backend che ospita l'API:

  • Per le API ospitate nell'ambiente flessibile di App Engine, devi utilizzare il dominio appspot.com e il nome del servizio deve avere il formato seguente, dove YOUR_PROJECT_ID è l'ID progetto Google Cloud:

    YOUR_PROJECT_ID.appspot.com

    Quando esegui il deployment dell'API in App Engine, viene creata automaticamente una voce DNS con un nome nel formato YOUR_PROJECT_ID.appspot.com.

  • Per le API ospitate su Compute Engine, Google Kubernetes Engine o Kubernetes, devi utilizzare il dominio cloud.goog e il nome del servizio deve avere il formato seguente, dove YOUR_API_NAME è il nome della tua API:

    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.

info.title

Il campo info.title è un nome facile da usare per la tua API. La pagina Endpoint > Servizi nella console Google Cloud mostra il testo configurato nel campo info.title. Se hai più di un'API per progetto Google Cloud, il nome dell'API viene visualizzato in un elenco alla prima apertura della pagina. Puoi fare clic sul nome dell'API per aprire un'altra pagina che mostra le metriche, la cronologia dei deployment e altre informazioni dell'API.

info.version

La pagina Endpoint > Servizi nella console Google Cloud mostra il numero di versione dell'API. Prima di eseguire il deployment della configurazione API per la prima volta:

  • Imposta il numero di versione nel campo info.version sulla versione applicabile dell'API, ad esempio 1.0.

  • Imposta il campo basePath sul numero di versione principale, ad esempio /v1.

Per ulteriori informazioni sul controllo delle versioni dell'API, consulta Gestione del ciclo di vita delle API.

operationId

Sebbene operationId sia un campo facoltativo della specifica OpenAPI, Endpoints richiede questo campo perché viene utilizzato per l'identificazione interna dell'operazione. La stringa che utilizzi per operationId deve essere univoca all'interno dell'API. Per indicazioni sulla denominazione, consulta la descrizione di operationId nella specifica OpenAPI.

Passaggi successivi