Esegui il deployment di un'API gestita da Cloud Endpoints

Esegui il deployment di un'API gestita da Cloud Endpoints

Questa guida rapida illustra la procedura di deployment di un'API di esempio, gestita da Endpoints. Il codice campione include:

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

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

Questa guida rapida utilizza script per semplificare i passaggi di configurazione in modo da visualizzare rapidamente i grafici e i log 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
• Cloud Endpoints Frameworks: tutorial

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.

Avviare Cloud Shell

1. Nella console Google Cloud, assicurati di trovarti 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 e viene visualizzato un prompt della riga di comando. L'inizializzazione della sessione può richiedere alcuni secondi.

   

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

   gcloud components update
   

Nota: se utilizzi una macchina Linux o macOS e vuoi seguire questa procedura di avvio rapido utilizzando la tua shell locale, scarica Google Cloud CLI ed esegui queste istruzioni di avvio rapido 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 è dotata di un file OpenAPI preconfigurato denominato openapi.yaml.

Endpoints utilizza Service Management, un servizio di infrastruttura di Google Cloud, per creare e gestire API e servizi. Per utilizzare Endpoints per la gestione di 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 nel 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 il 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 informazioni nella console Google Cloud. Puoi ignorare tranquillamente gli avvisi sui percorsi presenti in openapi.yaml 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 [airports-api.endpoints.example-project.cloud.goog]

Attivazione dei servizi richiesti

Endpoints richiede almeno l'abilitazione dei seguenti servizi Google:

Nome	Titolo
servicecontrol.googleapis.com	API Service Control
servicemanagement.googleapis.com	API Service Management

Nella maggior parte dei casi, il deployment della configurazione di Endpoints abilita questi servizi obbligatori.

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 YOUR-PROJECT-ID.appspot.com

Per ulteriori informazioni sui comandi gcloud, consulta Servizi gcloud.

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 per 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 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 il seguente 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 per l'ambiente flessibile di App Engine richiede alcuni minuti. Dopo aver creato l'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 alcuni minuti. Quando l'API viene eseguita correttamente in App Engine, 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 inviare 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 mostra 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 aeroporto IATA valido, ad esempio SEA o JFK. Ad esempio:

./query_api.sh JFK

Nota: App Engine potrebbe impiegare alcuni minuti per rispondere correttamente alle richieste. Se invii una richiesta e ricevi un messaggio HTTP 502, 503 o un altro errore del server, attendi un minuto e riprova a inviare 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 inviare un feedback nella parte inferiore di questa pagina. Il tuo feedback ci aiuta a migliorare questi tutorial.
Se hai visualizzato un messaggio di errore, partecipa al gruppo Google google-cloud-endpoints e comunicaci cosa non ha funzionato. Questo gruppo riceve risposte da altri utenti di Endpoints e dai tecnici di Google, che lo monitorano.

monitora l'attività dell'API

Per le API di cui esegui il deployment con Endpoints, puoi monitorare le metriche delle operazioni critiche nella console Google Cloud e raccogliere informazioni dettagliate sugli utenti e sull'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, premi Control+C in Cloud Shell.

2. Nella console Google Cloud, esamina i grafici delle attività associate alla tua API.

   Vai alla pagina Servizi endpoint

   La visualizzazione dei dati relativi alle richieste nei grafici può richiedere alcuni minuti. Mentre attendi che i dati vengano visualizzati:

   • Se il riquadro laterale Autorizzazioni non è aperto, fai clic su +Autorizzazioni. Il riquadro Autorizzazioni consente di controllare chi ha accesso alla tua 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. Vedrai il traffico in entrata. Dopo un minuto dall'inizio dell'esecuzione dello script di generazione del traffico, vedrai 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 Collegamenti, fai clic su Visualizza log per GET/airportName. Nella pagina Esplora log sono visualizzati 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 ti consente di impostare quote che ti consentono di controllare la frequenza con cui le applicazioni possono chiamare la tua API. Puoi utilizzare le quote per proteggere la tua API dall'utilizzo eccessivo da parte di un singolo 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, questa diventa attiva entro un minuto.

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

   Vai alla pagina Credenziali

3. Fai clic su Crea credenziali e poi 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 che hai appena generato.

   ./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 il comando seguente per inviare il traffico all'API e attivare il limite stabilito dalla quota.

   ./generate_traffic_with_key.sh $API_KEY
   

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

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 di nuovo 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 ulteriori 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 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 questa pagina, segui questi passaggi.

Per evitare addebiti, puoi eliminare il tuo progetto Google Cloud per interrompere la fatturazione per tutte le risorse utilizzate al suo interno.

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

• Per una panoramica di Endpoints:

  • Informazioni su Endpoints
  • Endpoint: panoramica dell'architettura

• Per scoprire i diversi framework API supportati da Endpoints:

  • Specifica OpenAPI
  • Endpoint per le API gRPC
  • Informazioni su Endpoints Frameworks

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

  • Endpoints per OpenAPI: tutorial
  • Endpoints per gRPC: tutorial
  • Endpoints Frameworks: tutorial