Esegui il deployment di un'API gestita da Cloud Endpoints

Esegui il deployment di un'API gestita da Cloud Endpoints

Questa guida rapida illustra come eseguire il deployment di un'API di esempio, gestita dagli endpoint. Il codice campione include:

• Un'API REST su cui puoi eseguire una query per trovare il nome di un aeroporto nel codice IATA di tre lettere.
• Uno script che carica la configurazione API su Endpoints.
• Uno script che esegue il deployment del backend di un ambiente App Engine flessibile per ospitare l'API di esempio.

Dopo aver inviato le richieste all'API di esempio, puoi visualizzare i grafici di attività degli endpoint e i log di Google Cloud Observability nella console Google Cloud. Questi strumenti consentono di monitorare le API e ottenere insight sul loro utilizzo.

Questa guida rapida utilizza gli script per semplificare i passaggi di configurazione, permettendoti di vedere rapidamente i log e i grafici delle attività in azione. Per scoprire come configurare ed eseguire il deployment di un'API di esempio, scegli un tutorial per uno dei framework API:

• Cloud Endpoints per OpenAPI: tutorial
• Cloud Endpoints per gRPC: tutorial
• Framework di Cloud Endpoints: tutorial

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.

Avviare Cloud Shell

1. Nella console Google Cloud, assicurati di essere nel progetto che vuoi utilizzare per l'API di esempio.

2. Apri Cloud Shell.

   Apri Cloud Shell

   All'interno di un nuovo frame nella parte inferiore della console Google Cloud si apre una sessione di Cloud Shell che mostra un prompt della riga di comando. L'inizializzazione della sessione potrebbe richiedere alcuni secondi.

   

3. Se utilizzi un progetto esistente, assicurati di disporre della versione più recente di tutti i componenti gcloud installati:

   gcloud components update
   

Nota: se utilizzi una macchina Linux o MacOS e vuoi seguire questa guida rapida utilizzando la tua shell locale, scarica Google Cloud CLI ed esegui queste istruzioni rapide utilizzando l'interfaccia a riga di comando locale anziché Cloud Shell.

recupera il codice di esempio

1. In Cloud Shell, inserisci il comando seguente per recuperare l'API e gli script di esempio:

   git clone https://github.com/GoogleCloudPlatform/endpoints-quickstart
   

2. Passa alla directory che contiene il codice di esempio:

   cd endpoints-quickstart
   

esegui il deployment della configurazione di Endpoints

Per pubblicare un'API REST in Endpoints, è necessario un file di configurazione OpenAPI che descriva l'API. L'API di esempio viene fornita con un file OpenAPI preconfigurato denominato openapi.yaml.

Endpoints utilizza Service Management, un servizio di infrastruttura di Google Cloud per creare e gestire le API e i servizi. Per utilizzare gli endpoint per gestire un'API, devi eseguire il deployment del file di configurazione OpenAPI dell'API in Service Management.

Per eseguire il deployment della configurazione di Endpoints:

1. In Cloud Shell, nella directory endpoints-quickstart, inserisci quanto segue:

   cd scripts
   

2. Esegui lo script seguente, che è incluso nell'esempio:

   ./deploy_api.sh
   

Endpoints utilizza il campo host del file di configurazione OpenAPI per identificare il servizio. Lo script deploy_api.sh imposta l'ID del progetto Google Cloud come parte del nome configurato nel campo host. Quando prepari un file di configurazione OpenAPI per un tuo servizio, devi eseguire questa operazione manualmente.

Lo script quindi esegue il deployment della configurazione OpenAPI in Service Management utilizzando il comando: gcloud endpoints services deploy openapi.yaml

Durante la creazione e la configurazione del servizio, Service Management visualizza le informazioni nella console Google Cloud. Puoi ignorare tranquillamente gli avvisi relativi ai percorsi in openapi.yaml che non richiedono una chiave API. Al completamento, viene visualizzata una riga simile alla seguente, in cui sono visualizzati l'ID della configurazione del servizio e il nome del servizio:

    Service Configuration [2017-02-13-r2] uploaded for service [airports-api.endpoints.example-project.cloud.goog]

