Introduzione a Cloud Endpoints Frameworks per Java

---

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. Endpoints Frameworks è costituito da strumenti, librerie e funzionalità che consentono di generare API e librerie client da un'applicazione App Engine.

Obiettivi

Utilizza il seguente elenco di attività di alto livello mentre svolgi il tutorial. Tutte le attività sono necessarie per poter inviare correttamente richieste all'API.

1. Configurare un progetto Google Cloud. Vedi Prima di iniziare.
2. Installa il software richiesto e crea un'applicazione App Engine. Consulta Installazione e configurazione del software richiesto.
3. Scarica il codice campione. Consulta la pagina Ottenere il codice di esempio.
4. Generare un file di configurazione OpenAPI. Vedi Configurazione di Cloud Endpoints.
5. Esegui il deployment della configurazione di Endpoints per creare un servizio endpoint. Vedi Deployment della configurazione di Endpoints.
6. Esegui l'esempio sul computer. Vedi Esecuzione dell'esempio in locale.
7. Crea un backend per gestire l'API ed eseguirne il deployment. Vedi Deployment del backend dell'API.
8. Invia una richiesta all'API. Vedi Invio di una richiesta all'API.
9. Monitora l'attività delle API. Consulta Monitoraggio dell'attività dell'API.
10. Evita che al tuo account Google Cloud vengano addebitati costi. Vedi Pulizia.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

• Endpoint
• App Engine

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud possono essere idonei a una prova senza costi aggiuntivi.

Una volta completate le attività descritte in questo documento, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori informazioni, consulta la pagina Pulizia.

Prima di iniziare

1. Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

2. Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

   Nota: se non prevedi di conservare le risorse create in questa procedura, crea un progetto anziché selezionarne uno esistente. Dopo aver completato questi passaggi, puoi eliminare il progetto, rimuovendo tutte le risorse associate.

   Vai al selettore progetti

3. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

4. Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

   Nota: se non prevedi di conservare le risorse create in questa procedura, crea un progetto anziché selezionarne uno esistente. Dopo aver completato questi passaggi, puoi eliminare il progetto, rimuovendo tutte le risorse associate.

   Vai al selettore progetti

5. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

6. Prendi nota dell'ID progetto perché ti servirà in un secondo momento.

Installazione e configurazione del software richiesto

1. 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.
2. Se non disponi di Maven 3.3.9 o versioni successive, scaricalo e installalo.

Nota per gli utenti Windows: se stai installando JDK e Maven su Windows, installali in una directory che non contiene uno spazio nel percorso. Consulta Maven su Windows per ulteriori informazioni.

3. È necessaria un'applicazione per inviare richieste all'API di esempio.

   • Utenti Linux e macOS: questo tutorial fornisce un esempio sull'utilizzo di curl, che in genere è preinstallato sul sistema operativo. Se non hai curl, puoi scaricarlo dalla pagina curl Release e download.
   • Utenti Windows: questo tutorial fornisce un esempio utilizzando Invoke-WebRequest, supportato in PowerShell 3.0 e versioni successive.
4. Scarica e inizializza Google Cloud CLI.
5. Esegui questi comandi:
   1. Assicurati che gcloud CLI sia autorizzato ad accedere a dati e servizi su Google Cloud:

      gcloud auth login

   2. Utilizza le credenziali predefinite dell'applicazione:

      gcloud auth application-default login

   3. Installa il componente app-engine-java di Google Cloud SDK:

      gcloud components install app-engine-java

   4. Esegui l'aggiornamento alla versione più recente dell'Google Cloud SDK e di tutti i componenti:

      gcloud components update

6. Crea un'applicazione App Engine:
   1. 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 utilizzare gcloud per gestirli, consulta Gestione della gcloud CLI gcloud.

   2. Seleziona la regione in cui vuoi creare l'applicazione App Engine. Esegui questo comando per ottenere un elenco di regioni:

      gcloud app regions list

   3. Crea un'applicazione App Engine utilizzando il comando seguente. Sostituisci YOUR_PROJECT_ID con l'ID progetto Google Cloud e YOUR_REGION con la regione in cui vuoi creare l'applicazione App Engine.

      gcloud app create \
      --project=YOUR_PROJECT_ID \
      --region=YOUR_REGION
      

Recupera il codice di esempio

