Começar a usar o Cloud Endpoints para grupos de instâncias geridas (MIGs) com o ESPv2

Este tutorial mostra como configurar e implementar uma amostra da API e o Extensible Service Proxy V2 (ESPv2) em execução em contentores Docker pré-criados em Managed Instance Group (MIGs) .

A API REST do exemplo de código é descrita através da especificação OpenAPI. O tutorial também mostra como criar uma chave da API e usá-la em pedidos à API.

Para uma vista geral do Cloud Endpoints, consulte os artigos Acerca dos Endpoints e Arquitetura dos Endpoints.

Objetivos

Use a seguinte lista de tarefas de alto nível à medida que avança no tutorial. Todas as tarefas são necessárias para enviar pedidos com êxito para a API.

  1. Configure um Google Cloud projeto. Consulte a secção Antes de começar.
  2. Transfira o exemplo de código. Consulte o artigo Obter o código de exemplo.
  3. Configure o ficheiro openapi.yaml, que é usado para configurar pontos finais. Consulte o artigo Configurar pontos finais.
  4. Implemente a configuração do Endpoints para criar um serviço do Endpoints. Consulte o artigo Implementar a configuração dos Endpoints.
  5. Implemente a API e o ESPv2 no back-end do grupo de instâncias geridas (GIGs). Consulte o artigo Implementar o back-end da API.
  6. Envie um pedido para a API através de um endereço IP. Consulte o artigo Enviar uma solicitação através do endereço IP.
  7. Configure um registo de DNS para a API de exemplo. Consulte o artigo Configurar o DNS para pontos finais.
  8. Envie um pedido para a API através do nome de domínio totalmente qualificado. Consulte Enviar uma solicitação através do FQDN.
  9. Acompanhe a atividade da API. Consulte o artigo Acompanhamento da atividade da API.
  10. Evite incorrer em cobranças na sua conta Google Cloud . Consulte a secção Limpar.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custos com base na sua utilização prevista, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

Antes de começar

Antes de começar

  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.

    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.

    Go to project selector

  3. Verify 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.

    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.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Tome nota do ID do projeto, uma vez que é necessário mais tarde.

  7. Precisa de uma aplicação para enviar pedidos para a API de exemplo.

    • Utilizadores do Linux e macOS: este tutorial oferece um exemplo de utilização do curl, que normalmente vem pré-instalado no seu sistema operativo. Se não tiver o curl, pode transferi-lo na curl página de lançamentos e transferências.
    • Utilizadores do Windows: este tutorial fornece um exemplo com Invoke-WebRequest, que é suportado no PowerShell 3.0 e posterior.
  8. Transfira a CLI do Google Cloud.
  9. Atualize a CLI gcloud e instale os componentes do Endpoints. 
    gcloud components update
  10. Certifique-se de que a CLI do Google Cloud (gcloud) está autorizada a aceder aos seus dados e serviços em Google Cloud: 
    gcloud auth login
     No novo separador do navegador apresentado, selecione uma conta.
  11. Defina o projeto predefinido para o ID do seu projeto. 
    gcloud config set project YOUR_PROJECT_ID

    Substitua YOUR_PROJECT_ID pelo ID do seu projeto. Se tiver outros Google Cloud projetos e quiser usar gcloud para os gerir, consulte Gerir configurações da CLI gcloud.

    12. Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

Transferir o exemplo de código

Transfira o exemplo de código para o seu computador local.

Java

Para clonar ou transferir a API de exemplo:

  1. Clone o repositório da app de exemplo para a sua máquina local: 
    git clone https://github.com/GoogleCloudPlatform/java-docs-samples

    Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

  2. Altere para o diretório que contém o código de exemplo: 
    cd java-docs-samples/endpoints/getting-started
Python

Para clonar ou transferir a API de exemplo:

  1. Clone o repositório da app de exemplo para a sua máquina local: 
    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

  2. Altere para o diretório que contém o código de exemplo: 
    cd python-docs-samples/endpoints/getting-started
Ir

