Primeiros passos com o Cloud Endpoints para grupo gerenciado de instâncias (MIGs, na sigla em inglês) com o ESPv2

---

OpenAPI | gRPC

Neste tutorial, mostramos como configurar e implantar uma API de amostra e o Extensible Service Proxy V2 (ESPv2) em contêineres pré-criados do Docker (em inglês) no Grupo gerenciado de instâncias (MIGs) .

A API REST do código de amostra é descrita com a especificação OpenAPI. Além disso, você também aprenderá a criar uma chave de API e a usá-la em solicitações à API.

Para uma visão geral do Cloud Endpoints, consulte Sobre o Endpoints e Arquitetura do Endpoints.

Objetivos

Ao seguir o tutorial, use a lista detalhada de tarefas abaixo. Em todas elas, é necessário que as solicitações para a API sejam enviadas com sucesso.

1. Configure um projeto do Google Cloud. Consulte Antes de começar.
2. Faça o download do código de amostra. Consulte Como conseguir o código de amostra.
3. Configurar o arquivo openapi.yaml, usado para configurar o Endpoints. Consulte Como configurar o Endpoints.
4. Implante a configuração do Endpoints para criar um serviço dele. Consulte Como implantar a configuração do Endpoints.
5. Implante a API e o ESPv2 no back-end do grupo gerenciado de instâncias (MIGs, na sigla em inglês). Consulte Como implantar o back-end da API.
6. Envie uma solicitação à API usando um endereço IP. Consulte Como enviar uma solicitação usando um endereço IP.
7. Configurar um registro DNS para a API. Consulte Como configurar o DNS para o Endpoints.
8. Envie uma solicitação à API usando o nome de domínio totalmente qualificado. Consulte Como enviar uma solicitação usando o FQDN.
9. Rastreie a atividade da API. Consulte Como rastrear a atividade da API.
10. Evite cobranças na sua conta do Google Cloud. Consulte Fazer limpeza.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

• Compute Engine
• Endpoints

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.

Antes de começar

1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

2. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

4. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

5. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

6. Anote o código do projeto, ele será necessário mais tarde.

7. Você precisará que um aplicativo envie solicitações à API de amostra.

   • Usuários de Linux e macOS: este tutorial fornece um exemplo de uso de curl, que normalmente vem pré-instalado em seu sistema operacional. Caso não tenha curl, faça o download na página Versões e downloads (em inglês) do curl.
   • Usuários do Windows: neste tutorial, há um exemplo que usa Invoke-WebRequest (em inglês), que é compatível com o PowerShell 3.0 e versões posteriores.
8. Faça o download da Google Cloud CLI.
9. Atualize a CLI gcloud e instale os componentes do Endpoints.

   gcloud components update

10. Verifique se a Google Cloud CLI (gcloud) está autorizada a acessar seus dados e serviços no Google Cloud:

    gcloud auth login

    Na nova guia aberta no navegador, selecione uma conta.
11. Defina o projeto padrão como o ID do projeto.

    gcloud config set project YOUR_PROJECT_ID

    Substitua YOUR_PROJECT_ID pela ID do seu projeto. Se você tiver outros projetos do Google Cloud e quiser usar gcloud para gerenciá-los, consulte Como gerenciar configurações da CLI gcloud.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.

Como fazer o download do código de amostra

Faça o download do código de amostra para a máquina local.

Java

Para clonar ou fazer o download da API de amostra:

1. Clone o repositório do aplicativo de amostra na máquina local:

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples

   Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

2. Acesse o diretório que contém o exemplo de código:

   cd java-docs-samples/endpoints/getting-started

Python

Para clonar ou fazer o download da API de amostra:

1. Clone o repositório do aplicativo de amostra na máquina local:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples

   Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

2. Acesse o diretório que contém o exemplo de código:

   cd python-docs-samples/endpoints/getting-started

Go

Para clonar ou fazer o download da API de amostra:

