Configurazione di Cloud Endpoints

Cloud Endpoints supporta le API descritte utilizzando la versione 2.0 di la specifica OpenAPI. Descrivi la superficie dell'API e configurare le funzionalità di Endpoints come regole di autenticazione o quote in un Documento OpenAPI.

Endpoints utilizza in modo speciale i 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 tuo documento OpenAPI 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. 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:

  • 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 il tuo dominio personalizzato (ad esempio example.com) oppure puoi usare 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 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 il nome del servizio sia 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 utilizza il dominio appspot.com e il nome del servizio deve essere nel seguente dove YOUR_PROJECT_ID è il tuo ID progetto Google Cloud:

    YOUR_PROJECT_ID.appspot.com

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

  • Per le API ospitate su Compute Engine, Google Kubernetes Engine o Kubernetes, devi utilizzare il dominio cloud.goog e il nome del servizio deve essere nel seguente formato, 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 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) 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.

info.title

Il campo info.title è un nome facile da usare per l'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 quando apri prima la pagina. Puoi fare clic sul nome dell'API per aprire un'altra pagina che mostra le metriche dell'API, la cronologia del deployment e altre informazioni.

info.version

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

  • Imposta il numero di versione nel campo info.version sul valore Versione API, ad esempio 1.0.

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

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

operationId

Sebbene operationId sia un campo facoltativo nella specifica OpenAPI, Endpoint richiede questo campo perché viene utilizzato per per identificare l'operazione. La stringa utilizzata per operationId deve essere univoca all'interno dell'API. Leggi la descrizione di operationId nella specifica OpenAPI per indicazioni sulla denominazione.

Passaggi successivi