Inizia a utilizzare Cloud Endpoints per i gruppi di istanze gestite (MIG) con ESPv2

OpenAPI   |  gRPC

Questo tutorial mostra come configurare ed eseguire il deployment di un'API di esempio e di Extensible Service Proxy V2 (ESPv2) in esecuzione in container Docker predefiniti su gruppi di istanze gestite (MIG) .

L'API REST del codice campione è descritta utilizzando la specifica OpenAPI. Il tutorial mostra anche come creare una chiave API e utilizzarla nelle richieste all'API.

Per una panoramica di Cloud Endpoints, consulta Informazioni su Endpoints e Architettura di Endpoints.

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. Scarica il codice campione. Consulta la sezione Recupera il codice di esempio.
3. Configura il file openapi.yaml, che viene utilizzato per configurare Endpoints. Vedi Configurazione di Endpoints.
4. Esegui il deployment della configurazione di Endpoints per creare un servizio Endpoints. Vedi Deployment della configurazione di Endpoints.
5. Esegui il deployment dell'API e di ESPv2 nel backend del gruppo di istanze gestite (MIG). Consulta Esegui il deployment del backend dell'API.
6. Invia una richiesta all'API utilizzando un indirizzo IP. Consulta Invio di una richiesta utilizzando l'indirizzo IP.
7. Configura un record DNS per l'API di esempio. Consulta Configurazione del DNS per Endpoints.
8. Invia una richiesta all'API utilizzando il nome di dominio completo. Consulta la sezione Invio di una richiesta utilizzando l'FQDN.
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 vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

• Compute Engine
• Endpoints

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi.

I nuovi utenti di Google Cloud 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 saperne di più, consulta Esegui la pulizia.

Prima di iniziare

Prima di iniziare

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.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

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

2. 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 download e release.
   • Utenti Windows: questo tutorial fornisce un esempio che utilizza Invoke-WebRequest, che è supportato in PowerShell 3.0 e versioni successive.
3. Scarica Google Cloud CLI.
4. Aggiorna gcloud CLI e installa i componenti di Endpoints.

   gcloud components update

5. Assicurati che Google Cloud CLI (gcloud) sia autorizzata ad accedere ai tuoi dati e servizi su Google Cloud:

   gcloud auth login

   Nella nuova scheda del browser che si apre, seleziona un account.
6. 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 Gestione delle configurazioni di gcloud CLI.

Al termine delle attività descritte in questo documento, puoi evitare l'addebito di ulteriori costi eliminando le risorse che hai creato. Per saperne di più, consulta Esegui la pulizia.

Download del codice campione

Scarica il codice campione sulla tua macchina locale.

Java

Per clonare o scaricare l'API di esempio:

1. Clona il repository dell'app di esempio sulla tua macchina 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 dell'app di esempio sulla tua macchina 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 la variabile di ambiente GOPATH sia impostata.
2. Clona il repository dell'app di esempio sulla tua macchina 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 dell'app di esempio sulla tua macchina 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 dell'app di esempio sulla tua macchina 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 dell'app di esempio sulla tua macchina 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

Devi disporre di un documento OpenAPI basato su OpenAPI 2.0 o OpenAPI 3.x che descriva la superficie delle tue app e qualsiasi requisito di autenticazione. Per saperne di più, consulta Versioni di OpenAPI supportate.

Devi anche aggiungere un campo specifico di Google che contenga l'URL di ogni app in modo che ESPv2 disponga delle informazioni necessarie per richiamare un'app. Se non hai familiarità con OpenAPI, consulta la panoramica di OpenAPI per saperne di più.

OpenAPI 2.0

Per configurare Endpoints utilizzando una specifica OpenAPI 2.0, puoi utilizzare il file openapi.yaml disponibile nella directory endpoints/getting-started del codice campione scaricato.

I contenuti della specifica OpenAPI 2.0 dovrebbero essere simili ai seguenti:

swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"

host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"

consumes:
  - "application/json"
produces:
  - "application/json"

schemes:
# Uncomment the next line if you configure SSL for this API.
# - "https"
  - "http"