1. Verifique se a variável de ambiente GOPATH (em inglês) está configurada.
2. Clone o repositório do aplicativo de amostra na máquina local:

   go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started

3. Acesse o diretório que contém o exemplo de código:

   cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started

PHP

Para clonar ou fazer o download da API de amostra:

1. Clone o repositório do aplicativo de amostra na máquina local:

   git clone https://github.com/GoogleCloudPlatform/php-docs-samples

   Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

2. Acesse o diretório que contém o exemplo de código:

   cd php-docs-samples/endpoints/getting-started

Ruby

Para clonar ou fazer o download da API de amostra:

1. Clone o repositório do aplicativo de amostra na máquina local:

   git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

   Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

2. Acesse o diretório que contém o exemplo de código:

   cd ruby-docs-samples/endpoints/getting-started

NodeJS

Para clonar ou fazer o download da API de amostra:

1. Clone o repositório do aplicativo de amostra na máquina local:

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

   Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

2. Acesse o diretório que contém o código de amostra:

   cd nodejs-docs-samples/endpoints/getting-started

Como configurar o Endpoints

O código de exemplo inclui o arquivo de configuração OpenAPI, openapi.yaml, que é baseado na especificação OpenAPI v2.0. Configure e implante openapi.yaml na máquina local. Para configurar o Endpoints:

1. No diretório de código de amostra, abra o arquivo de configuração openapi.yaml.
   Java

   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"

   Python

   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"

   Go

   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"

   PHP

   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"

   Ruby

   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"

   NodeJS

   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"

   Observações:

   • A amostra de configuração exibe as linhas próximas ao campo host, que precisa ser modificado. Para implantar o arquivo openapi.yaml no Endpoints, é necessário o documento completo da OpenAPI.
   • O arquivo de exemplo openapi.yaml contém uma seção para configurar a autenticação que não é necessária para este tutorial. Não é necessário configurar as linhas com YOUR-SERVICE-ACCOUNT-EMAIL e YOUR-CLIENT-ID.
   • A OpenAPI é uma especificação agnóstica de linguagem. Por conveniência, o mesmo arquivo openapi.yaml está na amostra getting-started no repositório do GitHub de cada linguagem.

2. No campo host, substitua o texto pelo nome do serviço do Endpoints, que precisa estar no seguinte formato:

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

   Substitua o YOUR_PROJECT_ID pelo ID do projeto do Google Cloud. Exemplo:

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

Observe que echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog é o nome do serviço do Endpoints. e não o nome de domínio totalmente qualificado (FQDN, na sigla em inglês) usado para enviar solicitações à API.

Para mais informações sobre os campos no documento da OpenAPI exigido pelo Endpoints, consulte Como configurar o Endpoints. Depois de concluir todas as etapas de configuração a seguir para enviar solicitações à API de amostra usando um endereço IP, consulte Como configurar o DNS do Endpoints para informações sobre como configurar echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog para ser o FQDN.

Como implantar a configuração do Endpoints

Para implantar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Ele utiliza o Service Management para criar um serviço gerenciado.

Para implantar a configuração do Endpoints:

1. Verifique se você está no diretório endpoints/getting-started.
2. Faça upload da configuração e crie um serviço gerenciado:

   gcloud endpoints services deploy openapi.yaml
   

Em seguida, o comando gcloud chama a API Service Management para criar um serviço gerenciado com o nome especificado no campo host do arquivo openapi.yaml. O Service Management configura o serviço de acordo com as configurações no arquivo openapi.yaml. Ao fazer alterações em openapi.yaml, é necessário reimplantar o arquivo para atualizar o serviço do Endpoints.

