Introduzione a Cloud Endpoints per GKE con ESPv2

Questo tutorial ti mostra come configurare ed eseguire il deployment di un'API di esempio e di Extensible Service Proxy V2 (ESPv2) in un cluster Google Kubernetes Engine (GKE).

L'API REST di esempio di codice è descritta utilizzando la specifica OpenAPI. Il tutorial mostra anche come creare una chiave API e come utilizzarla quando si inviano richieste all'API.

Il tutorial utilizza immagini container predefinite del codice di esempio e ESPv2, che sono archiviate in Container Registry.

Per una panoramica di Cloud Endpoints, consulta le informazioni sugli endpoint e l'architettura degli endpoint.

Obiettivi

Utilizza il seguente elenco di attività avanzate durante l'esecuzione del tutorial. Tutte le attività nella Parte 1 sono necessarie per inviare correttamente le richieste all'API.

Parte 1

  1. Configurare un progetto Google Cloud. Vedi Prima di iniziare.
  2. Crea un cluster di container su GKE. Vedi Creazione di un cluster di container.
  3. Installa e configura il software utilizzato nel tutorial. Vedi Installazione e configurazione del software richiesto.
  4. Scarica il codice di esempio. Consulta la sezione Ottenere il codice di esempio.
  5. Configura il file openapi.yaml, che viene utilizzato per configurare Cloud Endpoints. Vedi Configurazione degli endpoint.
  6. Eseguire il deployment della configurazione degli endpoint per creare un servizio di endpoint. Vedi Deployment della configurazione degli endpoint.
  7. Esegui il deployment dell'API e di ESPv2 al cluster. Vedi Deployment del backend dell'API.
  8. Recupera l'indirizzo IP del cluster. Vedi Recupero dell'indirizzo IP esterno del cluster.
  9. Invia una richiesta all'API utilizzando un indirizzo IP. Vedi Inviare una richiesta utilizzando un indirizzo IP.
  10. Monitora l'attività dell'API. Consulta Attività dell'API di monitoraggio.

Parte 2

  1. Configura un record DNS per l'API di esempio. Vedi Configurazione del DNS per endpoint.
  2. Invia una richiesta all'API utilizzando il nome di dominio completo. Vedi Inviare una richiesta utilizzando il nome di dominio completo.

Pulizia

Al termine, consulta Pulizia per evitare che al tuo account Google Cloud vengano addebitati costi.

Costi

Questo tutorial utilizza i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud possono beneficiare di una prova gratuita.

Al termine di questo tutorial, puoi evitare una fatturazione continua eliminando le risorse che hai creato. Per scoprire di più, vedi 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 dei progetti in Google Cloud Console, seleziona o crea un progetto Google Cloud.

    Vai al selettore progetti

  3. Assicurati che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata su un progetto.

  4. Nella pagina del selettore dei progetti in Google Cloud Console, seleziona o crea un progetto Google Cloud.

    Vai al selettore progetti

  5. Assicurati che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata su un progetto.

  6. Prendi nota dell'ID progetto Google Cloud, perché è necessario in un secondo momento.

Creazione di un cluster di container

Per eseguire il codice di backend dell'API di esempio, devi creare un cluster di container su GKE. Il cluster deve avere un alias IP per poter usare il bilanciamento del carico nativo del container. Per creare un cluster di container con un alias IP per l'API di esempio:

gcloud container clusters create espv2-demo-cluster \
    --enable-ip-alias \
    --create-subnetwork="" \
    --network=default \
    --zone=us-central1-a

Il comando di esempio riportato sopra crea un cluster, espv2-demo-cluster, con una subnet di cui è stato eseguito il provisioning automatico nella zona us-central1-a.

Prendi nota del nome e della zona del cluster perché sono necessari quando esegui l'autenticazione di kubectl nel cluster di container.

Installazione e configurazione del software richiesto

In questo tutorial, installerai l'interfaccia a riga di comando gcloud in modo da poter utilizzare l'interfaccia a riga di comando di Google Cloud per gestire il tuo progetto. Utilizzi kubectl per eseguire comandi contro i cluster GKE. Ti serve anche un modo per testare l'API.

Nella procedura seguente, se hai già installato il software richiesto, vai al passaggio successivo.

