Primeiros passos com o Cloud Endpoints no ambiente flexível do App Engine (.NET) com o ESP

Como receber o código de exemplo

Para fazer o download da API de amostra, siga estas etapas:

1. Faça o download do código de amostra como um arquivo zip.

2. Extraia o arquivo zip e mude para o diretório dotnet-docs-samples-master\endpoints\getting-started.

3. Abra GettingStarted.sln com o Visual Studio ou use seu editor de preferência para editar os arquivos no diretório endpoints\getting-started\src\IO.Swagger.

Como configurar o Endpoints

O código de amostra inclui o arquivo de configuração da OpenAPI, openapi-appengine.yaml, que é baseado na especificação OpenAPI v2.0 (em inglês).

1. No diretório de código de amostra, abra o arquivo de configuração openapi-appengine.yaml.
   swagger: "2.0"
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   host: "YOUR-PROJECT-ID.appspot.com"
   

   Observe o seguinte:

   • A amostra de configuração exibe as linhas próximas ao campo host, que precisa ser modificado. Para implantar openapi-appengine.yaml no Endpoints, é preciso ter o documento completo da OpenAPI.
   • O exemplo openapi-appengine.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-appengine.yaml está na amostra getting-started no repositório do GitHub de cada linguagem.

2. Na linha com o campo host, substitua YOUR-PROJECT-ID pelo ID do projeto do Google Cloud. Exemplo:

   host: "example-project-12345.appspot.com"

O Endpoints usa o texto configurado no campo host como o nome do serviço. Quando você implanta a API no back-end do App Engine, uma entrada DNS com um nome no formato YOUR-PROJECT-ID.appspot.com é criada automaticamente.

Para informações sobre os campos no documento da OpenAPI exigido pelo Endpoints, consulte Como configurar o Endpoints.

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-appengine.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-appengine.yaml. O Service Management configura o serviço de acordo com as configurações no arquivo openapi-appengine.yaml. Ao fazer alterações em openapi-appengine.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-appengine.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 [example-project-12345.appspot.com]

No exemplo anterior, 2017-02-13r0 é o ID de configuração do serviço e example-project-12345.appspot.com é 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-appengine.yaml novamente no mesmo dia, o número de revisão será incrementado no ID de configuração do serviço. Você pode conferir a configuração do serviço 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

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:

• Após 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.

Implantar o back-end da API

Até agora, você implantou o documento da OpenAPI no Service Management, mas não o código que exibe o back-end da API. Nesta seção, veja como implantar a API de amostra e o ESP no App Engine.

Para implantar o back-end da API:

1. Abra o arquivo endpoints/getting-started/src/IO.Swagger/app.yaml e adicione o nome do serviço:
endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
  # previously run the deploy command, you can list your existing configuration
  # ids using the 'configs list' command as follows:
  # 'gcloud endpoints configs list --service=[PROJECT-ID].appspot.com'
  # where [PROJECT-ID].appspot.com is your Endpoints service name.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

Substitua ENDPOINTS-SERVICE-NAME pelo nome do serviço do Endpoints. Ele é o mesmo que foi configurado no campo host do documento da OpenAPI. Exemplo:

endpoints_api_service:
  name: example-project-12345.appspot.com
  rollout_strategy: managed

A opção rollout_strategy: managed configura o ESP para usar a implantação mais recente da configuração de serviço. Quando você especifica essa opção, até 5 minutos depois de implantar uma nova configuração de serviço, o ESP detecta a alteração e começa a usá-la automaticamente. Recomendamos especificar essa opção em vez de um ID de configuração específico para uso do ESP.

2. Salve o arquivo app.yaml.

Como a seção endpoints_api_service está incluída no arquivo app.yaml, o comando gcloud app deploy implanta e configura o ESP em um contêiner separado para o ambiente flexível do App Engine. Todo o tráfego de solicitação é roteado pelo ESP, que atua como proxy em solicitações e respostas de e para o contêiner que executa o código de servidor do back-end.

3. Verifique se você está no diretório endpoints/getting-started, em que está localizado o arquivo de configuração openapi-appengine.yaml.
4. Implante a API de amostra e o ESP no App Engine:

    dotnet restore
    dotnet publish
    gcloud app deploy src\IO.Swagger\bin\Debug\netcoreapp2.0\publish\app.yaml

O comando gcloud app deploy cria um registro DNS no formato YOUR_PROJECT_ID.appspot.com, usado ao enviar solicitações à API. Recomendamos que você espere alguns minutos antes de enviar solicitações para a API enquanto o Google App Engine é completamente inicializado.

Caso receba uma mensagem de erro, consulte Como solucionar problemas de implantação flexível no App Engine.

Para mais informações, consulte Como implantar o back-end da API.

Como enviar solicitações para a API

Envie solicitações para a API de exemplo depois de implantá-la.

Criar uma chave de API e definir 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: $Env:ENDPOINTS_KEY="AIza..."

Enviar a solicitação

1. No PowerShell, defina uma variável de ambiente para o URL do projeto do App Engine. Substitua YOUR_PROJECT_ID pelo ID do projeto do Google Cloud.

   $Env:ENDPOINTS_HOST="https://YOUR_PROJECT_ID.appspot.com"

2. Teste uma solicitação HTTP usando as variáveis de ambiente ENDPOINTS_HOST e ENDPOINTS_KEY definidas anteriormente:

   Invoke-WebRequest "$ENDPOINTS_HOST/echo?key=$ENDPOINTS_KEY" `
     -Body '{"message": "hello world"}' -Method POST `
     -ContentType "application/json"
   

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 ver informações sobre as opções usadas na solicitação de exemplo, consulte Invoke-WebRequest na documentação da Microsoft.

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.

Como rastrear atividade da API

1. Veja os gráficos de atividades da API na página "Endpoints".

   Ir para a página Serviços do Endpoints

   Pode levar alguns instantes até 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 amostra. Para saber mais, consulte a Visão geral do Portal do Cloud Endpoints.