Introduzione ai framework di Cloud Endpoints 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 App Engine ambiente di runtime Java 8 standard. Endpoints Frameworks è costituito da strumenti, librerie e funzionalità che ti consentono di generare API e librerie client da un ambiente App Engine un'applicazione.

Obiettivi

Durante il tutorial, utilizza il seguente elenco di attività di alto livello. Tutte le attività sono necessarie per inviare correttamente le richieste all'API.

1. Configurare un progetto Google Cloud. Consulta Prima di iniziare.
2. Installa il software richiesto e crea un'applicazione App Engine. Consulta Installare e configurare il software necessario.
3. Scarica il codice di esempio. Consulta Recupero del codice campione.
4. Genera un file di configurazione OpenAPI. Consulta Configurazione di Cloud Endpoints.
5. Esegui il deployment della configurazione di Endpoints per creare Servizio Endpoints. Consulta Esegui il deployment della configurazione di Endpoints.
6. Esegui l'esempio sul computer. Consulta Esecuzione dell'esempio in locale.
7. Creare un backend per la gestione dell'API ed il relativo deployment. Consulta Esegui il deployment del backend dell'API.
8. Invia una richiesta all'API. Consulta Invio di una richiesta all'API.
9. Monitorare l'attività dell'API. Consulta Monitorare l'attività dell'API.
10. Evita che al tuo account Google Cloud vengano addebitati costi. Consulta Esegui la pulizia.

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

• Endpoints
• App Engine

Per generare una stima dei costi basata sull'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero essere idonei per una prova gratuita.

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

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

6. Prendi nota dell'ID progetto perché ti servirà in seguito.

Installazione e configurazione del software necessario

1. Se non hai installato Java 8, scarica il Java Development Kit (JDK) da Oracle e installarlo. 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 hai Maven 3.3.9 o una versione successiva, download e installalo.

Nota per gli utenti Windows: se installi il JDK e Maven su Windows, installarle in una directory che non ha uno spazio nel percorso. Consulta Maven su Windows per maggiori informazioni.

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

   • Utenti Linux e macOS: questo tutorial fornisce un esempio dell'utilizzo curl, che in genere è preinstallata sul sistema operativo. Se non hai curl, puoi scaricarlo dal curl Pagina Release e download.
   • Utenti Windows: questo tutorial fornisce un esempio di utilizzo Invoke-WebRequest, ovvero supportato in PowerShell 3.0 e versioni successive.
4. Scarica e inizializza Google Cloud CLI.
5. Esegui questi comandi:
   1. Assicurati che l'interfaccia a riga di comando gcloud sia autorizzata ad accedere ai tuoi 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 Google Cloud SDK app-engine-java:

      gcloud components install app-engine-java

   4. Esegui l'aggiornamento alla versione più recente di 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 consulta Gestione di gcloud CLI configurazioni.

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

      gcloud app regions list

   3. Crea un'applicazione App Engine utilizzando il seguente comando. Sostituisci YOUR_PROJECT_ID con l'ID del tuo 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 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 OpenAPI di configurazione 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

Devi aggiungere l'ID progetto ottenuto al momento della creazione del progetto nell'oggetto pom.xml dell'esempio prima di poter eseguire il deployment del codice.

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

Usi uno strumento della libreria Endpoints Frameworks per generare un Documento OpenAPI denominato openapi.json. Questo file descrive l'API REST del codice di esempio.

Per generare il file di configurazione OpenAPI:

1. Richiama lo strumento Endpoints Frameworks utilizzando questo comando:

   mvn endpoints-framework:openApiDocs
   

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

   Ignorare gli eventuali messaggi relativi al mancato caricamento di una classe logger statica.

esegui il deployment della configurazione di Endpoints

Per eseguire il deployment della configurazione di Endpoints, Service Infrastructure, il programma di base, usata da Endpoints Frameworks e da altre piattaforme 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 precedente sezione:

   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 altri file di configurazione inclusi nell'esempio. Tieni presente che quando esegui il deployment dell'API su App Engine, viene creato un record DNS il formato del nome YOUR_PROJECT_ID.appspot.com, ovvero il nome di dominio completo (FQDN) che utilizzi quando invii richieste a l'API.