paths:
  /echo:
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
        - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
        -
          description: "Message to echo"
          in: body
          name: message
          required: true
          schema:
            $ref: "#/definitions/echoMessage"
      security:
        - api_key: []
  /auth/info/googlejwt:
    get:
      description: "Returns the requests' authentication information."
      operationId: "auth_info_google_jwt"
      produces:
        - "application/json"
      responses:
        200:
          description: "Authenication info."
          schema:
            $ref: "#/definitions/authInfoResponse"
      security:
        - api_key: []
          google_jwt: []
  /auth/info/googleidtoken:
    get:
      description: "Returns the requests' authentication information."
      operationId: "authInfoGoogleIdToken"
      produces:
        - "application/json"
      responses:
        200:
          description: "Authentication info."
          schema:
            $ref: "#/definitions/authInfoResponse"
      security:
        - api_key: []
          google_id_token: []

definitions:
  echoMessage:
    type: "object"
    properties:
      message:
        type: "string"
  authInfoResponse:
    properties:
      id:
        type: "string"
      email:
        type: "string"

securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"

  # This section configures authentication using Google API Service Accounts
  # to sign a json web token. This is mostly used for server-to-server
  # communication.
  google_jwt:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    # This must match the 'iss' field in the JWT.
    x-google-issuer: "jwt-client.endpoints.sample.google.com"
    # Update this with your service account's email address.
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR_SERVICE_ACCOUNT_EMAIL"
    # This must match the "aud" field in the JWT. You can add multiple
    # audiences to accept JWTs from multiple clients.
    x-google-audiences: "echo.endpoints.sample.google.com"
  # This section configures authentication using Google OAuth2 ID Tokens.
  # ID Tokens can be obtained using OAuth2 clients, and can be used to access
  # your API on behalf of a particular user.

  google_id_token:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v3/certs"
    # Your OAuth2 client's Client ID must be added here. You can add
    # multiple client IDs to accept tokens from multiple clients.
    x-google-audiences: "YOUR_CLIENT_ID"

OpenAPI 3.x

Per configurare Endpoints utilizzando una specifica OpenAPI 3.x, puoi sostituire i contenuti del file openapi.yaml disponibile nella directory endpoints/getting-started decodice campioneio scaricato:

1. Apri il file openapi.yaml nell'editor di testo e sostituisci i contenuti con i seguenti:

   openapi: 3.0.4
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   servers:
     - url: "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
       x-google-endpoint: {}
   
   paths:
     "/echo":
       post:
         description: "Echo back a given message."
         operationId: "echo"
         requestBody:
           description: "Message to echo"
           required: true
           content:
             "application/json":
               schema:
                 $ref: "#/components/schemas/echoMessage"
         responses:
           '200':
             description: "Echo"
             content:
               "application/json":
                 schema:
                   $ref: "#/components/schemas/echoMessage"
         security:
           - api_key: []
   
     "/auth/info/googlejwt":
       get:
         description: "Returns the requests' authentication information."
         operationId: "auth_info_google_jwt"
         responses:
           '200':
             description: "Authentication info."
             content:
               "application/json":
                 schema:
                   $ref: "#/components/schemas/authInfoResponse"
         security:
           - api_key: []
             google_jwt: []
   
     "/auth/info/googleidtoken":
       get:
         description: "Returns the requests' authentication information."
         operationId: "authInfoGoogleIdToken"
         responses:
           '200':
             description: "Authentication info."
             content:
               "application/json":
                 schema:
                   $ref: "#/components/schemas/authInfoResponse"
         security:
           - api_key: []
             google_id_token: []
   
   components:
     schemas:
       echoMessage:
         type: "object"
         properties:
           message:
             type: "string"
       authInfoResponse:
         properties:
           id:
             type: "string"
           email:
             type: "string"
   
     securitySchemes:
       api_key:
         type: "apiKey"
         name: "key"
         in: "query"
   
       google_jwt:
         type: "oauth2"
         flows:
           implicit:
             authorizationUrl: ""
             scopes: {}
         x-google-auth:
           issuer: "jwt-client.endpoints.sample.google.com"
           jwksUri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR_SERVICE_ACCOUNT_EMAIL"
           audiences: "echo.endpoints.sample.google.com"
   
       google_id_token:
         type: "oauth2"
         flows:
           implicit:
             authorizationUrl: ""
             scopes: {}
         x-google-auth:
           issuer: "https://accounts.google.com"
           jwksUri: "https://www.googleapis.com/oauth2/v3/certs"
           audiences:
             - "YOUR_CLIENT_ID"