Durante a criação e a configuração do serviço, a Service Management envia informações ao terminal. Ignore os avisos sobre os caminhos no arquivo openapi.yaml que não exigem uma chave de API. Quando a configuração do serviço é concluída, o Service Management mostra uma mensagem com o código de configuração e o nome do serviço:

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 do Endpoints. O código de configuração do serviço consiste em um carimbo de data e um número de revisão. Se você implantar o arquivo openapi.yaml novamente no mesmo dia, o número de revisão será incrementado no ID de configuração do serviço. É possível visualizar a configuração do serviço do Endpoints na página Endpoints > Serviços no console do Google Cloud.

Se você receber uma mensagem de erro, consulte Como solucionar problemas de implantação na configuração do Endpoints.

Como verificar os serviços obrigatórios

O Endpoints e o ESP exigem que estes serviços do Google estejam ativados:

Nome	Título
servicemanagement.googleapis.com	API Service Management
servicecontrol.googleapis.com	API Service Control
endpoints.googleapis.com	Google Cloud Endpoints

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

• Você usou um aplicativo de terceiros, como o Terraform, e não incluiu esses serviços.

• Você implantou a configuração do Endpoints em um projeto do Google Cloud existente, em que esses serviços foram desativados explicitamente.

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

gcloud services list

Se você não encontrar os serviços necessários listados, ative-os:

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

Ative também seu serviço do Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar o ENDPOINTS_SERVICE_NAME, é possível:

• Depois de implantar a configuração do Endpoints, acesse a página Endpoints no console do Cloud. A lista de ENDPOINTS_SERVICE_NAME possíveis é mostrada na coluna Nome do serviço.

• Para a OpenAPI, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo host da especificação do OpenAPI. Para gRPC, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo name da configuração do gRPC Endpoints.

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

Como implantar o back-end da API

Criar um modelo de instância

Crie um modelo que você usará para criar um grupo de instâncias da VM. Cada instância criada a partir do modelo inicia um ESPv2 e um servidor de aplicativos de back-end.

1. No Console do Google Cloud, acesse a página Modelos de instância.

   Acesse "Modelos de instância"

2. Clique em Criar modelo de instância.

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

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

5. Em Disco de inicialização, defina a Imagem como Container Optimized OS stable version.

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

7. Clique em Gerenciamento, segurança, discos, rede, locatário único para ver configurações avançadas.

8. Clique na guia Gerenciamento. Em Automação, insira o script de inicialização a seguir. Lembre-se de atualizar 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 recebe, instala e inicia o servidor de aplicativos de eco e o servidor proxy ESPv2 na inicialização da instância.

9. Clique em Criar.

Aguarde o modelo ser criado para continuar.

Criar um grupo de instâncias gerenciadas regional

Para executar o aplicativo, use o modelo de instância para criar um grupo gerenciado de instâncias regional:

1. No Console do Google Cloud, acesse a página Grupos de instâncias.

   Acesse grupo de instâncias

2. Clique em Criar grupo de instâncias.

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

4. Em Local, selecione Várias zonas.

   Dica profissional: para garantir que seu aplicativo esteja disponível durante eventos extremos, como interrupções de zona, o Compute Engine recomenda que você distribua o aplicativo em várias zonas.

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

6. Clique no menu suspenso Configurar zonas para exibir 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 Escalonamento automático, selecione Não fazer escalonamento automático.

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

   Dica profissional: ao criar um grupo regional de instâncias gerenciadas com o Compute Engine, é recomendável provisionar instâncias suficientes. Assim, caso todas elas em qualquer zona estejam indisponíveis, as instâncias restantes ainda serão o mínimo necessário. No entanto, provisionar mais instâncias do que você precisa pode resultar em custos adicionais. Para mais informações, consulte Como selecionar o tamanho do grupo de instâncias para garantir a disponibilidade.

10. Em Redistribuição da instância, selecione Ativado.

11. Em Recuperação automática e Verificação de integridade, selecione Nenhuma verificação de integridade.

12. Clique em Criar. Isso redireciona você de volta à página Grupos de instâncias.

    Observação: aguarde alguns minutos até que todas as instâncias do grupo estejam em execução e prontas para exibir o aplicativo da Web.