Per installare e configurare il software richiesto:

  1. Per inviare richieste all'API di esempio, devi avere un'applicazione.

    • Utenti Linux e macOS: questo tutorial fornisce un esempio di utilizzo di curl, che in genere è preinstallato sul tuo sistema operativo. Se non hai curl, puoi scaricarlo dalla curl Pagina Uscite e download.
    • Utenti Windows: questo tutorial fornisce un esempio utilizzando Invoke-WebRequest, che è supportato in PowerShell 3.0 e versioni successive.
  2. Installa e inizializza l'interfaccia a riga di comando gcloud.
  3. Aggiorna l'interfaccia a riga di comando gcloud e installa i componenti endpoint:
    gcloud components update
  4. Assicurati che l'interfaccia a riga di comando di Google Cloud (gcloud) sia autorizzata ad accedere ai tuoi dati e servizi su Google Cloud:
    gcloud auth login
    Seleziona un account nella nuova scheda del browser che si apre.
  5. Imposta il progetto predefinito sull'ID progetto:
    gcloud config set project YOUR_PROJECT_ID

    Sostituisci YOUR_PROJECT_ID con l'ID progetto. Se hai altri progetti Google Cloud e vuoi utilizzare gcloud per gestirli, consulta la sezione sulla gestione delle configurazioni dell'interfaccia a riga di comando gcloud.

  6. Installa kubectl:
    gcloud components install kubectl
  7. Acquisisci nuove credenziali utente da utilizzare per le credenziali predefinite dell'applicazione. Per autorizzare kubectl sono necessarie le credenziali dell'utente.
    gcloud auth application-default login
    Seleziona un account nella nuova scheda del browser che si apre.

Download del codice di esempio

Per aiutarti a iniziare rapidamente, il codice di esempio viene fornito in diverse lingue. Per scaricare il codice di esempio sul computer locale:

Java

Per clonare o scaricare l'API di esempio:

  1. Clona il repository delle app di esempio sul tuo computer locale:
    git clone https://github.com/GoogleCloudPlatform/java-docs-samples

    In alternativa, scarica l'esempio come file ZIP ed estrailo.

  2. Passa alla directory che contiene il codice di esempio:
    cd java-docs-samples/endpoints/getting-started
Python

Per clonare o scaricare l'API di esempio:

  1. Clona il repository delle app di esempio sul tuo computer locale:
    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    In alternativa, scarica l'esempio come file ZIP ed estrailo.

  2. Passa alla directory che contiene il codice di esempio:
    cd python-docs-samples/endpoints/getting-started
Vai

Per clonare o scaricare l'API di esempio:

  1. Assicurati che sia impostata la variabile di ambiente GOPATH.
  2. Clona il repository delle app di esempio sul tuo computer locale:
    go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
  3. Passa alla directory che contiene il codice di esempio:
    cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
PHP

Per clonare o scaricare l'API di esempio:

  1. Clona il repository delle app di esempio sul tuo computer locale:
    git clone https://github.com/GoogleCloudPlatform/php-docs-samples

    In alternativa, scarica l'esempio come file ZIP ed estrailo.

  2. Passa alla directory che contiene il codice di esempio:
    cd php-docs-samples/endpoints/getting-started
Ruby

Per clonare o scaricare l'API di esempio:

  1. Clona il repository delle app di esempio sul tuo computer locale:
    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

    In alternativa, scarica l'esempio come file ZIP ed estrailo.

  2. Passa alla directory che contiene il codice di esempio:
    cd ruby-docs-samples/endpoints/getting-started
NodeJS

Per clonare o scaricare l'API di esempio:

  1. Clona il repository delle app di esempio sul tuo computer locale:
    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

    In alternativa, scarica l'esempio come file ZIP ed estrailo.

  2. Passa alla directory che contiene il codice di esempio:
    cd nodejs-docs-samples/endpoints/getting-started

Configurazione di Endpoints