2. Salva i nuovi contenuti di openapi.yaml.

Nota :il file openapi.yaml di esempio contiene una sezione per la configurazione dell'autenticazione che non è necessaria per questo tutorial. Non è necessario configurare le righe con YOUR_SERVICE_ACCOUNT_EMAIL e YOUR_CLIENT_ID.

Questo tutorial utilizza un'estensione specifica di Google della specifica OpenAPI che consente di configurare il nome del servizio. Il metodo per specificare il nome del servizio dipende dalla versione della specifica OpenAPI che stai utilizzando.

OpenAPI 2.0

Utilizza il campo host per specificare il nome del servizio:

host: echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog

Per configurare Endpoints:

1. Apri il file openapi.yaml.
2. Nel campo host, sostituisci YOUR_PROJECT_ID con l'ID del tuo progetto Google Cloud .
3. Salva il file openapi.yaml.

OpenAPI 3.x

Utilizza il campo url nell'oggetto servers per specificare il nome del servizio:

servers:
- url: https://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog
  x-google-endpoint: {}

Per configurare Endpoints:

1. Apri il file openapi.yaml.
2. Se il file openapi.yaml ha un campo host, rimuovilo.
3. Aggiungi un oggetto servers come mostrato.
4. Nel campo url, sostituisci YOUR_PROJECT_ID con l'ID del tuo progetto Google Cloud .
5. Salva il file openapi.yaml.

Dopo aver completato tutti i seguenti passaggi di configurazione in modo da poter inviare correttamente richieste all'API di esempio utilizzando un indirizzo IP, consulta Configurazione del DNS di Endpoints per informazioni su come configurare echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog in modo che sia il nome di dominio completo (FQDN).

esegui il deployment della configurazione di Endpoints

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

Per eseguire il deployment della configurazione di Endpoints:

1. Assicurati di trovarti nella directory in cui si trova il file di configurazione openapi.yaml.
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 o servers.url 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 Endpoints.

Durante la creazione e la configurazione del servizio, Service Management visualizza le informazioni nel terminale. Puoi ignorare tranquillamente gli avvisi sui percorsi nel file openapi.yaml che non richiedono una chiave API. Al termine della configurazione del servizio, Service Management visualizza un messaggio con l'ID configurazione del servizio 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 di configurazione del servizio e echo-api.endpoints.example-project-12345.cloud.goog è il servizio Endpoints. L'ID configurazione del servizio è composto da un timestamp seguito da un numero di revisione. Se esegui di nuovo il deployment del file openapi.yaml nello stesso giorno, il numero di revisione viene incrementato nell'ID configurazione del servizio. Puoi visualizzare la configurazione del servizio Endpoints nella pagina Endpoints > Servizi nella console Google Cloud .

Se ricevi un messaggio di errore, consulta Risoluzione dei problemi di deployment della configurazione di Endpoints.

Controllo dei servizi richiesti

Come minimo, Endpoints ed ESP richiedono l'abilitazione dei seguenti servizi Google:

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

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 saperne di più sui comandi gcloud, consulta servizi gcloud.

Deployment del backend dell'API

Crea un modello di istanza

Crea un modello da utilizzare per creare un gruppo di istanze VM. Ogni istanza creata dal modello avvia un ESPv2 e un server delle applicazioni di backend.

1. Nella console Google Cloud , vai alla pagina Template di istanza.

   Vai a Template di istanza

2. Fai clic su Crea modello istanza.

3. In Nome, inserisci load-balancing-espv2-template.

4. In Configurazione macchina, imposta Tipo di macchina su e2-micro.

5. Nella sezione Disco di avvio, imposta Immagine su Container Optimized OS stable version.

6. In Firewall, seleziona Consenti traffico HTTP.

7. Fai clic su Gestione, sicurezza, dischi, networking, single-tenancy per visualizzare le impostazioni avanzate.

