Começar a usar o Cloud Endpoints para o Compute Engine com o ESP

OpenAPI   |  gRPC

Este tutorial mostra como configurar e implementar uma API de exemplo e o Extensible Service Proxy (ESP) em execução em contentores Docker pré-criados no Compute Engine. 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.

Criar uma instância do Compute Engine

Para criar uma instância do Compute Engine:

1. In the Google Cloud console, go to the Create an instance page.

   Go to Create an instance

2. Na secção Firewall, selecione Permitir tráfego HTTP e permitir tráfego HTTPS.
3. Para criar a VM, clique em Criar.



Aguarde algum tempo para que a instância seja iniciada. Quando estiver pronta, é apresentada na página Instâncias de VM com um ícone de estado verde.

4. Certifique-se de que consegue estabelecer ligação à instância de VM.
   1. In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.
   2. Agora, pode usar o terminal para executar comandos do Linux na sua instância do Debian.
   3. Introduza exit para desassociar da instância.
5. Tome nota do nome da instância, da zona e do endereço IP externo, uma vez que são necessários mais tarde.

Transferir o exemplo de código

Transfira o exemplo de código para a sua máquina 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 GOPATHvariável de ambiente 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

O exemplo de código inclui o ficheiro de configuração da OpenAPI, openapi.yaml, que se baseia na especificação da OpenAPI v2.0. Configura e implementa o openapi.yaml na sua máquina local.

Para configurar pontos finais:

1. No diretório de código de exemplo, abra o ficheiro 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"

   Ir

   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"

   Tenha em conta o seguinte:

   • O exemplo de configuração apresenta as linhas junto ao campo host que tem de modificar. Para implementar o ficheiro openapi.yaml nos Endpoints, é necessário o documento OpenAPI completo.
   • O ficheiro de exemplo openapi.yaml contém uma secção para configurar a autenticação que não é necessária para este tutorial. Não precisa de configurar as linhas com YOUR-SERVICE-ACCOUNT-EMAIL e YOUR-CLIENT-ID.
   • A OpenAPI é uma especificação independente do idioma. O mesmo ficheiro openapi.yaml encontra-se no exemplo getting-started em cada repositório do GitHub para sua conveniência.

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

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

   Substitua YOUR_PROJECT_ID pelo ID do seu Google Cloud projeto. Por exemplo:

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

Tenha em atenção que echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog é o nome do serviço Endpoints. Não é o nome do domínio totalmente qualificado (FQDN) que usa para enviar pedidos à API.

Para obter informações sobre os campos no documento OpenAPI que o Endpoints requer, consulte o artigo Configurar o Endpoints.

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 FQDN.

Implementar a 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 endpoints/getting-started.
2. Carregue a configuração e crie um serviço gerido:

   gcloud endpoints services deploy openapi.yaml
   

Em seguida, o comando gcloud chama a API Service Management para criar um serviço gerido com o nome que especificou no campo host 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 ao 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

Até agora, implementou o documento OpenAPI na gestão de serviços, mas ainda não implementou o código que publica o back-end da API. Esta secção explica como configurar o Docker na instância da VM e executar o código de back-end da API e o ESP num contentor Docker.

A verificar as autorizações necessárias

Nota:

Este passo não é necessário se a instância do Compute Engine for criada com a conta de serviço predefinida do Compute Engine e lhe tiverem sido concedidas todas as autorizações necessárias.

• Na Google Cloud consola, aceda à página de instâncias do Compute Engine.

  Aceda à página do Compute Engine

• Selecione a sua instância na lista.
• Pode ver a conta de serviço associada e as autorizações que tem.

• Conceda as autorizações necessárias à conta de serviço:

  gcloud projects add-iam-policy-binding PROJECT_ID 
  
  --member "serviceAccount:SERVICE_ACCOUNT" 
  
  --role roles/servicemanagement.serviceController

  Para mais informações, consulte o artigo O que são funções e autorizações?

Instale o Docker na instância de VM

Para instalar o Docker na instância de VM:

1. Defina a zona do seu projeto executando o comando:

   gcloud config set compute/zone YOUR_INSTANCE_ZONE
   

   Substitua YOUR_INSTANCE_ZONE pela zona onde a sua instância está a ser executada.

2. Associe-se à sua instância através do seguinte comando:

   gcloud compute ssh INSTANCE_NAME
   

   Substitua INSTANCE_NAME pelo nome da instância de VM.

3. Consulte a documentação do Docker para configurar o repositório do Docker. Certifique-se de que segue os passos que correspondem à versão e à arquitetura da sua instância de VM:
   • Jessie ou mais recente
   • x86_64 / amd64

Execute a API e o ESP num contentor do Docker

O ESP é um proxy baseado no nginx que se encontra à frente do código de back-end. Processa o tráfego recebido para fornecer autenticação, gestão de chaves de API, registo e outras funcionalidades de gestão da API Endpoints.

Para instalar e executar a API de exemplo e o ESP num contentor Docker:

1. Crie a sua própria rede de contentores denominada esp_net.

   sudo docker network create --driver bridge esp_net
   

2. Execute o servidor Echo de exemplo que publica a API de exemplo:
   Java

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-java:1.0
   

   Python

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-python:1.0
   

   Ir

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-go:1.0
   

   PHP

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-php:1.0
   

   Ruby

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-ruby:1.0
   

   NodeJS

   sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-node:1.0
   

3. Execute o contentor Docker de ESP público pré-embalado. Nas opções de arranque do ESP, substitua SERVICE_NAME pelo nome do seu serviço. Este é o mesmo nome que configurou no campo host do seu documento OpenAPI.

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=SERVICE_NAME \
       --rollout_strategy=managed \
       --backend=echo:8080
   

   A opção --rollout_strategy=managed configura o ESP para usar a configuração do serviço implementada mais recente. Quando especifica esta opção, até 5 minutos após implementar uma nova configuração de serviço, o ESP deteta a alteração e começa a usá-la automaticamente. Recomendamos que especifique esta opção em vez de um ID de configuração específico para o ESP usar. Para ver informações sobre as outras opções de ESP usadas acima, consulte as opções de arranque do ESP.

Se receber uma mensagem de erro, consulte o artigo Resolução de problemas de pontos finais no Compute Engine.

Consulte o artigo Implementar o back-end da API para ver informações adicionais.

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

Depois de a API de exemplo e o ESP estarem em execução na instância do Compute Engine, 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!

Nota: se quiser partilhar o que gostou neste tutorial, não hesite em enviar feedback na parte inferior desta página. O seu feedback ajuda-nos a melhorar estes tutoriais.
Se recebeu um erro, junte-se ao google-cloud-endpoints grupo Google e diga-nos o que correu mal. Este grupo recebe respostas de outros utilizadores do Endpoints e de engenheiros da Google, que monitorizam o grupo.

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:

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
   

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

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

Quando 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 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