Para clonar ou transferir a API de exemplo:

  1. Certifique-se de que a variável de ambiente GOPATH está definida.
  2. Clone o repositório da app de exemplo para a sua máquina local: 
    go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
  3. Altere para o diretório que contém o código de exemplo: 
    cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
PHP

Para clonar ou transferir a API de exemplo:

  1. Clone o repositório da app de exemplo para a sua máquina local: 
    git clone https://github.com/GoogleCloudPlatform/php-docs-samples

    Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

  2. Altere para o diretório que contém o código de exemplo: 
    cd php-docs-samples/endpoints/getting-started
Ruby

Para clonar ou transferir a API de exemplo:

  1. Clone o repositório da app de exemplo para a sua máquina local: 
    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

    Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

  2. Altere para o diretório que contém o código de exemplo: 
    cd ruby-docs-samples/endpoints/getting-started
NodeJS

Para clonar ou transferir a API de exemplo:

  1. Clone o repositório da app de exemplo para a sua máquina local: 
    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

    Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

  2. Altere para o diretório que contém o código de exemplo: 
    cd nodejs-docs-samples/endpoints/getting-started

Configurar pontos finais

Tem de ter um documento OpenAPI baseado no OpenAPI 2.0 ou no OpenAPI 3.x que descreva a superfície das suas apps e quaisquer requisitos de autenticação. Para saber mais, consulte o artigo Versões do OpenAPI suportadas.

Também tem de adicionar um campo específico da Google que contenha o URL de cada app para que o ESPv2 tenha as informações necessárias para invocar uma app. Se não conhece o OpenAPI, consulte a vista geral do OpenAPI para mais informações.

OpenAPI 2.0

Para configurar os Endpoints através de uma especificação OpenAPI 2.0, pode usar o ficheiro openapi.yaml disponível no diretório endpoints/getting-started do código de exemplo transferido.

O conteúdo da especificação OpenAPI 2.0 deve ser semelhante ao seguinte:

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

Para configurar os Endpoints através de uma especificação OpenAPI 3.x, pode substituir o conteúdo do ficheiro openapi.yaml disponível no diretório endpoints/getting-started do código de exemplo transferido:

  1. Abra o openapi.yaml no editor de texto e substitua o conteúdo pelo seguinte: 
    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. Guarde o novo conteúdo de openapi.yaml.

Este tutorial usa uma extensão específica da Google à especificação OpenAPI que lhe permite configurar o nome do serviço. O método para especificar o nome do serviço depende da versão da especificação OpenAPI que está a usar.

OpenAPI 2.0

Use o campo host para especificar o nome do serviço:

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

Para configurar pontos finais:

  1. Abra o ficheiro openapi.yaml.
  2. No campo host, substitua YOUR_PROJECT_ID pelo seu Google Cloud ID do projeto.
  3. Guarde o ficheiro openapi.yaml.

OpenAPI 3.x

Use o campo url no objeto servers para especificar o nome do serviço:

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

Para configurar pontos finais:

  1. Abra o ficheiro openapi.yaml.
  2. Se o ficheiro openapi.yaml tiver um campo host, remova-o.
  3. Adicione um objeto servers, conforme mostrado.
  4. No campo url, substitua YOUR_PROJECT_ID pelo seu Google Cloud ID do projeto.
  5. Guarde o ficheiro openapi.yaml.

Depois de concluir todos os passos de configuração seguintes para poder enviar pedidos com êxito para a API de exemplo através de um endereço IP, consulte o artigo Configurar o DNS dos pontos finais para ver informações sobre como configurar echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog para ser o nome de domínio totalmente qualificado (FQDN).

Implementação da configuração dos pontos finais

Para implementar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Este comando usa a gestão de serviços para criar um serviço gerido.

Para implementar a configuração dos Endpoints:

  1. Certifique-se de que está no diretório onde se encontra o ficheiro de configuração openapi.yaml.
  2. Carregue a configuração e crie um serviço gerido: 
    gcloud endpoints services deploy openapi.yaml

O comando gcloud chama a API Service Management para criar um serviço gerido com o nome especificado no campo host ou servers.url do ficheiro openapi.yaml. A gestão de serviços configura o serviço de acordo com as definições no ficheiro openapi.yaml. Quando faz alterações a openapi.yaml, tem de voltar a implementar o ficheiro para atualizar o serviço Endpoints.