8. Fai clic sulla scheda Gestione. In Automazione, inserisci il seguente script di avvio. Ricordati di aggiornare ENDPOINTS_SERVICE_NAME.

   sudo docker network create --driver bridge esp_net
   sudo docker run \
     --detach \
     --name=echo \
     --net=esp_net \
     gcr.io/google-samples/echo-python:1.0
   sudo docker run \
     --detach \
     --name=esp \
     --publish=80:9000 \
     --net=esp_net \
     gcr.io/endpoints-release/endpoints-runtime:2 \
     --service=ENDPOINTS_SERVICE_NAME \
     --rollout_strategy=managed \
     --listener_port=9000 \
     --healthz=/healthz \
     --backend=echo:8080
   

   Lo script recupera, installa e avvia il server delle applicazioni echo e il server proxy ESPv2 all'avvio dell'istanza.

9. Fai clic su Crea.

Attendi il completamento della creazione del modello prima di continuare.

Crea un gruppo di istanze gestite a livello di regione

Per eseguire l'applicazione, utilizza il modello di istanza per creare un gruppo di istanze gestite a livello di regione:

1. Nella console Google Cloud , vai alla pagina Gruppi di istanze.

   Vai a Gruppi di istanze

2. Fai clic su Crea gruppo di istanze.

3. In Nome, inserisci load-balancing-espv2-group.

4. In Località, seleziona Più zone.

   Suggerimento avanzato: per assicurarti che sia disponibile nel corso di eventi estremi, come interruzioni a livello di zona, Compute Engine consiglia di distribuire l'applicazione in più zone.

5. In Regione, seleziona us-central1.

6. Fai clic sul menu a discesa Configura zone per visualizzare Zone. Seleziona le seguenti zone:

   • us-central1-b
   • us-central1-c
   • us-central1-f

7. In Template di istanza, seleziona load-balancing-espv2-template.

8. In Scalabilità automatica, seleziona Non scalare automaticamente.

9. Imposta Numero di istanze su 3.

   Suggerimento avanzato: quando crei un gruppo di istanze gestite a livello di regione, Compute Engine consiglia di eseguire il provisioning di un numero sufficiente di istanze in modo che, se le istanze di una zona non sono disponibili, quelle rimanenti soddisfino comunque il numero minimo di istanze richiesto. Tuttavia, l'esecuzione del provisioning di più istanze del necessario potrebbe comportare costi aggiuntivi. Per ulteriori informazioni, consulta Selezione delle dimensioni del gruppo di istanze per garantire la disponibilità.

10. In Ridistribuzione delle istanze, seleziona On.

11. In Riparazione automatica e Controllo di integrità, seleziona Nessun controllo di integrità.

12. Fai clic su Crea. Verrà visualizzata nuovamente la pagina Gruppi di istanze.

    Nota: potrebbe essere necessario attendere alcuni minuti affinché tutte le istanze del gruppo siano in esecuzione e pronte a visualizzare l'applicazione web.

Crea un bilanciatore del carico

Questa sezione illustra i passaggi necessari per creare un bilanciatore del carico globale che indirizzi il traffico HTTP al tuo gruppo di istanze.

Questo bilanciatore del carico utilizza un frontend per ricevere il traffico in entrata e un backend per distribuire questo traffico alle istanze integre. Poiché il bilanciatore del carico è costituito da più componenti, questa attività è suddivisa in più parti:

• Configurazione backend
• Configurazione frontend
• Esamina e finalizza

Completa tutti i passaggi per creare il bilanciatore del carico.

1. Nella console Google Cloud , vai alla pagina Crea un bilanciatore del carico.

   Vai a Crea un bilanciatore del carico

2. Nella sezione Bilanciatore del carico delle applicazioni (HTTP/S), fai clic su Avvia configurazione.

3. In Per internet o solo interno, seleziona Da internet alle mie VM. poi fai clic su Continua.

4. In Nome del bilanciatore del carico, inserisci espv2-load-balancer.

Configurazione backend

1. Nel riquadro sinistro della pagina Crea bilanciatore del carico delle applicazioni esterno globale, fai clic su Configurazione backend.
2. Fai clic su Crea o seleziona servizi di backend e bucket di backend per aprire un menu a discesa. Fai clic su Servizi di backend, quindi su Crea un servizio di backend.
3. Nella nuova finestra, come Nome dell'applicazione di backend inserisci espv2-backend.
4. Imposta Gruppo di istanze su load-balancing-espv2-group.
5. Imposta Numeri di porta su 80. In questo modo, consenti il traffico HTTP tra il bilanciatore del carico e il gruppo di istanze.
6. In Modalità di bilanciamento, seleziona Utilizzo.
7. Fai clic su Fine per creare il backend.