Durante la creazione e la configurazione del servizio, Service Management genera le informazioni al terminale. Puoi ignorare tranquillamente gli avvisi sui percorsi presenti in openapi.json che non richiedono una chiave API. Attivato completamento riuscito, viene visualizzata una riga simile alla seguente: 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 è la configurazione del servizio e example-project-12345.appspot.com è il nome del servizio.

Consulta Deployment di gcloud servizi di 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 attiva i servizi richiesti nelle seguenti circostanze:

• Se hai utilizzato un'applicazione di terze parti, come Terraform, includono questi servizi.

• Hai eseguito il deployment della configurazione di Endpoints in una Progetto Google Cloud 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 elencati i servizi richiesti, abilitali:

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 il 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 è quello che hai 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 gcloud servizi.

Esecuzione dell'esempio in locale

Dopo aver eseguito il deployment della configurazione di Endpoints, puoi eseguire campionare localmente.

1. Crea una variabile di ambiente denominata ENDPOINTS_SERVICE_NAME, che è utilizzato nel file appengine-web.xml dell'esempio per impostare il nome host. Nel testo che segue, 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 da i 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

Nel curl precedente:

• 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 accento grave. Quando incolli in PowerShell, assicuratevi che non ci sia uno spazio dopo i accenti arretrati. Per informazioni sulle opzioni utilizzate nella richiesta di esempio, vedi Invoke-WebRequest nel documentazione.

L'API restituisce il messaggio che lo invii e risponde con seguenti:

{
 "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. Questo ti guiderà attraverso la procedura di 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, ti potrebbe essere chiesto di autorizzare per il deployment. Segui le istruzioni. Quando viene visualizzato un browser contenente un codice, copialo nella finestra del terminale.

3. Attendi il completamento del caricamento.

   Ti consigliamo di attendere alcuni minuti prima di inviare richieste alla tua API mentre App Engine inizia l'inizializzazione.

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 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 periodo precedente (curl):

• 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 utilizzando Invoke-WebRequest. Sostituisci [YOUR_PROJECT_ID] con il tuo ID 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 in PowerShell, assicuratevi che non ci sia uno spazio dopo i accenti arretrati. Per informazioni sulle opzioni utilizzate nella richiesta di esempio, vedi Invoke-WebRequest nel documentazione.

App di terze parti

Puoi utilizzare un'applicazione di terze parti come il browser Chrome Postman per inviare richiesta:

• 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 il messaggio che lo invii e risponde con seguenti:

{
 "message": "hello world"
}

Se non hai ricevuto una risposta positiva, consulta Risolvere i problemi relativi alle risposte.

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

Nota: se vuoi farci sapere cosa ti è piaciuto di questa presentazione tutorial, non esitare a fornire un feedback in fondo a questa pagina. Il tuo feedback ci aiuta a migliorare questi tutorial.
Se ricevi un messaggio di errore, partecipa al google-cloud-endpoints gruppo Google e facci sapere cosa non ha funzionato. Questo gruppo riceve risposte da altri Utenti di Endpoints e degli ingegneri Google che monitorano il gruppo.

monitora l'attività dell'API

1. Visualizza i grafici di attività per l'API nella console Google Cloud nella Endpoint > Servizio.

   Vai alla pagina dei servizi Endpoints

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

2. Controlla 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ù, 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.

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à descritte in questo documento, quando lo elimini elimini anche tutto il 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 appspot.com URL, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.
1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. 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.
• Informazioni su annotazioni API disponibili.
• Scopri come pubblicare l'API da un percorso diverso.
• Informazioni su il monitoraggio dell'API.
• Informazioni su limitare l'accesso con chiavi API.
• Informazioni su per la gestione del controllo delle versioni dell'API.
• Scopri di più sulle opzioni di assistenza della community.