Attivazione dei servizi richiesti

Come minimo, Endpoints richiede l'abilitazione dei seguenti servizi Google:

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 deployment della configurazione di Endpoints abilita questi servizi richiesti.

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

gcloud services list

Se i servizi richiesti non sono elencati, 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 YOUR-PROJECT-ID.appspot.com

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

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 per gestire il backend dell'API. Lo script deploy_app.sh incluso nell'esempio crea un ambiente App Engine flessibile per ospitare il backend dell'API, quindi lo script esegue il deployment dell'API in App Engine.

Per eseguire il deployment del backend dell'API:

• In Cloud Shell, nella directory endpoints-quickstart/scripts, esegui questo script:

  ./deploy_app.sh
  

Lo script esegue il comando seguente per creare un ambiente App Engine flessibile nella regione us-central: gcloud app create --region="$REGION"

La creazione del backend dell'ambiente flessibile di App Engine richiede diversi minuti. Dopo la creazione dell'applicazione, l'output è:

Success! The app is now created.

Successivamente, lo script esegue il comando gcloud app deploy per eseguire il deployment dell'API di esempio in App Engine.

L'output è:

Deploying ../app/app_template.yaml...You are about to deploy the following services:

Il deployment dell'API in App Engine richiede diversi minuti. Una volta che il deployment dell'API in App Engine è stato eseguito correttamente, l'output è:

Deployed service [default] to [https://example-project.appspot.com]

invia richieste all'API

• In Cloud Shell, dopo aver eseguito il deployment dell'API di esempio, puoi inviarle richieste eseguendo lo script seguente:

  ./query_api.sh
  

Lo script visualizza sullo schermo l'output del comando curl che utilizza per inviare una richiesta all'API, quindi visualizza il risultato. L'output è:

curl "https://example-project.appspot.com/airportName?iataCode=SFO"
San Francisco International Airport

L'API prevede un parametro di query, iataCode, impostato su un codice dell'aeroporto IATA valido, come SEA o JFK. Ad esempio:

./query_api.sh JFK

Nota: App Engine potrebbe richiedere alcuni minuti per rispondere correttamente alle richieste. Se invii una richiesta e ricevi un errore HTTP 502, 503 o di qualche altro tipo del server, attendi un minuto e riprova a eseguire la richiesta.

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

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

monitora l'attività dell'API

Con le API di cui è stato eseguito il deployment con Endpoints, puoi monitorare le metriche operative fondamentali nella console Google Cloud e ottenere insight su utenti e utilizzo con Cloud Logging.

1. In Cloud Shell, esegui lo script per la generazione di traffico per completare i grafici e i log:

   ./generate_traffic.sh
   

   Nota: questo script genera le richieste in un loop e il timeout si verifica automaticamente dopo 5 minuti. Per terminare lo script in anticipo, inserisci Control+C in Cloud Shell.

2. Nella console Google Cloud, guarda i grafici di attività per la tua API.

   Vai alla pagina Endpoints Services

   La visualizzazione dei dati relativi alle richieste nei grafici potrebbe richiedere qualche istante. Mentre attendi che i dati vengano visualizzati:

   • Se il riquadro laterale Autorizzazioni non è aperto, fai clic su +Autorizzazioni. Il riquadro Autorizzazioni ti consente di controllare chi può accedere all'API e il livello di accesso.

   • Fai clic su Cronologia deployment. La scheda visualizza una cronologia dei deployment dell'API e include dati come l'ora del deployment e chi ha eseguito il deployment della modifica.

   • Fai clic su Panoramica. Vedi il traffico in entrata. Dopo che lo script di generazione del traffico è in esecuzione per un minuto, vengono visualizzate tre linee sul grafico della latenza totale (50°, 95° e 98° percentile). Questi dati forniscono una stima dei tempi di risposta.

3. Scorri verso il basso fino alla tabella sotto i grafici e, in Link, fai clic su Visualizza log per GET/airportName. La pagina Esplora log mostra i log delle richieste per l'API.

4. Apri Cloud Shell.

   Apri Cloud Shell

5. Per interrompere lo script, inserisci Control+C.

Aggiunta di una quota all'API

Beta

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Endpoints permette di impostare quote che permettono di controllare la frequenza con cui le applicazioni possono chiamare l'API. Puoi usare le quote per proteggere l'API dall'utilizzo eccessivo da parte di un solo client.

1. In Cloud Shell, esegui il deployment della configurazione di Endpoints che prevede una quota.

   ./deploy_api.sh ../openapi_with_ratelimit.yaml
   

   Dopo aver eseguito il deployment di una configurazione di Endpoints aggiornata, diventa attiva entro un minuto.

2. Nella console Google Cloud, vai alla pagina Credenziali.

   Vai alla pagina Credenziali

3. Fai clic su Crea credenziali, quindi su Chiave API. Sullo schermo viene visualizzata una nuova chiave API.

4. Fai clic su Copia .

5. In Cloud Shell, digita quanto segue. Sostituisci YOUR_API_KEY con la chiave API che hai appena creato.

   export API_KEY=YOUR_API_KEY
   

6. Invia una richiesta all'API utilizzando la chiave API appena generata.

   ./query_api_with_key.sh $API_KEY
   

   L'output è simile al seguente:

   curl -H 'x-api-key: AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB' "https://example-project.appspot.com/airportName?iataCode=SFO"
   San Francisco International Airport
   

7. L'API ora ha un limite di 5 richieste al minuto. Esegui questo comando per inviare il traffico all'API e attivare il limite di quota.

   ./generate_traffic_with_key.sh $API_KEY
   

8. Dopo aver eseguito lo script per 5-10 secondi, inserisci Control+C per interrompere lo script.

9. Invia un'altra richiesta autenticata all'API.

   ./query_api_with_key.sh $API_KEY
   

   L'output è simile al seguente:

   {
    "code": 8,
    "message": "Insufficient tokens for quota 'airport_requests' and limit 'limit-on-airport-requests' of service 'example-project.appspot.com' for consumer     'api_key:AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB'.",
    "details": [
     {
      "@type": "type.googleapis.com/google.rpc.DebugInfo",
      "stackEntries": [],
      "detail": "internal"
     }
    ]
   }
   

Se viene visualizzata una risposta diversa, prova a eseguire nuovamente lo script generate_traffic_with_key.sh e riprova.

Complimenti! Hai impostato correttamente la limitazione di frequenza dell'API. Puoi anche impostare limiti variabili su metodi diversi dell'API, creare più tipi di quote e tenere traccia di quali consumer utilizzano quali API.

Per maggiori informazioni, consulta Informazioni sulle quote.

Creazione di un portale per gli sviluppatori per l'API

Puoi utilizzare il portale Cloud Endpoints per creare un portale per sviluppatori, un sito web che puoi utilizzare per interagire con l'API di esempio. Per ulteriori informazioni, consulta la pagina Panoramica del portale Cloud Endpoints.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questa pagina, segui questi passaggi:

Per evitare addebiti, puoi eliminare il tuo progetto Google Cloud per interrompere la fatturazione per tutte le risorse utilizzate all'interno di quel progetto.

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

• Per una panoramica di Endpoints:

  • Informazioni su Endpoints
  • Endpoint: panoramica dell'architettura

• Per saperne di più sui diversi framework API supportati da Endpoints:

  • Specifica OpenAPI
  • Endpoint per API gRPC
  • Informazioni su Endpoints Framework

• Per scoprire come configurare ed eseguire il deployment di un'API di esempio, scegli un tutorial per uno dei framework API:

  • Endpoint per OpenAPI: tutorial
  • Endpoint per gRPC: tutorial
  • Endpoint Framework: tutorial