Criar um balanceador de carga

Nesta seção, explicamos as etapas necessárias para criar um balanceador de carga global que direciona o tráfego HTTP para seu grupo de instâncias.

Esse balanceador de carga usa um front-end para receber tráfego de entrada e um back-end para distribuir esse tráfego para instâncias íntegras. Como o balanceador de carga é composto por vários componentes, essa tarefa é dividida em várias partes.

• Configuração de back-end
• Configuração de front-end
• Analisar e finalizar

Conclua todas as etapas para criar o balanceador de carga.

1. No console do Google Cloud, acesse a página Criar balanceador de carga.

   Acessar "Criar um balanceador de carga"

2. Na seção Balanceador de carga de aplicativo (HTTP/S), clique em Iniciar configuração.

3. Em Somente voltado para a Internet ou interno, selecione Da Internet para minhas VMs. Em seguida, clique em Continuar.

4. Em Nome do balanceador de carga, digite espv2-load-balancer.

Configuração de back-end

1. No painel esquerdo da página Criar balanceador de carga de aplicativo externo global, clique em Configuração de back-end.
2. Clique em Criar ou selecione serviços e buckets de back-end para abrir um menu suspenso. Clique em Serviços de back-end e em Criar um serviço de back-end.
3. Na nova janela, para o Nome do aplicativo de back-end, insira espv2-backend.
4. Defina Grupo de instâncias como load-balancing-espv2-group.
5. Defina Números de portas como 80. Isso permite o tráfego HTTP entre o balanceador de carga e o grupo de instâncias.
6. Em Modo de balanceamento, selecione Utilização.
7. Clique em Concluído para criar o back-end.

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

   Dica profissional: as verificações de integridade são usadas para balanceamento de carga e autohealing, mas para diferentes propósitos:

   • As verificações de integridade para balanceamento de carga são usadas para detectar instâncias sem resposta e direcionar o tráfego para longe delas.
   • As verificações de integridade para recuperação automática são usadas para detectar e recriar instâncias com falha.

   Use verificações de integridade separadas para balanceamento de carga e recuperação automática. Usar a mesma verificação de integridade para esses serviços removeria a distinção entre instâncias sem resposta e com falha, o que causaria latência e falta de disponibilidade desnecessárias para seus usuários. Para mais informações, consulte Conceitos de verificação de integridade.

   1. Em Verificação de integridade, selecione Criar uma verificação de integridade (ou Criar outra verificação de integridade) no menu suspenso. Uma nova janela será aberta.
   2. Na nova janela, em Nome, digite espv2-load-balancer-check.
   3. Defina Protocolo como HTTP.
   4. Em Porta, digite 80.
   5. Para este tutorial, defina o Caminho da solicitação como /healthz, que é o caminho de resposta configurado para o ESPv2.

   6. Defina os seguintes Critérios de integridade:

      1. Defina Intervalo de verificação como 3 segundos. Isso define o período entre o início de uma sondagem e o início da próxima.
      2. Defina Tempo limite como 3 segundos. Isso define o tempo que o Google Cloud aguardará pela resposta de uma sondagem. O valor precisa ser menor ou igual ao intervalo de verificação.
      3. Defina Limite íntegro como 2 sucessos consecutivos. Isso define o número sequencial de sondagens que precisam ser bem-sucedidas para que a instância seja considerada íntegra.
      4. Defina Limite não íntegro como 2 falhas consecutivas. Isso define o número de falhas seguidas em sondagens para que a instância seja considerada não íntegra.

      Dica profissional: para mais informações sobre como refinar os valores de Intervalo de verificação e Tempo limite para seu próprio aplicativo, consulte Como as verificações de integridade funcionam Para refinar os valores de Limite íntegro e Limite não íntegro para seu próprio aplicativo, use os seguintes critérios:

      • Se o tráfego estiver sendo direcionado para instâncias com alta latência, mesmo quando instâncias mais rápidas estiverem disponíveis, diminua o limite de tráfego tornando sua verificação de integridade mais agressiva.
      • Se o tráfego estiver sendo direcionado para longe de instâncias com baixa latência, aumente o limite para o tráfego tornando sua verificação de integridade mais conservadora.

      Para ver informações detalhadas sobre como otimizar e medir a latência, consulte Como otimizar a latência do aplicativo com balanceamento de carga.

   7. Clique em Salvar e continuar para criar a verificação de integridade.

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