À medida que cria e configura o serviço, o Service Management envia informações para o terminal. Pode ignorar com segurança os avisos sobre os caminhos no ficheiro openapi.yaml que não requerem uma chave da API. Quando terminar de configurar o serviço, a gestão de serviços apresenta uma mensagem com o ID de configuração do serviço e o nome do serviço, semelhante ao seguinte:

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

No exemplo anterior, 2017-02-13r0 é o ID de configuração do serviço e echo-api.endpoints.example-project-12345.cloud.goog é o serviço Endpoints. O ID de configuração do serviço consiste numa data/hora seguida de um número de revisão. Se implementar o ficheiro openapi.yaml novamente no mesmo dia, o número de revisão é incrementado no ID de configuração do serviço. Pode ver a configuração do serviço Endpoints na página Endpoints > Serviços na Google Cloud consola.

Se receber uma mensagem de erro, consulte o artigo Resolução de problemas da implementação da configuração de pontos finais.

A verificar os serviços necessários

No mínimo, os pontos finais e o ESP requerem a ativação dos seguintes serviços Google:
Nome Título
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

Na maioria dos casos, o comando gcloud endpoints services deploy ativa estes serviços obrigatórios. No entanto, o comando gcloud é concluído com êxito, mas não ativa os serviços necessários nas seguintes circunstâncias:

  • Se usou uma aplicação de terceiros, como o Terraform, e não incluiu estes serviços.

  • Implementou a configuração do Endpoints numGoogle Cloud projeto existente no qual estes serviços foram explicitamente desativados.

Use o seguinte comando para confirmar que os serviços necessários estão ativados:

gcloud services list

Se não vir os serviços necessários listados, ative-os:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Ative também o serviço Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar o ENDPOINTS_SERVICE_NAME, pode:

  • Após implementar a configuração do Endpoints, aceda à página Endpoints na Cloud Console. A lista de ENDPOINTS_SERVICE_NAME possíveis é apresentada na coluna Nome do serviço.

  • Para a OpenAPI, o ENDPOINTS_SERVICE_NAME é o que especificou no campo host da sua especificação OpenAPI. Para o gRPC, o ENDPOINTS_SERVICE_NAME é o que especificou no campo name da sua configuração de pontos finais gRPC.

Para mais informações sobre os comandos gcloud, consulte os serviços gcloud.

Implementar o back-end da API

Crie um modelo de instância

Crie um modelo que vai usar para criar um grupo de instâncias de VM. Cada instância criada a partir do modelo inicia um ESPv2 e um servidor de aplicações de back-end.

  1. Na Google Cloud consola, aceda à página Modelos de instâncias.

    Aceda a Modelos de instâncias

  2. Clique em Criar modelo de instância.

  3. Em Nome, introduza load-balancing-espv2-template.

  4. Em Configuração da máquina, defina o Tipo de máquina como e2-micro.

  5. Em Disco de arranque, defina a Imagem como Container Optimized OS stable version.

  6. Em Firewall, selecione Permitir tráfego HTTP.

  7. Clique em Gestão, segurança, discos, trabalhar em rede, arrendamento único para revelar as definições avançadas.

  8. Clique no separador Gestão. Em Automatização, introduza o seguinte Script de arranque. Lembre-se de atualizar o 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

    O script obtém, instala e inicia o servidor de aplicações de eco e o servidor proxy ESPv2 no arranque da instância.

  9. Clique em Criar.

Aguarde até que o modelo seja criado antes de continuar.

Crie um grupo de instâncias gerido regional

Para executar a aplicação, use o modelo de instância para criar um grupo de instâncias gerido regional:

  1. Na Google Cloud consola, aceda à página Grupos de instâncias.

    Aceda a Grupos de instâncias

  2. Clique em Criar grupo de instâncias.

  3. Em Nome, introduza load-balancing-espv2-group.

  4. Em Localização, selecione Várias zonas.

  5. Em Região, selecione us-central1.

  6. Clique no menu pendente Configurar zonas para revelar Zonas. Selecione as seguintes zonas:

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

  7. Em Modelo de instância, selecione load-balancing-espv2-template.

  8. Em Ajuste de escala automático, selecione Não ajustar a escala automaticamente.

  9. Defina o Número de instâncias como 3.

  10. Em Redistribuição de instâncias, selecione Ativada.

  11. Em Reparação automática e Verificação de estado, selecione Sem verificação de estado.

  12. Clique em Criar. Esta ação redireciona novamente para a página Grupos de instâncias.

