Questa pagina mostra come configurare, eseguire il deployment e inviare richieste a un'API di esempio utilizzando Cloud Endpoints Frameworks per Java. Endpoints Frameworks per Java è integrato con l'ambiente di runtime Java 8 standard di App Engine. I framework Endpoints sono costituiti da strumenti, librerie e funzionalità che ti consentono di generare API e librerie client da un'applicazione App Engine.
Obiettivi
Segui il seguente elenco di attività di alto livello durante il tutorial. Tutte le attività sono necessarie per inviare correttamente le richieste all'API.
- Configurare un progetto Google Cloud. Vedi Prima di iniziare.
- Installa il software necessario e crea un'applicazione App Engine. Consulta Installare e configurare il software necessario.
- Scarica il codice campione. Consulta Recupero del codice di esempio.
- Genera un file di configurazione OpenAPI. Consulta Configurazione di Cloud Endpoints.
- Esegui il deployment della configurazione di Endpoints per creare un servizio Endpoints. Consulta Eseguire il deployment della configurazione di Endpoints.
- Esegui il sample sul computer. Consulta Eseguire l'esempio localmente.
- Crea un backend per pubblicare l'API e esegui il deployment dell'API. Consulta Esegui il deployment del backend dell'API.
- Invia una richiesta all'API. Consulta Invio di una richiesta all'API.
- Monitora l'attività dell'API. Consulta Monitorare l'attività dell'API.
- Evita che al tuo account Google Cloud vengano addebitati costi. Consulta Pulizia.
Costi
In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:
Per generare una stima dei costi in base all'utilizzo previsto,
utilizza il Calcolatore prezzi.
Al termine delle attività descritte in questo documento, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori informazioni, consulta la sezione Pulizia.
Prima di iniziare
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
- Prendi nota dell'ID progetto perché ti servirà in seguito.
Installazione e configurazione del software necessario
- Se non hai installato Java 8, scarica il Java Development Kit (JDK) da Oracle e installalo. Poiché Endpoints Frameworks per Java dipende dall'ambiente di runtime Java 8 standard di App Engine, Endpoints Frameworks non supporta altre versioni di Java.
- Se non hai Maven 3.3.9 o versioni successive, scarica e installalo.
-
Devi disporre di un'applicazione per inviare richieste all'API di esempio.
- Utenti Linux e macOS: questo tutorial fornisce un esempio di utilizzo di
curl
, che in genere è preinstallato nel sistema operativo. Se non haicurl
, puoi scaricarlo dallacurl
pagina Release e download. - Utenti Windows: questo tutorial fornisce un esempio di utilizzo di
Invoke-WebRequest
, supportato in PowerShell 3.0 e versioni successive.
- Utenti Linux e macOS: questo tutorial fornisce un esempio di utilizzo di
- Scarica e inizializza Google Cloud CLI.
- Esegui i seguenti comandi:
- Assicurati che gcloud CLI sia autorizzata ad accedere ai tuoi dati e servizi su Google Cloud:
gcloud auth login
- Utilizza le credenziali predefinite dell'applicazione:
gcloud auth application-default login
- Installa il componente
app-engine-java
di Google Cloud SDK:gcloud components install app-engine-java
- Esegui l'aggiornamento alla versione più recente di Google Cloud SDK e di tutti i componenti:
gcloud components update
- Assicurati che gcloud CLI sia autorizzata ad accedere ai tuoi dati e servizi su Google Cloud:
- Crea un'applicazione App Engine:
-
Imposta il progetto predefinito sul tuo ID progetto.
gcloud config set project YOUR_PROJECT_ID
Sostituisci
YOUR_PROJECT_ID
con l'ID del tuo progetto Google Cloud. Se hai altri progetti Google Cloud e vuoi utilizzarli congcloud
per gestirli, consulta Gestire la gcloud CLI gcloud. - Seleziona la regione in cui vuoi creare l'applicazione App Engine. Esegui il
seguente comando per ottenere un elenco di regioni:
gcloud app regions list
- Crea un'applicazione App Engine utilizzando il seguente comando.
Sostituisci
YOUR_PROJECT_ID
con l'ID del tuo progetto Google Cloud eYOUR_REGION
con la regione in cui vuoi creare l'applicazione App Engine.gcloud app create \ --project=YOUR_PROJECT_ID \ --region=YOUR_REGION
-
Imposta il progetto predefinito sul tuo ID progetto.
Nota per gli utenti Windows: se stai installando JDK e Maven su Windows, installali in una directory che non contenga spazi nel percorso. Per ulteriori informazioni, consulta Maven su Windows.
recupera il codice di esempio
Per clonare l'API di esempio da GitHub:
Clona il repository di esempio sulla tua macchina locale:
git clone https://github.com/GoogleCloudPlatform/java-docs-samples
Passa alla directory che contiene il codice campione:
cd java-docs-samples/appengine-java8/endpoints-v2-backend
Configurazione di Endpoints
Il codice campione include lo strumento Endpoints Frameworks che genera un file di configurazione OpenAPI che descrive l'API REST del codice campione. Segui i passaggi in questa sezione per configurare e compilare il progetto Maven di esempio in modo da poter poi generare il file di configurazione OpenAPI.
Aggiunta dell'ID progetto al codice API di esempio
Prima di poter eseguire il deployment del codice, devi aggiungere l'ID progetto ottenuto quando hai creato il progetto al pom.xml
del Sample.
Per aggiungere l'ID progetto:
Modifica il file
java-docs-samples/appengine-java8/endpoints-v2-backend/pom.xml
.Cerca
<endpoints.project.id>
e sostituisciYOUR_PROJECT_ID
con il tuo ID progetto Google Cloud.Ad esempio:
<endpoints.project.id>example-project</endpoints.project.id>
Salva le modifiche.
Creazione del progetto di esempio
Per compilare il progetto:
Assicurati di trovarti nella directory
java-docs-samples/appengine-java8/endpoints-v2-backend
.Esegui questo comando:
mvn clean package
Attendi il completamento della compilazione del progetto. Al termine del progetto, viene visualizzato un messaggio simile al seguente:
[INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 14.846s [INFO] Finished at: Wed April 13 09:43:09 PDT 2016 [INFO] Final Memory: 24M/331M
Generazione del file di configurazione OpenAPI
Utilizzi uno strumento della libreria Endpoints Frameworks per generare un
documento OpenAPI denominato openapi.json
. Questo file descrive l'API REST del codice campione.
Per generare il file di configurazione OpenAPI:
Richiama lo strumento Endpoints Frameworks utilizzando questo comando:
mvn endpoints-framework:openApiDocs
Attendi il completamento della compilazione delle specifiche di configurazione. Al termine, viene visualizzato un messaggio simile al seguente:
OpenAPI document written to target/openapi-docs/openapi.json
Ignora eventuali messaggi relativi al mancato caricamento di una classe di logger statica.
esegui il deployment della configurazione di Endpoints
Per eseguire il deployment della configurazione di Endpoints, utilizzi Service Infrastructure, la piattaforma di servizi di base di Google, utilizzata dai framework Endpoints e da altri servizi per creare e gestire API e servizi.
Per eseguire il deployment del file di configurazione:
Assicurati di trovarti nella directory
java-docs-samples/appengine-java8/endpoints-v2-backend
.Esegui il deployment del file di configurazione OpenAPI generato nella sezione precedente:
gcloud endpoints services deploy target/openapi-docs/openapi.json
Viene creato un nuovo servizio Endpoints con il nome nel formatoYOUR_PROJECT_ID.appspot.com
. Questo nome è configurato in
pom.xml
e in altri file di configurazione inclusi nel sample. Tieni presente che quando esegui il deployment dell'API su App Engine, viene creato un record DNS utilizzando il formato del nome YOUR_PROJECT_ID.appspot.com
, ovvero il nome di dominio completo (FQDN) che utilizzi per inviare richieste all'API.
Durante la creazione e la configurazione del servizio, Service Management visualizza informazioni sul terminale. Puoi ignorare tranquillamente gli avvisi
sui percorsi presenti in openapi.json
che non richiedono una chiave API. Al termine, viene visualizzata una riga simile alla seguente, in cui sono visualizzati l'ID configurazione del servizio e il nome del servizio:
Service Configuration [2017-02-13-r2] uploaded for service [example-project-12345.appspot.com]
Nell'esempio precedente, 2017-02-13-r2
è l'ID configurazione del servizio e example-project-12345.appspot.com
è il nome del servizio.
Per ulteriori informazioni, consulta
gcloud
Deployment dei servizi Endpoints.
Verifica dei servizi richiesti
Per fornire la gestione delle API, Endpoints Frameworks richiede i seguenti servizi:Nome | Titolo |
---|---|
servicemanagement.googleapis.com |
API Service Management |
servicecontrol.googleapis.com |
API Service Control |
Nella maggior parte dei casi, il comando gcloud endpoints services deploy
attiva questi
servizi obbligatori. Tuttavia, il comando gcloud
viene completato correttamente, ma
non attiva i servizi richiesti nelle seguenti circostanze:
Se hai utilizzato un'applicazione di terze parti come Terraform e non includi questi servizi.
Hai eseguito il deployment della configurazione di Endpoints in un progetto Google Cloud esistente in cui questi servizi sono stati disattivati esplicitamente.
Utilizza il seguente comando per verificare che i servizi richiesti siano abilitati:
gcloud services list
Se non vedi i servizi richiesti nell'elenco, attivali:
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
Abilita anche il servizio Endpoints:
gcloud services enable ENDPOINTS_SERVICE_NAME
Per determinare ENDPOINTS_SERVICE_NAME, puoi:
Dopo aver eseguito il deployment della configurazione di Endpoints, vai alla pagina Endpoints nella console Cloud. L'elenco dei possibili ENDPOINTS_SERVICE_NAME è riportato nella colonna Nome servizio.
Per OpenAPI, ENDPOINTS_SERVICE_NAME è il valore specificato nel campo
host
della specifica OpenAPI. Per gRPC, ENDPOINTS_SERVICE_NAME è il valore specificato nel camponame
della configurazione degli endpoint gRPC.
Per ulteriori informazioni sui comandi gcloud
, consulta
Servizi gcloud
.
Eseguire il sample localmente
Dopo aver eseguito il deployment della configurazione di Endpoints, puoi eseguire il sample localmente.
Crea una variabile di ambiente denominata
ENDPOINTS_SERVICE_NAME
, che viene utilizzata nel fileappengine-web.xml
del sample per impostare il nome host. Nel testo che segue, sostituisciYOUR_PROJECT_ID
con il tuo ID progetto Google Cloud.In Linux o Mac OS:
export ENDPOINTS_SERVICE_NAME=YOUR_PROJECT_ID.appspot.com
In Windows PowerShell:
$Env:ENDPOINTS_SERVICE_NAME="YOUR_PROJECT_ID.appspot.com"
Acquisisci nuove credenziali utente da utilizzare per le Credenziali predefinite dell'applicazione:
gcloud auth application-default login
Esegui il server di sviluppo:
mvn appengine:run
L'istanza locale è raggiungibile all'indirizzo
http://localhost:8080
, come indicato dai log stampati dal comandomvn appengine:run
:[INFO] GCLOUD: INFO: Module instance default is running at http://localhost:8080/
Invia una richiesta all'istanza locale:
Linux o Mac OS
curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"message":"hello world"}' \
http://localhost:8080/_ah/api/echo/v1/echo
Nel curl
precedente:
- L'opzione
--data
specifica i dati da pubblicare nell'API. - L'opzione
--header
specifica che i dati sono in formato JSON.
PowerShell
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
-Headers @{"content-type"="application/json"} `
-URI "http://localhost:8080/_ah/api/echo/v1/echo").Content
Nell'esempio precedente, le prime due righe terminano con un backtick. Quando incolli l'esempio in PowerShell, assicurati che non ci sia uno spazio dopo i backtick. Per informazioni sulle opzioni utilizzate nella richiesta di esempio, consulta Invoke-WebRequest nella documentazione di Microsoft.
L'API restituisce il messaggio che le hai inviato e risponde con quanto segue:
{
"message": "hello world"
}
esegui il deployment del backend dell'API
Fino a questo punto, hai eseguito il deployment della configurazione OpenAPI in Service Management, ma non hai ancora eseguito il deployment del codice soggiacente al backend dell'API. Questa sezione illustra la procedura per eseguire il deployment dell'API di esempio in App Engine.
Per eseguire il deployment del backend dell'API:
Assicurati di essere nella directory
java-docs-samples/appengine-java8/endpoints-v2-backend
Esegui il deployment del codice di implementazione dell'API utilizzando Maven:
mvn appengine:deploy
La prima volta che carichi un'app di esempio, ti potrebbe essere chiesto di autorizzare il deployment. Segui le istruzioni. Quando viene visualizzata una finestra del browser contenente un codice, copialo nella finestra del terminale.
Attendi il completamento del caricamento.
Ti consigliamo di attendere alcuni minuti prima di inviare richieste all'API mentre App Engine si inizializza completamente.
Invio di una richiesta all'API
Dopo aver eseguito il deployment dell'API e del relativo file di configurazione, puoi inviare richieste all'API.
Linux o Mac OS
Invia una richiesta HTTP utilizzando curl
. Sostituisci [YOUR_PROJECT_ID]
con il tuo ID progetto Google Cloud:
curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"message":"hello world"}' \
https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo
Nel curl
precedente:
- L'opzione
--data
specifica i dati da pubblicare nell'API. - L'opzione
--header
specifica che i dati sono in formato JSON.
PowerShell
Invia una richiesta HTTP utilizzando Invoke-WebRequest
. Sostituisci [YOUR_PROJECT_ID]
con l'ID del tuo progetto Google Cloud:
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
-Headers @{"content-type"="application/json"} -URI `
"https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content
Nell'esempio precedente, le prime due righe terminano con un backtick. Quando incolli l'esempio in PowerShell, assicurati che non ci sia uno spazio dopo i simboli ". Per informazioni sulle opzioni utilizzate nella richiesta di esempio, consulta Invoke-WebRequest nella documentazione di Microsoft.
App di terze parti
Puoi utilizzare un'applicazione di terze parti come l'estensione del browser Chrome Postman per inviare la richiesta:
- Seleziona
POST
come verbo HTTP. - Per l'intestazione, seleziona la chiave
content-type
e il valoreapplication/json
. - Per il corpo, inserisci quanto segue:
{"message":"hello world"}
-
Inserisci l'URL dell'applicazione di esempio. Ad esempio:
https://example-project-12345.appspot.com/_ah/api/echo/v1/echo
L'API restituisce il messaggio che le hai inviato e risponde con quanto segue:
{
"message": "hello world"
}
Se non hai ricevuto una risposta positiva, consulta la sezione Risoluzione dei problemi relativi alle risposte.
Hai appena eseguito il deployment e il test di un'API nei framework Endpoints.
monitora l'attività dell'API
Visualizza i grafici delle attività della tua API nella console Google Cloud nella pagina Endpoints > Service.
Vai alla pagina Servizi endpoint
La visualizzazione dei dati relativi alla richiesta nei grafici può richiedere alcuni minuti.
Esamina i log delle richieste per la tua API nella pagina Esplora log.
Creazione di un portale per gli sviluppatori per l'API
Puoi utilizzare il portale Cloud Endpoints per creare un portale per gli sviluppatori, un sito web che puoi utilizzare per interagire con l'API di esempio. Per saperne di più, consulta la panoramica del portale Cloud Endpoints.
Esegui la pulizia
Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Passaggi successivi
- Scopri di più sull'architettura dei framework Endpoints.
- Scopri di più sulle annotazioni API disponibili.
- Scopri come pubblicare l'API da un percorso diverso.
- Scopri di più sul monitoraggio dell'API.
- Scopri di più sulla limitazione dell'accesso con le chiavi API.
- Scopri di più sulla gestione del controllo delle versioni dell'API.
- Scopri di più sulle opzioni di assistenza della community.