Esta página foi traduzida pela API Cloud Translation.

Introdução ao Cloud Endpoints no ambiente flexível do App Engine (.NET) com o ESP

Este tutorial mostra como configurar e implementar uma API .NET Core de exemplo e o Extensible Service Proxy (ESP) em execução numa instância no ambiente flexível do App Engine. A API REST do código de exemplo é 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.

Obter o exemplo de código

Para transferir a API de exemplo:

Transfira o código de exemplo como um ficheiro ZIP.
Extraia o ficheiro ZIP e altere para o diretório dotnet-docs-samples-master\endpoints\getting-started.
Abra GettingStarted.sln com o Visual Studio ou use o seu editor favorito para editar os ficheiros no diretório endpoints\getting-started\src\IO.Swagger.

Configurar pontos finais

O exemplo de código inclui o ficheiro de configuração da OpenAPI, openapi-appengine.yaml, que se baseia na especificação da OpenAPI v2.0.

Para configurar pontos finais:

No diretório de código de exemplo, abra o openapi-appengine.yamlficheiro de configuração.
```
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"
```
Tenha em conta o seguinte:
- O exemplo de configuração apresenta as linhas junto ao campo host que tem de modificar. Para implementar openapi-appengine.yaml nos Endpoints, é necessário o documento OpenAPI completo.
- O exemplo openapi-appengine.yaml contém uma secção para configurar a autenticação que não é necessária para este tutorial. Não tem 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-appengine.yaml encontra-se no exemplo getting-started no repositório do GitHub de cada idioma para sua conveniência.
Na linha com o campo host, substitua YOUR-PROJECT-ID pelo ID do seu Google Cloud projeto. Por exemplo:
```
host: "example-project-12345.appspot.com"
```

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

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

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:

Certifique-se de que está no diretório endpoints/getting-started.

Carregue a configuração e crie um serviço gerido:

gcloud endpoints services deploy openapi-appengine.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-appengine.yaml. A gestão de serviços configura o serviço de acordo com as definições no ficheiro openapi-appengine.yaml. Quando faz alterações ao openapi-appengine.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-appengine.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 [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 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-appengine.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 implementar a API de exemplo e o ESP no App Engine.

Para implementar o back-end da API:

Abra o ficheiro endpoints/getting-started/src/IO.Swagger/app.yaml e adicione o nome do seu 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 seu serviço Endpoints. Este é o mesmo nome que configurou no campo host do seu documento OpenAPI. Por 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 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.

Guarde o ficheiro app.yaml.

Uma vez que a secção endpoints_api_service está incluída no ficheiro app.yaml, o comando gcloud app deploy implementa e configura o ESP num contentor separado do ambiente flexível do App Engine. Todo o tráfego de pedidos é encaminhado através do ESP, e este encaminha pedidos e respostas de e para o contentor que executa o seu código do servidor de back-end.

Certifique-se de que está no diretório endpoints/getting-started, onde se encontra o ficheiro de configuração openapi-appengine.yaml.
Implemente a API de exemplo 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 registo de DNS no formato YOUR_PROJECT_ID.appspot.com, que usa quando envia pedidos à API. Recomendamos que aguarde alguns minutos antes de enviar pedidos à sua API enquanto o App Engine é completamente inicializado.

Se receber uma mensagem de erro, consulte o artigo Resolução de problemas da implementação flexível do App Engine.

Para mais informações, consulte o artigo Implementar o back-end da API.

Enviar pedidos para a API

Depois de implementar a API de exemplo, pode enviar-lhe pedidos.

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.

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
Clique em Criar credenciais e, de 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 a atribuir a uma variável de ambiente: $Env:ENDPOINTS_KEY="AIza..."

Envie o pedido

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

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

Teste um pedido HTTP com as variáveis de ambiente ENDPOINTS_HOST e ENDPOINTS_KEY que definiu anteriormente:

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

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.

A API devolve a mensagem que lhe 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!

Acompanhamento da atividade da API

Veja os gráficos de atividade da sua API na página Endpoints.

Aceda à página Serviços de pontos finais

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

Aceda à página do Explorador de registos