Configuração de front-end

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

Analisar e finalizar

1. Verifique suas configurações de balanceamento de carga antes de criar o balanceador de carga:

   1. No painel esquerdo da página Criar balanceador de carga de aplicativo externo global, clique em Analisar e finalizar.

   2. Na página Analisar e finalizar, verifique as seguintes configurações de back-end:

      • O Serviço de back-end é espv2-backend.
      • O Protocolo do endpoint é HTTP.
      • A Verificação de integridade é espv2-load-balancer-check.
      • O Grupo de instâncias é load-balancing-espv2-group.

   3. Na mesma página, verifique se o Front-end usa um endereço IP com um Protocolo HTTP.

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

   Pode ser necessário aguardar alguns minutos para que a criação do balanceador de carga seja concluída.

3. Depois que o balanceador de carga for criado, localize o endereço IP na página Balanceador de carga.

   Acessar "Balanceador de carga"

Como enviar uma solicitação usando um endereço IP

Depois que a API de amostra e o ESPv2 estiverem em execução no back-end, será possível enviar solicitações para a API da máquina local.

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

O código de amostra requer uma chave de API. Para simplificar a solicitação, defina uma variável de ambiente para a chave da API.

1. No mesmo projeto do Google Cloud usado para a API, crie uma chave de API na página de credenciais da API. Se você quer criar uma chave de API em um projeto diferente do Google Cloud, consulte Como ativar uma API no projeto do Google Cloud.

   Acessar a página Credenciais

2. Clique em Criar credenciais e, em 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 atribuí-la a uma variável de ambiente:
   • No Linux ou no macOS: export ENDPOINTS_KEY=AIza...
   • No Windows PowerShell: $Env:ENDPOINTS_KEY="AIza..."

Enviar a solicitação

Linux ou mac OS

Utilize curl para enviar uma solicitação HTTP usando a variável de ambiente ENDPOINTS_KEY definida anteriormente. Substitua IP_ADDRESS pelo endereço IP externo da instância.

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

No curl anterior:

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

PowerShell

Utilize Invoke-WebRequest para enviar uma solicitação HTTP usando a variável de ambiente ENDPOINTS_KEY definida anteriormente. Substitua IP_ADDRESS pelo endereço IP externo da 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 acima, as duas primeiras linhas terminam em um acento grave. Quando você colar o exemplo no PowerShell, verifique se não há espaço após os acentos graves. Para informações sobre as opções usadas na solicitação de exemplo, consulte Invoke-WebRequest (em inglês) na documentação da Microsoft.

Aplicativo de terceiros

É possível usar um aplicativo terceirizado para enviar a solicitação, como o Postman (em inglês), uma extensão do navegador Chrome:

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

A mensagem enviada é retornada pela API com a seguinte resposta:

{
  "message": "hello world"
}

Se não receber uma resposta bem-sucedida, consulte Como solucionar problemas em erros de resposta.

Você acaba de implantar e testar uma API no Endpoints.

Observação: se quiser nos contar do que você gostou neste tutorial, envie um feedback na parte inferior desta página. Isso é muito importante para a melhoria dos tutoriais.
Se ocorrer um erro, entre no grupo do Google google-cloud-endpoints e informe o que aconteceu. Nesse grupo, são enviadas respostas de outros usuários do Endpoints e de engenheiros do Google, que o monitoram.

