Cloud Endpoints supporta le API descritte utilizzando la versione 2.0 della specifica OpenAPI. Descrivi la superficie dell'API e configura funzionalità endpoint 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 gli endpoint utilizzano i campi precedenti. Con queste informazioni, puoi completare la preparazione del documento OpenAPI per il deployment.
Prerequisiti
Come punto di partenza, questa pagina presuppone che tu disponga di:
- Un progetto Google Cloud.
- Conoscenza di base di OpenAPI.
- Un documento OpenAPI nel formato descritto nella documentazione di swap di base della struttura.
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. Dal momento che gli endpoint utilizzano nomi compatibili con DNS per identificare i servizi, ti consigliamo di utilizzare il nome di dominio o il nome del sottodominio dell'API come nome del servizio. Con questo approccio, il nome del servizio visualizzato nella pagina Endpoint Servizi corrisponde al nome utilizzato nelle richieste alla tua 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. 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 il tuo dominio personalizzato (ad esempio example.com
) oppure
usare un dominio gestito da Google.
Utilizza un dominio gestito da Google
Google possiede e gestisce i dominicloud.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 univoco a livello globale, questo requisito garantisce che tu abbia un nome di servizio univoco.
Il nome di dominio che utilizzi dipende dal backend che ospita la tua 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, doveYOUR_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
, mentre il nome del servizio deve essere nel seguente formato, doveYOUR_API_NAME
è il nome della tua API:YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
Per utilizzare questo dominio come nome di dominio API, leggi 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 facile da usare per l'API. Nella pagina Endpoint > Servizi in Google Cloud Console viene visualizzato il testo che hai configurato nel campo info.title
. Se hai più di un'API per progetto Cloud, quando apri la pagina per la prima volta, il nome API viene visualizzato in un elenco. 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
Nella pagina Endpoint > Servizi in 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 API applicabile, ad esempio1.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 relativa alla gestione del ciclo di vita delle API.
operationId
Anche se operationId
è un campo facoltativo nella specifica OpenAPI,
gli endpoint lo richiedono perché viene utilizzato per l'identificazione
interna dell'operazione. La stringa utilizzata per operationId
deve essere univoca all'interno dell'API. Per indicazioni sulla denominazione, consulta la descrizione di operationId
nella specifica OpenAPI.
Passaggi successivi
- Eseguire il deployment della configurazione degli endpoint
- Deployment del backend dell'API
- Configurare l'autenticazione