8. Crea il controllo di integrità per il backend del bilanciatore del carico:

   Suggerimento avanzato: i controlli di integrità vengono utilizzati sia per il bilanciamento del carico che per la riparazione automatica, ma con finalità diverse:

   • I controlli di integrità per il bilanciamento del carico vengono utilizzati per rilevare le istanze che non rispondono e per indirizzare il traffico lontano da queste.
   • I controlli di integrità per la riparazione automatica vengono utilizzati per rilevare e ricreare le istanze non riuscite.

   Utilizza controlli di integrità separati per il bilanciamento del carico e per la riparazione automatica. L'utilizzo dello stesso controllo di integrità per questi servizi rimuoverebbe la distinzione tra le istanze che non rispondono e quelle non riuscite, causando latenza e/o indisponibilità non necessarie per gli utenti. Per ulteriori informazioni, consulta Concetti dei controlli di integrità.

   1. In Controllo di integrità, seleziona Crea un controllo di integrità (o Crea un altro controllo di integrità) dal menu a discesa. Viene visualizzata una nuova finestra.
   2. Nella nuova finestra, in Nome, inserisci espv2-load-balancer-check.
   3. Imposta Protocollo su HTTP.
   4. In Porta, inserisci 80.
   5. Per questo tutorial, imposta Percorso richiesta su /healthz, un percorso a cui ESPv2 è configurato per rispondere.

   6. Imposta i seguenti Criteri integrità:

      1. Imposta Intervallo di controllo su 3 secondi. Questa impostazione definisce l'intervallo di tempo dall'inizio di un probe all'inizio di quello successivo.
      2. Imposta Timeout su 3 secondi. Questa impostazione definisce il tempo di attesa da parte di Google Cloud per una risposta a un probe. Il valore deve essere inferiore o uguale all'intervallo di controllo.
      3. Imposta Soglia stato integro su 2 operazioni riuscite consecutive. Questa impostazione definisce il numero di probe sequenziali che devono riuscire affinché l'istanza sia considerata integra.
      4. Imposta Soglia stato non integro su 2 errori consecutivi. Questa impostazione definisce il numero di probe sequenziali che non devono riuscire affinché l'istanza sia considerata non integra.

      Suggerimento avanzato: per informazioni su come perfezionare i valori Intervallo di controllo e Timeout per la tua applicazione, consulta Come funzionano i controlli di integrità. Per perfezionare i valori di Soglia stato integro e Soglia stato non integro per la tua applicazione, utilizza i seguenti criteri:

      • Se il traffico viene indirizzato a istanze con latenza elevata anche quando sono disponibili istanze più veloci, diminuisci la soglia per il traffico rendendo più aggressivo il controllo di integrità.
      • Se il traffico viene reindirizzato lontano dalle istanze con bassa latenza, aumenta la soglia per il traffico rendendo il controllo di integrità più prudente.

      Per informazioni dettagliate su ottimizzazione e misurazione della latenza, consulta Ottimizzazione della latenza delle applicazioni con il bilanciamento del carico.

   7. Fai clic su Salva e continua per creare il controllo di integrità.

9. Fai clic su Crea per creare il servizio di backend.

Configurazione frontend

1. Nel riquadro sinistro della pagina Crea bilanciatore del carico delle applicazioni esterno globale, fai clic su Configurazione frontend.
2. Nella pagina Configurazione frontend, in Nome, inserisci espv2-ipv4-frontend.
3. Imposta Protocollo su HTTP.
4. Imposta Porta su 80.
5. Fai clic su Fine per creare il frontend.

Esamina e finalizza

1. Verifica le impostazioni di bilanciamento del carico prima di creare il bilanciatore del carico:

   1. Nel riquadro a sinistra della pagina Crea bilanciatore del carico delle applicazioni esterno globale, fai clic su Esamina e finalizza.

   2. Nella pagina Esamina e finalizza, verifica le seguenti impostazioni in Backend:

      • Servizio di backend = espv2-backend.
      • Protocollo endpoint = HTTP.
      • Controllo di integrità = espv2-load-balancer-check.
      • Gruppo di istanze = load-balancing-espv2-group.

   3. Nella stessa pagina, verifica che Frontend utilizzi un indirizzo IP con Protocollo HTTP.