Crie um balanceador de carga

Esta secção explica os passos necessários para criar um balanceador de carga global que direcione o tráfego HTTP para o seu grupo de instâncias.

Este equilibrador de carga usa um front-end para receber tráfego de entrada e um back-end para distribuir este tráfego a instâncias em bom estado. Uma vez que o equilibrador de carga é composto por vários componentes, esta tarefa está dividida em várias partes:

  • Configuração do back-end
  • Configuração da interface
  • Reveja e finalize

Conclua todos os passos para criar o balanceador de carga.

  1. Na Google Cloud consola, aceda à página Criar um balanceador de carga.

    Aceda a Crie um balanceador de carga

  2. Na secção Balanceador de carga de aplicações (HTTP/S), clique em Iniciar configuração.

  3. Em Acessível pela Internet ou apenas interno, selecione Da Internet para as minhas VMs. Em seguida, clique em Continuar.

  4. Para o Nome do balanceador de carga, introduza espv2-load-balancer.

Configuração do back-end

  1. No painel do lado esquerdo da página Criar Application Load Balancer externo global, clique em Configuração do back-end.
  2. Clique em Criar ou selecionar serviços de back-end e contentores de back-end para abrir um menu pendente. Clique em Serviços de back-end e, de seguida, em Criar um serviço de back-end.
  3. Na nova janela, para o Nome da aplicação de back-end, introduza espv2-backend.
  4. Defina Grupo de instâncias como load-balancing-espv2-group.
  5. Defina Transferir números como 80. Isto permite o tráfego HTTP entre o balanceador de carga e o grupo de instâncias.
  6. Em Modo de equilíbrio, selecione Utilização.
  7. Clique em Concluído para criar o back-end.

  8. Crie a verificação de funcionamento para o back-end do balanceador de carga:

    1. Em Verificação de funcionamento, selecione Criar uma verificação de funcionamento (ou Criar outra verificação de funcionamento) no menu pendente. É aberta uma nova janela.
    2. Na nova janela, em Nome, introduza espv2-load-balancer-check.
    3. Defina o Protocolo como HTTP.
    4. Em Porta, introduza 80.
    5. Para este tutorial, defina o Caminho do pedido como /healthz, que é um caminho que o ESPv2 está configurado para responder.

    6. Defina os seguintes critérios de estado:

      1. Defina o Intervalo de verificação para 3 segundos. Isto define a quantidade de tempo desde o início de uma sondagem até ao início da seguinte.
      2. Defina o Limite de tempo para 3 segundos. Isto define o tempo que Google Cloud aguarda uma resposta a uma sondagem. O valor tem de ser inferior ou igual ao intervalo de verificação.
      3. Defina o Limite saudável para 2 sucessos consecutivos. Isto define o número de sondagens sequenciais que têm de ser bem-sucedidas para que a instância seja considerada em bom estado.
      4. Defina o limite não saudável para 2 falhas consecutivas. Este parâmetro define o número de sondagens sequenciais que têm de falhar para que a instância seja considerada não saudável.

    7. Clique em Guardar e continuar para criar a verificação de estado.

  9. Clique em Criar para criar o serviço de back-end.

Configuração da interface

  1. No painel do lado esquerdo da página Criar Application Load Balancer externo global, clique em Configuração do front-end.
  2. Na página Configuração do frontend, em Nome, introduza espv2-ipv4-frontend.
  3. Defina o Protocolo como HTTP.
  4. Defina a Porta para 80.
  5. Clique em Concluído para criar o frontend.

