Esta página foi traduzida pela API Cloud Translation.

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

Neste tutorial, veja como configurar e implantar uma amostra da API .NET Core e o Extensible Service Proxy (ESP) em execução em uma instância no ambiente flexível do App Engine. 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.

Obter o exemplo de código

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

Faça o download do código de amostra como um arquivo zip.
Extraia o arquivo zip e mude para o diretório dotnet-docs-samples-master\endpoints\getting-started.
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).

Para configurar o Endpoints:

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.
Na linha com o campo host, substitua YOUR-PROJECT-ID pelo ID do projeto 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:

Verifique se você está no diretório endpoints/getting-started.
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 ver a configuração do serviço do Endpoints na página Endpoints > Serviços no Google Cloud console.

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

No mínimo, o Endpoints e o ESP exigem a ativação dos seguintes serviços do Google:

Nome	Título
`servicemanagement.googleapis.com`	API Service Management
`servicecontrol.googleapis.com`	API Service Control

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 doGoogle Cloud atual em que esses serviços foram explicitamente desativados.

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

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.

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:

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

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.

Verifique se você está no diretório endpoints/getting-started, em que está localizado o arquivo de configuração openapi-appengine.yaml.
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.

No mesmo projeto Google Cloud usado para a API, crie uma chave de API na página de credenciais da API. Se você quiser 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
Clique em Criar credenciais e, em seguida, selecione Chave de API.
Copie a chave para a área de transferência.
Clique em Fechar.
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

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

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

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

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.
Verifique os registros de solicitações da API na página "Explorador de registros".

Acessar a página Análise de registros