Configurazione di Cloud Endpoints

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Cloud Endpoints supporta le API descritte utilizzando la versione 2.0 della specifica OpenAPI. Descrivi la piattaforma dell'API e configura le funzionalità di endpoint come le regole di autenticazione o le quote in un documento OpenAPI.

Gli endpoint fanno un uso speciale dei seguenti campi obbligatori nel documento OpenAPI:

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

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

Prerequisiti

Come punto di partenza, in questa pagina si presuppone che tu disponga di:

host

Cloud Endpoints utilizza il nome configurato 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 il sottodominio del tuo API come il nome del servizio. Con questo approccio, il nome del servizio visualizzato nella pagina Endpoint 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. Gli endpoint hanno 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 dominio personalizzato (ad esempio example.com) oppure 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 il tuo ID progetto Google Cloud come parte del nome del servizio. Poiché i progetti Google Cloud hanno un ID progetto globalmente univoco, questo requisito garantisce che tu abbia 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 essere nel seguente formato, 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 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 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 la pagina sulla 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) per cui disponi dell'autorizzazione necessaria. 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 intuitivo per la tua API. Nella pagina Endpoint > Servizi di Google Cloud Console viene visualizzato il testo che hai configurato nel campo info.title. Se hai più di un'API per progetto Cloud, il nome API viene visualizzato in un elenco quando apri la pagina per la prima volta. 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

Nella pagina Endpoint > Servizi di Google Cloud Console viene visualizzato il numero di versione della tua API. Prima di eseguire il deployment della configurazione dell'API per la prima volta:

  • Imposta il numero di versione nel campo info.version sulla versione dell'API applicabile, 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 la pagina sulla gestione del ciclo di vita delle API.

operationId

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

Passaggi successivi