Reveja e finalize

  1. Valide as definições de equilíbrio de carga antes de criar o equilibrador de carga:

    1. No painel do lado esquerdo da página Criar Application Load Balancer externo global, clique em Rever e finalizar.

    2. Na página Reveja e finalize, verifique as seguintes definições de back-end:

      • O serviço de back-end está espv2-backend.
      • O protocolo do ponto final é HTTP.
      • A verificação de funcionamento está espv2-load-balancer-check.
      • O grupo de instâncias está load-balancing-espv2-group.

    3. Na mesma página, verifique se o Frontend usa um endereço IP com um Protocolo de HTTP.

  2. No painel esquerdo da página Criar Application Load Balancer externo global, clique em Criar para concluir a criação do balanceador de carga.

    Pode ter de aguardar alguns minutos para que a criação do equilibrador de carga termine.

  3. Depois de criar o balanceador de carga, encontre o endereço IP na página Balanceador de carga.

    Aceder ao balanceador de carga

Enviar um pedido através de um endereço IP

Depois de a API de exemplo e o ESPv2 estarem em execução no back-end implementado, pode enviar pedidos para a API a partir da sua máquina local.

Crie uma chave da API e defina uma variável de ambiente

O código de exemplo requer uma chave da API. Para simplificar o pedido, defina uma variável de ambiente para a chave da API.

  1. No mesmo Google Cloud projeto que usou para a sua API, crie uma chave da API na página de credenciais da API. Se quiser criar uma chave da API num Google Cloud projeto diferente, consulte o artigo Ativar uma API no seu Google Cloud projeto.

    Aceda à página Credenciais

  2. Clique em Criar credenciais e, de seguida, selecione Chave de API.
  3. Copie a chave para a área de transferência.
  4. Clique em Fechar.
  5. No computador local, cole a chave da API para a atribuir a uma variável de ambiente:
    • No Linux ou macOS: export ENDPOINTS_KEY=AIza...
    • No Windows PowerShell: $Env:ENDPOINTS_KEY="AIza..."

Envie o pedido

Linux ou Mac OS

Use curl para enviar um pedido HTTP através da variável de ambiente ENDPOINTS_KEY que definiu anteriormente. Substitua IP_ADDRESS pelo endereço IP externo da sua instância.

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

Nos curl anteriores:

  • A opção --data especifica os dados a publicar na API.
  • A opção --header especifica que os dados estão no formato JSON.

PowerShell

Use Invoke-WebRequest para enviar um pedido HTTP através da variável de ambiente ENDPOINTS_KEY que definiu anteriormente. Substitua IP_ADDRESS pelo endereço IP externo da sua instância.

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content

No exemplo anterior, as duas primeiras linhas terminam com um acento grave. Quando colar o exemplo no PowerShell, certifique-se de que não existe um espaço após os acentos graves. Para obter informações sobre as opções usadas no pedido de exemplo, consulte Invoke-WebRequest na documentação da Microsoft.

App de terceiros

Pode usar uma aplicação de terceiros, como a extensão do navegador Chrome Postman, para enviar o pedido:

  • Selecione POST como verbo HTTP.
  • Para o cabeçalho, selecione a chave content-type e o valor application/json.
  • Para o corpo, introduza o seguinte:
    {"message":"hello world"}
  • No URL, use a chave da API real em vez da variável de ambiente. Por exemplo:
    http://192.0.2.0:80/echo?key=AIza...

A API devolve a mensagem que envia e responde com o seguinte:

{
  "message": "hello world"
}

Se não recebeu uma resposta bem-sucedida, consulte o artigo Resolução de problemas de erros de resposta.

Acabou de implementar e testar uma API no Endpoints!

Configurar o DNS para pontos finais

Uma vez que o nome do serviço Endpoints para a API está no domínio .endpoints.YOUR_PROJECT_ID.cloud.goog, pode usá-lo como o nome de domínio totalmente qualificado (FQDN) fazendo uma pequena alteração de configuração no ficheiro openapi.yaml. Desta forma, pode enviar pedidos para a API de exemplo através de echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog em vez do endereço IP.

Para configurar o DNS dos Endpoints:

OpenAPI 2.0

  1. Abra o ficheiro de configuração da OpenAPI, openapi.yaml, e adicione a propriedade x-google-endpoints no nível superior do ficheiro (sem recuo nem aninhamento), conforme mostrado no seguinte fragmento: 
    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. Na propriedade name, substitua YOUR_PROJECT_ID pelo ID do seu projeto.
  3. Na propriedade target, substitua IP_ADDRESS pelo endereço IP que usou quando enviou um pedido para a API de exemplo.
  4. Implemente o ficheiro de configuração OpenAPI atualizado na gestão de serviços: 
    gcloud endpoints services deploy openapi.yaml

OpenAPI 3.x

  1. Abra o ficheiro de configuração da OpenAPI, openapi.yaml, e adicione a propriedade servers.url no nível superior do ficheiro (sem recuo nem aninhamento), conforme mostrado no seguinte fragmento: 
    servers:
  - url: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
    x-google-endpoint:
      target: "IP_ADDRESS"
  2. Na propriedade name, substitua YOUR_PROJECT_ID pelo ID do seu projeto.
  3. Na propriedade target, substitua IP_ADDRESS pelo endereço IP que usou quando enviou um pedido para a API de exemplo.
  4. Implemente o ficheiro de configuração OpenAPI atualizado na gestão de serviços: 
    gcloud endpoints services deploy openapi.yaml

Por exemplo, suponha que o ficheiro openapi.yaml tem a seguinte configuração:

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 implementa o ficheiro openapi.yaml através do comando gcloud anterior, a gestão de serviços cria um registo A de DNS, echo-api.endpoints.my-project-id.cloud.goog, que é resolvido para o endereço IP de destino, 192.0.2.1. A propagação da nova configuração de DNS pode demorar alguns minutos.

Configurar SSL

Para mais detalhes sobre como configurar o DNS e o SSL, consulte o artigo Ativar SSL para pontos finais.

Enviar um pedido através do FQDN

Agora que tem o registo DNS configurado para a API de exemplo, envie-lhe um pedido usando o FQDN (substitua YOUR_PROJECT_ID pelo ID do seu projeto) e a variável de ambiente ENDPOINTS_KEY definida anteriormente:

  • No Linux ou no 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}"
  • No 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

Acompanhamento da atividade da API

Para acompanhar a atividade da API:

  1. Consulte os gráficos de atividade da sua API na página Endpoints > Serviços.

    Aceda à página Serviços de pontos finais


    Pode demorar alguns momentos até que o pedido se reflita nos gráficos.
  2. Consulte os registos de pedidos da sua API na página do explorador de registos.

    Aceda à página do Explorador de registos

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

  1. Certifique-se de que a CLI gcloud (gcloud) está autorizada a aceder aos seus dados e serviços em Google Cloud:

    gcloud auth login

  2. Introduza o seguinte para apresentar os IDs dos seus Google Cloud projetos:

    gcloud projects list

  3. Usando o ID do projeto aplicável do passo anterior, defina o projeto predefinido Google Cloud para aquele em que a sua aplicação se encontra:

    gcloud config set project [YOUR_PROJECT_ID]

  4. Obtenha o nome de todos os serviços geridos no seu Google Cloud projeto:

    gcloud endpoints services list

  5. Elimine o serviço na gestão de serviços. Substitua SERVICE_NAME pelo nome do serviço que quer remover.

    gcloud endpoints services delete SERVICE_NAME

    A execução de gcloud endpoints services delete não elimina imediatamente o serviço gerido. A gestão de serviços desativa o serviço gerido durante 30 dias, o que lhe dá tempo para o restaurar, se precisar. Após 30 dias, a gestão de serviços elimina permanentemente o serviço gerido.

  6. Aceda à página Load Balancer.

    Aceder ao balanceador de carga

    Elimine o balanceador de carga espv2-load-balancer com o serviço de back-end espv2-backend e a verificação de funcionamento espv2-load-balancer-check.

  7. Aceda à página Grupos de instâncias.

    Aceda a Grupos de instâncias

    Eliminar load-balancing-espv2-group

  8. Aceda à página Modelo de instância.

    Aceda a Modelos de instâncias

    Eliminar load-balancing-espv2-template.

O que se segue?