Il codice di esempio include il file di configurazione di OpenAPI, openapi.yaml, basato sulla versione OpenAPI v2.0. Per configurare endpoint:

  1. Nella directory del codice di esempio, apri il file di configurazione di openapi.yaml.

    Tieni presente quanto segue:

    • Nell'esempio di configurazione vengono visualizzate le linee vicino al campo host, che devi modificare. Per eseguire il deployment del file openapi.yaml in Endpoints, è richiesto il documento OpenAPI completo.
    • Il file di esempio openapi.yaml contiene una sezione per la configurazione dell'autenticazione non necessaria per questo tutorial. Non è necessario configurare le righe con YOUR-SERVICE-ACCOUNT-EMAIL e YOUR-CLIENT-ID.
    • OpenAPI è una specifica indipendente dal linguaggio. Per praticità, lo stesso file openapi.yaml è nell'esempio getting-started di ogni repository GitHub in una lingua.
  2. Nel campo host, sostituisci il testo con il nome del servizio Endpoint, che deve essere nel seguente formato:
    host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
    

    Sostituisci YOUR_PROJECT_ID con l'ID progetto di Google Cloud. Ad esempio:

    host: "echo-api.endpoints.example-project-12345.cloud.goog"
    

Tieni presente che echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog è il nome del servizio Endpoints. Non è il nome di dominio completo (FQDN) che utilizzi per inviare richieste all'API.

Per informazioni sui campi del documento di OpenAPI richiesti dagli endpoint, consulta la sezione Configurare gli endpoint.

Dopo aver completato tutti i passaggi di configurazione successivi necessari per inviare correttamente le richieste all'API di esempio con un indirizzo IP, consulta la sezione Configurazione del DNS endpoint per informazioni su come configurare echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog in modo che sia il nome di dominio completo.

Eseguire il deployment della configurazione di Endpoints

Per eseguire il deployment della configurazione degli endpoint, utilizza il comando gcloud endpoints services deploy. Questo comando utilizza Service Management per creare un servizio gestito.

Per eseguire il deployment della configurazione degli endpoint:

  1. Assicurati di essere nella directory endpoints/getting-started.
  2. Carica la configurazione e crea un servizio gestito:
    gcloud endpoints services deploy openapi.yaml
    

Il comando gcloud chiama quindi l'API Service Management per creare un servizio gestito con il nome specificato nel campo host del file openapi.yaml. Service Management configura il servizio in base alle impostazioni nel file openapi.yaml. Quando apporti modifiche a openapi.yaml, devi eseguire nuovamente il deployment del file per aggiornare il servizio endpoint.

Durante la creazione e la configurazione del servizio, Service Management trasmette informazioni al terminale. Puoi ignorare gli avvisi relativi ai percorsi nel file openapi.yaml che non richiedono una chiave API. Una volta completata la configurazione del servizio, Gestione servizi visualizza un messaggio con l'ID e il nome del servizio, simile al seguente:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

Nell'esempio precedente, 2017-02-13r0 è l'ID configurazione del servizio e echo-api.endpoints.example-project-12345.cloud.goog è il servizio endpoint. L'ID configurazione servizio è costituito da un timestamp, seguito da un numero di revisione. Se esegui nuovamente il deployment del file openapi.yaml lo stesso giorno, il numero di revisione viene incrementato nell'ID configurazione del servizio. Puoi visualizzare la configurazione del servizio Endpoints nella pagina Endpoint >Servizi in Google Cloud Console.

Se ricevi un messaggio di errore, vedi Risolvere i problemi di deployment della configurazione degli endpoint.

Verifica dei servizi richiesti

Come minimo, endpoint ed ESP richiedono l'attivazione 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 comando gcloud endpoints services deploy abilita questi servizi obbligatori. 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 endpoint in un progetto Google Cloud esistente in cui questi servizi sono stati disabilitati esplicitamente.

Utilizza il seguente comando 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

Attiva anche il servizio Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Per determinare il ENDPOINTS_SERVICE_NAME puoi:

  • Dopo aver eseguito il deployment della configurazione Endpoint, vai alla pagina Endpoint in Cloud Console. L'elenco dei possibili ENDPOINTS_SERVICE_NAME è riportato nella colonna Service name (Nome servizio).

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

Per maggiori informazioni sui comandi gcloud, consulta i servizi gcloud.

Esegui il deployment del backend dell'API

Finora hai eseguito il deployment del documento OpenAPI in Service Management, ma non hai ancora eseguito il deployment del codice necessario per il backend dell'API. Questa sezione ti spiega come eseguire il deployment di container predefiniti per l'API di esempio e ESPv2 al cluster.

Verifica autorizzazioni richieste

ESP e ESPv2 chiamano i servizi Google che utilizzano IAM per verificare se l'identità chiamante dispone di autorizzazioni sufficienti per accedere alle risorse IAM utilizzate. L'identità chiamante è l'account di servizio associato che esegue il deployment di ESP e ESPv2.