2. Nel riquadro a sinistra della pagina Crea bilanciatore del carico delle applicazioni esterno globale, fai clic su Crea per completare la creazione del bilanciatore del carico.

   Potrebbe essere necessario attendere alcuni minuti per il completamento della creazione del bilanciatore del carico.

3. Dopo aver creato il bilanciatore del carico, trova l'indirizzo IP nella pagina Bilanciatore del carico.

   Vai a Bilanciatore del carico

Invio di una richiesta utilizzando un indirizzo IP

Una volta che l'API di esempio e ESPv2 sono in esecuzione sul backend di cui è stato eseguito il deployment, puoi inviare richieste all'API dalla tua macchina locale.

Crea una chiave API e imposta una variabile di ambiente

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

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

   Vai alla pagina Credenziali

2. Fai clic su Crea credenziali e poi 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 macOS

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

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

Nella 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 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"}
• 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 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.

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

Configurazione del DNS per Endpoints

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 di Endpoints:

OpenAPI 2.0

1. Apri il file di configurazione OpenAPI, openapi.yaml, e aggiungi la proprietà x-google-endpoints al livello superiore del file (non rientrata o nidificata) 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
   

OpenAPI 3.x

1. Apri il file di configurazione OpenAPI, openapi.yaml, e aggiungi la proprietà servers.url al livello superiore del file (non rientrata o nidificata) come mostrato nel seguente snippet:

   servers:
     - url: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
       x-google-endpoint:
         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 abbia la seguente configurazione:

OpenAPI 2.0

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"

OpenAPI 3.x

servers:
  - url: "echo-api.endpoints.example-project-12345.cloud.goog"
    x-google-endpoint:
      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 viene risolto nell'indirizzo IP di destinazione, 192.0.2.1. Potrebbero essere necessari alcuni minuti prima che la nuova configurazione DNS venga propagata.

Configurazione di SSL

Per maggiori dettagli su come configurare DNS e SSL, consulta Attivazione di SSL per endpoint.

Invio di una richiesta utilizzando l'FQDN

Ora che hai configurato il record DNS per l'API di esempio, invia una richiesta utilizzando l'FQDN (sostituisci YOUR_PROJECT_ID con l'ID progetto) e la variabile di ambiente ENDPOINTS_KEY impostata in precedenza:

• In Linux o macOS:

  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

monitora l'attività dell'API

Per monitorare l'attività dell'API:

1. Guarda i grafici di attività della tua API nella pagina Endpoints > Servizi.
   

   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

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. Assicurati che gcloud CLI (gcloud) sia autorizzata ad accedere ai tuoi dati e servizi su Google Cloud:

   gcloud auth login
   

2. Inserisci quanto segue per visualizzare gli ID progetto dei tuoi Google Cloud progetti:

   gcloud projects list
   

3. Utilizzando l'ID progetto applicabile del passaggio precedente, imposta il progettoGoogle Cloud predefinito su quello in cui si trova la tua applicazione:

   gcloud config set project [YOUR_PROJECT_ID]
   

4. Ottieni il nome di tutti i servizi gestiti nel tuo progetto Google Cloud :

   gcloud endpoints services list
   

5. Elimina il servizio da Service Management. Sostituisci SERVICE_NAME con il nome del servizio che vuoi rimuovere.

   gcloud endpoints services delete SERVICE_NAME
   

   L'esecuzione di gcloud endpoints services delete non elimina immediatamente il servizio gestito. La gestione dei servizi disattiva il servizio gestito per 30 giorni, il che ti consente di ripristinarlo se necessario. Dopo 30 giorni, Service Management elimina definitivamente il servizio gestito.

6. Vai alla pagina Bilanciatore del carico.

   Vai a Bilanciatore del carico

   Elimina il bilanciatore del carico espv2-load-balancer con il servizio di backend espv2-backend e il controllo di integrità espv2-load-balancer-check.

7. Vai alla pagina Gruppi di istanze.

   Vai a Gruppi di istanze

   Elimina load-balancing-espv2-group

8. Vai alla pagina Modello di istanza.

   Vai a Modelli di istanza

   Elimina load-balancing-espv2-template.

Passaggi successivi

• Condividere l'API con un altro sviluppatore
• Scopri di più sull'autenticazione
• Scopri di più sulle opzioni di assistenza della community