Como configurar o DNS para o Endpoints

Como o nome do serviço do Endpoints para a API está no domínio .endpoints.YOUR_PROJECT_ID.cloud.goog, é possível usá-lo como o nome de domínio totalmente qualificado (FQDN, na sigla em inglês). Basta fazer uma pequena alteração na configuração do arquivo openapi.yaml. Dessa forma, é possível enviar solicitações para a API de amostra usando echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog em vez do endereço IP.

Para configurar o DNS para o Endpoints:

1. Abra o arquivo de configuração da OpenAPI, openapi.yaml, e adicione a propriedade x-google-endpoints no nível superior do arquivo (sem recuo ou aninhamento), conforme mostrado no snippet a seguir:

   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 projeto.
3. Na propriedade target, substitua IP_ADDRESS pelo endereço IP usado ao enviar uma solicitação para a API de amostra.
4. Implante o arquivo de configuração da OpenAPI atualizado na Service Management usando o seguinte comando:

   gcloud endpoints services deploy openapi.yaml
   

Por exemplo, suponha que o arquivo openapi.yaml tenha estas configurações:

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"

Ao implantar o arquivo openapi.yaml usando o comando gcloud anterior, o Service Management cria um registro A DNS, echo-api.endpoints.my-project-id.cloud.goog, que é resolvido para o endereço IP de destino, 192.0.2.1. Pode levar alguns minutos para a nova configuração do DNS se propagar.

Como configurar a SSL

Para mais detalhes sobre como configurar o DNS e a SSL, consulte Como ativar a SSL para o Endpoints.

Como enviar uma solicitação usando o FQDN

Agora que você tem o registro DNS configurado para a API de amostra, envie uma solicitação usando o FQDN (substitua YOUR_PROJECT_ID pelo ID do 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

Como rastrear atividade da API

Para rastrear a atividade da API:

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

   Ir para a página Serviços do Endpoints

   
   Pode levar alguns instantes para a solicitação aparecer nos gráficos.
2. Verifique os registros de solicitações da API na página "Explorador de registros".
   

   Acessar a página Explorador de registros

Como criar um portal do desenvolvedor para a API

É possível usar o portal do Cloud Endpoints para criar um portal do desenvolvedor, um site para interagir com a API de exemplo. Para saber mais, consulte a Visão geral do Portal do Cloud Endpoints.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

1. Verifique se a CLI gcloud (gcloud) está autorizada a acessar seus dados e serviços no Google Cloud:

   gcloud auth login
   

2. Insira o comando abaixo para exibir os IDs dos seus projetos do Google Cloud:

   gcloud projects list
   

3. Usando o ID do projeto aplicável da etapa anterior, defina o projeto padrão do Google Cloud como aquele em que seu aplicativo se encontra:

   gcloud config set project [YOUR_PROJECT_ID]
   

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

   gcloud endpoints services list
   

5. Exclua o serviço do Service Management: Substitua SERVICE_NAME pelo nome do serviço que você quer remover.

   gcloud endpoints services delete SERVICE_NAME
   

   A execução de gcloud endpoints services delete não exclui imediatamente o serviço gerenciado. O Service Management desativa o serviço gerenciado por 30 dias, o que permite que você tenha tempo para restaurá-lo, se necessário. Após 30 dias, o Service Management exclui permanentemente o serviço gerenciado.

6. Acesse a página Balanceador de carga.

   Acessar "Balanceador de carga"

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

7. Acesse a página "Grupos de instâncias".

   Acesse Grupos de instâncias

   Excluir load-balancing-espv2-group

8. Acesse a página Modelo de instância.

   Acesse "Modelos de instância"

   Excluir load-balancing-espv2-template.

A seguir

• Compartilhe a API com outro desenvolvedor
• Saiba mais sobre a autenticação
• Conheça as opções de suporte da comunidade