Quando viene eseguito il deployment nel pod GKE, l'account di servizio associato corrisponde all'account di servizio nodo. Di solito è l'account di servizio predefinito di Compute Engine. Segui questo consiglio per l'autorizzazione per scegliere un account di servizio nodo corretto.

Se si utilizza Workload Identity, per comunicare con i servizi Google può essere utilizzato un account di servizio diverso dall'account di servizio nodo. Puoi creare un account di servizio Kubernetes per il pod per eseguire ESP e ESPv2, creare un account di servizio Google e associare l'account di servizio Kubernetes all'account di servizio Google.

Segui questi passaggi per associare un account di servizio Kubernetes a un account di servizio Google. Questo account di servizio Google è l'account di servizio associato.

Se l'account di servizio associato è l'account di servizio predefinito di Compute Engine del progetto e la configurazione del servizio di endpoint è stata sottoposta a deployment nello stesso progetto, l'account di servizio dovrebbe avere autorizzazioni sufficienti per accedere alle risorse IAM. È possibile ignorare il passaggio di configurazione dei ruoli IAM. In caso contrario, sarà necessario aggiungere i seguenti ruoli IAM all'account di servizio collegato.

Aggiungi i ruoli IAM richiesti:

Questa sezione descrive le risorse IAM utilizzate da ESP e ESPv2 e i ruoli IAM richiesti dall'account di servizio collegato per accedere a tali risorse.

Configurazione del servizio endpoint

ESP e ESPv2 chiamano il Controllo servizio che utilizza la configurazione del servizio endpoint. La configurazione del servizio endpoint è una risorsa IAM e ESP e ESPv2 richiedono il ruolo Controller di servizio per accedervi.

Il ruolo IAM si trova nella configurazione del servizio di endpoint, non nel progetto. Un progetto può avere più configurazioni di servizi endpoint.

Utilizza il seguente comando gcloud per aggiungere il ruolo all'account di servizio associato per la configurazione del servizio Endpoint.

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/servicemanagement.serviceController

Dove
* SERVICE_NAME è il nome del servizio di endpoint
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com è l'account di servizio associato.

Cloud Trace

ESP e ESPv2 chiamano il servizio Cloud Trace per esportare Trace in un progetto. Questo progetto è chiamato progetto di tracciamento. In ESP, il progetto di tracciamento e il progetto che possiede la configurazione del servizio di endpoint sono gli stessi. In ESPv2, il progetto di tracciamento può essere specificato dal flag --tracing_project_id e presenta l'impostazione predefinita per il progetto di deployment.

ESP e ESPv2 richiedono il ruolo Agente Cloud Trace per abilitare Cloud Trace.

Utilizza il seguente comando gcloud per aggiungere il ruolo all'account di servizio associato:

gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/cloudtrace.agent

Dove
* TRACING_PROJECT_ID è l'ID progetto di tracciamento
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com è l'account di servizio associato. Per maggiori informazioni, consulta la pagina Cosa sono i ruoli e le autorizzazioni?

Deployment dei container nel cluster