Per clonare l'API di esempio da GitHub:

1. Clona il repository di esempio sulla tua macchina locale:

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples
   

2. Passa alla directory contenente 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 creare il progetto Maven di esempio in modo da poter 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 al momento della creazione del progetto al pom.xml dell'esempio.

Per aggiungere l'ID progetto:

1. Modifica il file java-docs-samples/appengine-java8/endpoints-v2-backend/pom.xml.

2. Cerca <endpoints.project.id> e sostituisci YOUR_PROJECT_ID con il tuo ID progetto Google Cloud.

   Ad esempio:

   <endpoints.project.id>example-project</endpoints.project.id>
   

3. Salva le modifiche.

Creazione del progetto di esempio

Per creare il progetto:

1. Assicurati di essere nella directory java-docs-samples/appengine-java8/endpoints-v2-backend.

2. Esegui questo comando:

   mvn clean package
   

3. Attendi la creazione del progetto. Al termine del progetto, viene visualizzato un messaggio simile a questo:

   [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

Puoi utilizzare 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:

1. Richiama lo strumento Endpoints Frameworks utilizzando questo comando:

   mvn endpoints-framework:openApiDocs
   

2. Attendi il completamento delle specifiche di configurazione. Al termine, viene visualizzato un messaggio simile a questo:

   OpenAPI document written to target/openapi-docs/openapi.json
   

   Ignora eventuali messaggi relativi al mancato caricamento di una classe di log statico.

Eseguire il deployment della configurazione di Endpoints

Per eseguire il deployment della configurazione di Endpoints, utilizza Service Infrastructure, la piattaforma di servizi di base di Google, utilizzata da Endpoints Frameworks e altri servizi per creare e gestire API e servizi

Per eseguire il deployment del file di configurazione:

1. Assicurati di essere nella directory java-docs-samples/appengine-java8/endpoints-v2-backend.

2. 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 formato YOUR_PROJECT_ID.appspot.com. Questo nome è configurato in pom.xml e in altri file di configurazione inclusi nell'esempio. Tieni presente che quando esegui il deployment dell'API in App Engine, viene creato un record DNS utilizzando il formato del nome YOUR_PROJECT_ID.appspot.com, ovvero il nome di dominio completo (FQDN) utilizzato quando invii richieste all'API.

Durante la creazione e la configurazione del servizio, Service Management invia le informazioni al terminale. Puoi ignorare tranquillamente gli avvisi relativi ai percorsi in openapi.json che non richiedono una chiave API. Al completamento, una riga simile alla seguente mostra 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.

Vedi gcloud Deployment dei servizi Endpoints per ulteriori informazioni.

Controllo dei servizi richiesti in corso...

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
endpoints.googleapis.com	Google Cloud Endpoints

Nella maggior parte dei casi, il comando gcloud endpoints services deploy abilita questi servizi richiesti. Tuttavia, il comando gcloud viene completato correttamente, ma non abilita 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 disabilitati esplicitamente.

Utilizza il comando seguente per confermare che i servizi richiesti siano abilitati:

gcloud services list

Se i servizi richiesti non sono elencati, attivali:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com

Abilita anche il servizio Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Per determinare i ENDPOINTS_SERVICE_NAME puoi:

• Dopo aver eseguito il deployment della configurazione di Endpoints, vai alla pagina Endpoint nella console Cloud. L'elenco dei possibili ENDPOINTS_SERVICE_NAME è visualizzato nella colonna Nome servizio.

• Per OpenAPI, il valore ENDPOINTS_SERVICE_NAME è quello specificato nel campo host della specifica OpenAPI. Per gRPC, il valore ENDPOINTS_SERVICE_NAME è quello specificato nel campo name della configurazione degli endpoint gRPC.

Per ulteriori informazioni sui comandi gcloud, consulta la pagina relativa ai servizi gcloud.

Esecuzione dell'esempio in locale

Dopo aver eseguito il deployment della configurazione di Endpoints, puoi eseguire l'esempio localmente.

1. Crea una variabile di ambiente denominata ENDPOINTS_SERVICE_NAME, che viene utilizzata nel file appengine-web.xml di esempio per impostare il nome host. Nel seguente, sostituisci YOUR_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"
   

2. Acquisisci nuove credenziali utente da utilizzare per Credenziali predefinite dell'applicazione:

   gcloud auth application-default login
   

3. Esegui il server di sviluppo:

   mvn appengine:run
   

   L'istanza locale è raggiungibile su http://localhost:8080, come indicato dai log stampati dal comando mvn appengine:run:

   [INFO] GCLOUD: INFO: Module instance default is running at http://localhost:8080/
   

4. 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

Nei curl precedenti:

• L'opzione --data consente di specificare 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 apice inverso. Quando incolli l'esempio in PowerShell, assicurati che non sia presente uno spazio dopo i apici inversi. Per informazioni sulle opzioni utilizzate nella richiesta di esempio, vedi Invoke-WebRequest nella documentazione di Microsoft.

L'API restituisce l'eco del messaggio inviato e risponde con quanto segue:

{
 "message": "hello world"
}

Esegui il deployment del backend dell'API

Finora hai eseguito il deployment della configurazione OpenAPI in Service Management, ma non hai ancora eseguito il deployment del codice che gestisce il backend dell'API. Questa sezione illustra il deployment dell'API di esempio in App Engine.

Per eseguire il deployment del backend dell'API:

1. Assicurati di essere nella directory java-docs-samples/appengine-java8/endpoints-v2-backend

2. Esegui il deployment del codice di implementazione dell'API utilizzando Maven:

    mvn appengine:deploy
   

   La prima volta che carichi un'app di esempio, è possibile che ti venga chiesto di autorizzare il deployment. Segui le istruzioni. Quando viene visualizzata una finestra del browser contenente un codice, copialo nella finestra del terminale.

3. Attendi il completamento del caricamento.

   Durante l'inizializzazione completa di App Engine, ti consigliamo di attendere qualche minuto prima di inviare richieste all'API.

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 tramite curl. Sostituisci [YOUR_PROJECT_ID] con l'ID del tuo 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

Nei curl precedenti:

• L'opzione --data consente di specificare i dati da pubblicare nell'API.
• L'opzione --header specifica che i dati sono in formato JSON.

PowerShell

Invia una richiesta HTTP tramite 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 apice inverso. Quando incolli l'esempio in PowerShell, assicurati che non sia presente uno spazio dopo i apici inversi. Per informazioni sulle opzioni utilizzate nella richiesta di esempio, vedi Invoke-WebRequest nella documentazione di Microsoft.

App di terze parti

Per inviare la richiesta, puoi utilizzare un'applicazione di terze parti, come l'estensione del browser Chrome, Postman:

• Seleziona POST come verbo HTTP.
• Per l'intestazione, seleziona la chiave content-type e il valore application/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 l'eco del messaggio inviato e risponde con quanto segue:

{
 "message": "hello world"
}

Se non hai ricevuto una risposta corretta, consulta la sezione Risoluzione dei problemi relativi agli errori di risposta.

Hai appena eseguito il deployment e il test di un'API in Endpoints Frameworks.

Nota: se vuoi farci sapere cosa ti è piaciuto di questo tutorial, non esitare a fornire un feedback nella parte inferiore di questa pagina. Il tuo feedback ci aiuta a migliorare questi tutorial.
Se hai ricevuto un errore, unisciti al gruppo Google google-cloud-endpoints e facci sapere cosa non ha funzionato. Questo gruppo riceve risposte da altri utenti di endpoint e dai tecnici di Google, che monitorano il gruppo.

Monitora l'attività dell'API

1. Visualizza i grafici di attività per la tua API nella console Google Cloud nella pagina Endpoint > Servizio.

   Vai alla pagina di Endpoints Services

   Potrebbero essere necessari alcuni istanti prima che la richiesta venga riportata nei grafici.

2. Esamina i log delle richieste per l'API nella pagina Esplora log.

   Vai alla 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ù, vedi 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.

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:
• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività in questo documento, quando lo elimini elimini anche qualsiasi altro lavoro svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.
1. Nella console Google Cloud, vai alla pagina Gestisci risorse.

   Vai a Gestisci risorse

2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
3. Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.

Passaggi successivi

• Scopri di più sull'architettura di Endpoints Frameworks.
• Scopri di più sulle annotazioni API disponibili.
• Scopri di più sulla pubblicazione dell'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 delle API.
• Scopri di più sulle opzioni di assistenza dalla community.