Inizia a utilizzare 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 standard Java 8 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 segui il tutorial. Tutte le attività sono necessarie per inviare correttamente le richieste all'API.

  1. Configurare un progetto Google Cloud . Vedi Prima di iniziare.
  2. Installa il software richiesto e crea un'applicazione App Engine. Vedi Installazione e configurazione del software richiesto.
  3. Scarica il codice campione. Vedi Recupera il codice di esempio.
  4. Genera un file di configurazione OpenAPI. Consulta Configurazione di Cloud Endpoints.
  5. Esegui il deployment della configurazione di Endpoints per creare un servizio Endpoints. Vedi Deployment della configurazione di Endpoints.
  6. Esegui il campione sul computer. Consulta Esecuzione del campione localmente.
  7. Crea un backend per pubblicare l'API ed esegui il deployment dell'API. Consulta Esegui il deployment del backend dell'API.
  8. Invia una richiesta all'API. Consulta Invio di una richiesta all'API.
  9. Monitora l'attività dell'API. Consulta Monitorare l'attività dell'API.
  10. Evita che al tuo account Google Cloud vengano addebitati costi. Vedi 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.

I nuovi Google Cloud utenti potrebbero avere diritto a una prova gratuita.

Al termine delle attività descritte in questo documento, puoi evitare l'addebito di ulteriori costi eliminando le risorse che hai creato. Per ulteriori informazioni, vedi 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.

    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.

    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 richiesto

  1. Se non hai installato Java 8, scarica Java Development Kit (JDK) da Oracle e installalo. Poiché Endpoints Frameworks per Java dipende dall'ambiente di runtime standard Java 8 di App Engine, Endpoints Frameworks non supporta altre versioni di Java.
  2. Se non hai Maven 3.3.9 o versioni successive, scaricalo e installalo.
  3. Nota per gli utenti Windows: se installi JDK e Maven su Windows, installali in una directory il cui percorso non contenga spazi. Per ulteriori informazioni, consulta Maven su Windows.

  4. Per inviare richieste all'API di esempio, devi disporre di un'applicazione.

    • Utenti Linux e macOS: questo tutorial fornisce un esempio di utilizzo di curl, che in genere è preinstallato sul sistema operativo. Se non hai curl, puoi scaricarlo dalla curl pagina di release e download.
    • Utenti Windows: questo tutorial fornisce un esempio che utilizza Invoke-WebRequest, che è supportato in PowerShell 3.0 e versioni successive.
  5. Scarica e inizializza Google Cloud CLI.
  6. Esegui i seguenti comandi:
    1. Assicurati che gcloud CLI 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 app-engine-java di Google Cloud SDK:
      gcloud components install app-engine-java
    4. Esegui l'aggiornamento all'ultima versione di Google Cloud SDK e di tutti i componenti:
      gcloud components update
  7. Crea un'applicazione App Engine:
    1. Imposta il progetto predefinito sull'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 la sezione Gestione delle configurazioni di gcloud CLI.

    2. Seleziona la regione in cui vuoi creare l'applicazione App Engine. Esegui il comando seguente 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 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 decodice campioneio. Segui i passaggi di 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

Devi aggiungere l'ID progetto ottenuto quando hai creato il progetto al 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 l'Google Cloud ID progetto.

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

Utilizzi uno strumento della libreria Endpoints Frameworks per generare un documento OpenAPI chiamato 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 la creazione della specifica di configurazione. Al termine, viene visualizzato un messaggio simile a questo:

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

    Ignora tutti i 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, utilizza Service Infrastructure, la piattaforma di servizi di base di Google, utilizzata da Endpoints Frameworks e da altri servizi per creare e gestire API e servizi

Per eseguire il deployment del file di configurazione:

  1. Assicurati di trovarti 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
    

In questo modo 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 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 quando invii richieste all'API.

Durante la creazione e la configurazione del servizio, Service Management visualizza informazioni nel 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 di configurazione del servizio e example-project-12345.appspot.com è il nome del servizio.

Per ulteriori informazioni, consulta gcloud Deploy dei servizi Endpoints.

Controllo 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 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 progettoGoogle Cloud esistente in cui questi servizi sono stati disattivati in modo esplicito.

Utilizza questo comando per verificare che i servizi richiesti siano abilitati:

gcloud services list

Se non vedi i servizi richiesti elencati, 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 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 viene visualizzato nella colonna Nome servizio.

  • Per OpenAPI, ENDPOINTS_SERVICE_NAME è ciò che hai specificato nel campo host della specifica OpenAPI. Per gRPC, ENDPOINTS_SERVICE_NAME è ciò che hai specificato nel campo name della configurazione di gRPC Endpoints.

Per ulteriori informazioni sui comandi gcloud, consulta servizi gcloud.

Esecuzione del campione in locale

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

  1. Crea una variabile di ambiente denominata ENDPOINTS_SERVICE_NAME, che viene utilizzata nel file appengine-web.xml dell'esempio per impostare il nome host. Nel seguente comando, sostituisci YOUR_PROJECT_ID con l'Google Cloud ID progetto.

    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 le 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 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 accento grave. Quando incolli l'esempio in PowerShell, assicurati che non ci sia uno spazio dopo gli apici inversi. Per informazioni sulle opzioni utilizzate nella richiesta di esempio, consulta Invoke-WebRequest nella documentazione di Microsoft.

L'API restituisce il messaggio che invii 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 ti guida nell'esecuzione del deployment dell'API di esempio in App Engine.

Per eseguire il deployment del backend dell'API:

  1. Assicurati di trovarti 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, potrebbe esserti 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.

    Ti consigliamo di attendere alcuni minuti prima di inviare richieste alla tua 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 l'Google Cloud ID progetto:

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 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 accento grave. Quando incolli l'esempio in PowerShell, assicurati che non ci sia uno spazio dopo gli apici inversi. 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 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 invii e risponde con quanto segue:

{
 "message": "hello world"
}

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

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

monitora l'attività dell'API

  1. Visualizza i grafici di attività della tua API nella console Google Cloud nella pagina Endpoints > Servizio.

    Vai alla pagina Servizi endpoint

    La visualizzazione dei dati relativi alla richiesta nei grafici può richiedere alcuni minuti.

  2. Esamina i log delle richieste per la tua API nella pagina Esplora log.

    Vai alla pagina Esplora log

Creazione di un portale per 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.

  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