I container offrono un meccanismo di pacchettizzazione logico in cui è possibile astrarre le applicazioni dall'ambiente in cui vengono effettivamente eseguite. Utilizza la procedura seguente per eseguire il deployment dell'API di esempio e di ESPv2 nel cluster. Per eseguire il deployment dei container nel cluster:

  1. Recupera le credenziali del cluster e rendile disponibili a kubectl:
        gcloud container clusters get-credentials NAME --zone ZONE
        
    Sostituisci NAME con il nome del cluster e ZONE con la zona del cluster.
  2. Eseguire il deployment di un servizio Kubernetes nel cluster GKE. Il servizio Kubernetes implementa l'API. git clone questo repository, cd getting-started/ per inserire nella cartella e modificare il file di configurazione di Kubernetes LANG-deployment.yaml, e sostituire SERVICE_NAME nelle opzioni di avvio di ESPv2 con il nome del tuo servizio.

    Java
    - name: esp
      image: gcr.io/endpoints-release/endpoints-runtime:2
      args: [
        "--listener_port=8081",
        "--backend=127.0.0.1:8080",
        "--service=SERVICE_NAME",
        "--rollout_strategy=managed",
        "--healthz=/healthz",
      ]
      readinessProbe:
        httpGet:
          path: /healthz
          port: 8081
    Python
    - name: esp
      image: gcr.io/endpoints-release/endpoints-runtime:2
      args: [
        "--listener_port=8081",
        "--backend=http://127.0.0.1:8080",
        "--service=SERVICE_NAME",
        "--rollout_strategy=managed",
        "--healthz=/healthz",
      ]
      readinessProbe:
        httpGet:
          path: /healthz
          port: 8081
    Vai
    - name: esp
      image: gcr.io/endpoints-release/endpoints-runtime:2
      args: [
        "--listener_port", "8081",
        "--backend", "127.0.0.1:8080",
        "--service", "SERVICE_NAME",
        "--rollout_strategy", "managed",
        "--healthz=/healthz",
      ]
      readinessProbe:
        httpGet:
          path: /healthz
          port: 8081
    NodeJS
    - name: esp
      image: gcr.io/endpoints-release/endpoints-runtime:2
      args: [
        "--listener_port", "8081",
        "--backend", "127.0.0.1:8080",
        "--service", "SERVICE_NAME",
        "--rollout_strategy", "managed",
        "--healthz=/healthz",
      ]
      readinessProbe:
        httpGet:
          path: /healthz
          port: 8081

    Ad esempio:

      args: [
        "--listener_port=8081",
        "--backend=http://127.0.0.1:8080",
        "--service=echo-api.endpoints.example-project-12345.cloud.goog ",
        "--rollout_strategy=managed",
      ]
    

    L'opzione --rollout_strategy=managed configura ESPv2 in modo che utilizzi l'ultima configurazione del servizio di cui è stato eseguito il deployment. Quando specifichi questa opzione, entro un minuto dal deployment di una nuova configurazione del servizio, ESPv2 rileva la modifica e inizia automaticamente a utilizzarla. Ti consigliamo di specificare questa opzione invece di fornire un ID di configurazione specifico per ESPv2. Per informazioni sulle altre opzioni di ESPv2 utilizzate, consulta le opzioni di avvio di ESPv2.

  3. Avvia il servizio Kubernetes utilizzando il comando kubectl apply:

    Java
    kubectl apply -f java-deployment.yaml
    Python
    kubectl apply -f python-deployment.yaml
    Vai
    kubectl apply -f golang-deployment.yaml
    PHP
    kubectl apply -f php-deployment.yaml
    Ruby
    kubectl apply -f ruby-deployment.yaml
    NodeJS
    kubectl apply -f nodejs-deployment.yaml

Se ricevi un messaggio di errore, consulta Risoluzione dei problemi di endpoint in GKE. Per ulteriori informazioni, consulta Deployment del backend dell'API.

Recupero dell'indirizzo IP esterno del cluster

Per inviare richieste all'API, devi avere l'IP esterno del servizio. Dopo aver avviato il servizio nel container, possono essere necessari alcuni minuti prima che l'indirizzo IP esterno sia pronto.

  1. Visualizza l'indirizzo IP esterno: kubectl get ingress
  2. Prendi nota del valore di EXTERNAL-IP. Questo indirizzo IP viene utilizzato quando invii una richiesta all'API di esempio.

Inviare una richiesta tramite un indirizzo IP

Ora che il servizio è in esecuzione nel cluster del container e che hai l'indirizzo IP esterno, puoi inviare richieste all'API.

Creare una chiave API e impostare una variabile di ambiente

Il codice di esempio richiede una chiave API. Per semplificare la richiesta, imposta una variabile di ambiente per la chiave API.

  1. Nello stesso progetto Google Cloud che hai utilizzato per l'API, crea una chiave API nella pagina delle credenziali. Se vuoi creare una chiave API in un progetto Google Cloud diverso, vedi Abilitare un'API nel tuo progetto Google Cloud.

    Vai alla pagina Credenziali

  2. Fai clic su Crea credenziali, quindi seleziona Chiave API.
  3. Copia la chiave negli appunti.
  4. Fai clic su Chiudi.
  5. Sul computer locale, incolla la chiave API per assegnarla a una variabile di ambiente:
    • In Linux o macOS: export ENDPOINTS_KEY=AIza...
    • In Windows PowerShell: $Env:ENDPOINTS_KEY="AIza..."

Invia la richiesta

Linux o mac OS

Utilizza curl per inviare una richiesta HTTP tramite la variabile di ambiente ENDPOINTS_KEY impostata in precedenza. Sostituisci IP_ADDRESS con l'indirizzo IP esterno dell'istanza.

curl --request POST \
   --header "content-type:application/json" \
   --data '{"message":"hello world"}' \
   "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"

Nel curl precedente:

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

PowerShell

Utilizza Invoke-WebRequest per inviare una richiesta HTTP utilizzando la variabile di ambiente ENDPOINTS_KEY che hai impostato in precedenza. Sostituisci IP_ADDRESS con l'indirizzo IP esterno della tua istanza.

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").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 che segue gli schizzi in sospeso. 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 Postman, l'estensione del browser Chrome.

  • Seleziona POST come verbo HTTP.
  • Per l'intestazione, seleziona la chiave content-type e il valore application/json.
  • Nel corpo, inserisci quanto segue:
    {"message":"hello world"}
  • Nell'URL, utilizza la chiave API effettiva anziché la variabile di ambiente. Ad esempio:
    http://192.0.2.0:80/echo?key=AIza...

L'API fa eco sul messaggio che invii e risponde con quanto segue:

{
  "message": "hello world"
}

Se non hai ricevuto una risposta corretta, consulta la sezione Risolvere gli errori di risposta.

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

Monitora l'attività dell'API

Per monitorare l'attività dell'API:

  1. Guarda i grafici delle attività per la tua API nella pagina Endpoint > Servizi.

    Vai alla pagina Servizi di endpoint


    Potrebbe essere necessario qualche minuto prima che la richiesta venga riportata nei grafici.
  2. Esamina i log delle richieste relativi alla tua API nella pagina Esplora log.

    Vai alla pagina Esplora log

Configurazione del DNS per gli endpoint

Poiché il nome del servizio Endpoints per l'API si trova nel dominio .endpoints.YOUR_PROJECT_ID.cloud.goog, puoi utilizzarlo come nome di dominio completo (FQDN) apportando una piccola modifica alla configurazione nel file openapi.yaml. In questo modo, puoi inviare richieste all'API di esempio utilizzando echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog anziché l'indirizzo IP.

Per configurare il DNS degli endpoint:

  1. Apri il file di configurazione OpenAPI openapi.yaml e aggiungi la proprietà x-google-endpoints al primo livello del file (non rientrato o nidificato) come mostrato nel seguente snippet:
    host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
    x-google-endpoints:
    - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
      target: "IP_ADDRESS"
    
  2. Nella proprietà name, sostituisci YOUR_PROJECT_ID con l'ID progetto.
  3. Nella proprietà target, sostituisci IP_ADDRESS con l'indirizzo IP che hai utilizzato quando hai inviato una richiesta all'API di esempio.
  4. Esegui il deployment del file di configurazione OpenAPI aggiornato in Service Management:
    gcloud endpoints services deploy openapi.yaml
    

Ad esempio, supponiamo che il file openapi.yaml sia configurato come segue:

host: "echo-api.endpoints.example-project-12345.cloud.goog"
x-google-endpoints:
- name: "echo-api.endpoints.example-project-12345.cloud.goog"
  target: "192.0.2.1"

Quando esegui il deployment del file openapi.yaml utilizzando il comando gcloud precedente, Service Management crea un record A DNS, echo-api.endpoints.my-project-id.cloud.goog, che si risolve nell'indirizzo IP di destinazione, 192.0.2.1. La propagazione della nuova configurazione DNS potrebbe richiedere alcuni minuti.

Configurazione di SSL

Per maggiori dettagli su come configurare DNS e SSL, consulta la sezione Abilitare SSL per endpoint.

Invio di una richiesta tramite FQDN

Ora che il record DNS è configurato per l'API di esempio, inviagli una richiesta utilizzando il nome di dominio completo (sostituisci YOUR_PROJECT_ID con l'ID progetto) e la variabile di ambiente ENDPOINTS_KEY impostata in precedenza:
  • In Linux o mac OS:
    curl --request POST \
        --header "content-type:application/json" \
        --data '{"message":"hello world"}' \
        "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"
  • In Windows PowerShell:
    (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content

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 ulteriori informazioni, 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.

Per informazioni su come interrompere i servizi utilizzati da questo tutorial, consulta la sezione Eliminare un'API e istanze API.

Passaggi successivi