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

Objetivos

Use a seguinte lista de tarefas de alto nível à medida que avança no tutorial. Todas as tarefas são necessárias para enviar pedidos com êxito para a API.

1. Configure um Google Cloud projeto, instale o software necessário e crie uma aplicação do App Engine. Consulte a secção Antes de começar.
2. Transfira o exemplo de código. Consulte o artigo Obter o código de exemplo.
3. Configure o ficheiro openapi.yaml, que é usado para configurar pontos finais. Consulte o artigo Configurar pontos finais.
4. Implemente a configuração do Endpoints para criar um serviço do Endpoints. Consulte o artigo Implementar a configuração dos Endpoints.
5. Implemente a API de exemplo e o ESP no App Engine. Consulte o artigo Implementar o back-end da API.
6. Envie um pedido para a API. Consulte o artigo Enviar uma solicitação para a API.
7. Acompanhe a atividade da API. Consulte o artigo Acompanhamento da atividade da API.
8. Evite incorrer em cobranças na sua conta Google Cloud . Consulte a secção Limpar.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• App Engine
• Endpoints

Para gerar uma estimativa de custos com base na sua utilização prevista, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

Antes de começar

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Tome nota do ID do projeto, uma vez que é necessário mais tarde.
2. Este tutorial requer o SDK.NET Core 2.x, que pode usar com qualquer editor de texto. Embora não seja necessário um ambiente de programação integrado (IDE), para maior comodidade, recomendamos que use um dos seguintes IDEs:
   • Visual Studio Code, que é executado no macOS, Linux e Windows. Se usar o Visual Studio Code, também tem de instalar o .NET Core 2.x.
   • Visual Studio 2017 para Windows, que inclui o .NET Core 2.x. Se usar o Visual Studio 2017, recomendamos que use o plug-in Google Tools for Visual Studio, que integra a implementação do App Engine no IDE.
   • Visual Studio para Mac, que inclui o .NET Core 2.x.

3. Precisa de uma aplicação para enviar pedidos para a API de exemplo. Este tutorial fornece um exemplo com o Invoke-WebRequest, que é suportado no PowerShell 3.0 e posterior.

4. Transfira a CLI do Google Cloud.
5. Atualize a CLI gcloud e instale os componentes do Endpoints.

   gcloud components update

6. Certifique-se de que a CLI do Google Cloud (gcloud) está autorizada a aceder aos seus dados e serviços em Google Cloud:

   gcloud auth login

   No novo separador do navegador apresentado, selecione uma conta.
7. Defina o projeto predefinido para o ID do seu projeto.

   gcloud config set project YOUR_PROJECT_ID

   Substitua YOUR_PROJECT_ID pelo ID do seu Google Cloud projeto. Se tiver outros Google Cloud projetos e quiser usar gcloud para os gerir, consulte o artigo Gerir configurações da CLI gcloud.

8. Selecione a região onde quer criar a sua aplicação do App Engine. Execute o seguinte comando para obter uma lista de regiões:

   gcloud app regions list

9. Crie uma aplicação do App Engine. Substitua YOUR_PROJECT_ID pelo ID do seu Google Cloud projeto e YOUR_REGION pela região na qual quer que a aplicação do App Engine seja criada.

     gcloud app create \
     --project=YOUR_PROJECT_ID \
     --region=YOUR_REGION
   

Obter o exemplo de código

Para transferir a API de exemplo:

1. Transfira o código de exemplo como um ficheiro ZIP.

2. Extraia o ficheiro ZIP e altere para o diretório dotnet-docs-samples-master\endpoints\getting-started.

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

Tem de ter um documento OpenAPI baseado no OpenAPI 2.0 ou no OpenAPI 3.x que descreva a superfície das suas apps e quaisquer requisitos de autenticação. Para saber mais, consulte o artigo Versões do OpenAPI suportadas.

Também tem de adicionar um campo específico da Google que contenha o URL de cada app para que o ESPv2 tenha as informações necessárias para invocar uma app. Se não conhece o OpenAPI, consulte a vista geral do OpenAPI para mais informações.

OpenAPI 2.0

Para configurar os Endpoints através de uma especificação OpenAPI 2.0, pode usar o ficheiro openapi-appengine.yaml disponível no diretório dotnet-docs-samples-master\endpoints\getting-started do código de exemplo transferido.

O conteúdo da especificação OpenAPI 2.0 deve ser semelhante ao seguinte:

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"
consumes:
- "application/json"
produces:
- "application/json"
schemes:
- "https"
paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      security:
      - api_key: []
  "/auth/info/googlejwt":
    get:
      description: "Returns the requests' authentication information."
      operationId: "auth_info_google_jwt"
      produces:
      - "application/json"
      responses:
        200:
          description: "Authentication info."
          schema:
            $ref: "#/definitions/authInfoResponse"
      x-security:
      - google_jwt:
          audiences:
          # This must match the "aud" field in the JWT. You can add multiple
          # audiences to accept JWTs from multiple clients.
          - "echo.endpoints.sample.google.com"
  "/auth/info/googleidtoken":
    get:
      description: "Returns the requests' authentication information."
      operationId: "authInfoGoogleIdToken"
      produces:
      - "application/json"
      responses:
        200:
          description: "Authenication info."
          schema:
            $ref: "#/definitions/authInfoResponse"
      x-security:
      - google_id_token:
          audiences:
          # Your OAuth2 client's Client ID must be added here. You can add
          # multiple client IDs to accept tokens from multiple clients.
          - "YOUR-CLIENT-ID"

definitions:
  echoMessage:
    type: "object"
    properties:
      message:
        type: "string"
  authInfoResponse:
    properties:
      id:
        type: "string"
      email:
        type: "string"

securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
  # This section configures authentication using Google API Service Accounts
  # to sign a json web token. This is mostly used for server-to-server
  # communication.
  google_jwt:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    # This must match the 'iss' field in the JWT.
    x-google-issuer: "jwt-client.endpoints.sample.google.com"
    # Update this with your service account's email address.
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR-SERVICE-ACCOUNT-EMAIL"
  # This section configures authentication using Google OAuth2 ID Tokens.
  # ID Tokens can be obtained using OAuth2 clients, and can be used to access
  # your API on behalf of a particular user.
  google_id_token:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"

Na linha com o campo do anfitrião, substitua YOUR_PROJECT_ID pelo seu Google Cloud ID do projeto.

OpenAPI 3.x

Para configurar os Endpoints através de uma especificação OpenAPI 3.x, pode substituir o conteúdo do ficheiro openapi-appengine.yaml disponível no diretório dotnet-docs-samples-master\endpoints\getting-started do código de exemplo transferido:

1. Abra o openapi-appengine.yaml no editor de texto e substitua o conteúdo pelo seguinte:

   openapi: 3.0.4
   info:
     description: "A simple Google Cloud Endpoints API example."
     title: "Endpoints Example"
     version: "1.0.0"
   servers:
     - url: "https://YOUR_PROJECT_ID.appspot.com"
       x-google-endpoint: {}
   paths:
     "/echo":
       post:
         description: "Echo back a given message."
         operationId: "echo"
         requestBody:
           description: "Message to echo"
           required: true
           content:
             "application/json":
               schema:
                 $ref: "#/components/schemas/echoMessage"
         responses:
           "200":
             description: "Echo"
             content:
               "application/json":
                 schema:
                   $ref: "#/components/schemas/echoMessage"
         security:
           - api_key: []
     "/auth/info/googlejwt":
       get:
         description: "Returns the requests' authentication information."
         operationId: "auth_info_google_jwt"
         responses:
           "200":
             description: "Authenication info."
             content:
               "application/json":
                 schema:
                   $ref: "#/components/schemas/authInfoResponse"
         security:
           - google_jwt: []
     "/auth/info/googleidtoken":
       get:
         description: "Returns the requests' authentication information."
         operationId: "authInfoGoogleIdToken"
         responses:
           "200":
             description: "Authenication info."
             content:
               "application/json":
                 schema:
                   $ref: "#/components/schemas/authInfoResponse"
         security:
           - google_id_token: []
   
   components:
     schemas:
       echoMessage:
         type: "object"
         properties:
           message:
             type: "string"
       authInfoResponse:
         type: "object"
         properties:
           id:
             type: "string"
           email:
             type: "string"
   
     securitySchemes:
       # This section configures basic authentication with an API key.
       api_key:
         type: apiKey
         name: key
         in: query
       # This section configures authentication using Google API Service Accounts
       # to sign a json web token. This is mostly used for server-to-server
       # communication.
       google_jwt:
         type: oauth2
         flows:
           implicit:
             authorizationUrl: ""
             scopes: {}
         x-google-auth:
           issuer: "jwt-client.endpoints.sample.google.com"
           jwksUri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR_SERVICE_ACCOUNT_EMAIL"
           audiences:
             - "echo.endpoints.sample.google.com"
           # This must match the "aud" field in the JWT. You can add multiple
           # audiences to accept JWTs from multiple clients.
       # This section configures authentication using Google OAuth2 ID Tokens.
       # ID Tokens can be obtained using OAuth2 clients, and can be used to access
       # your API on behalf of a particular user.
       google_id_token:
         type: oauth2
         flows:
           implicit:
             authorizationUrl: ""
             scopes: {}
         x-google-auth:
           issuer: "https://accounts.google.com"
           jwksUri: "https://www.googleapis.com/oauth2/v1/certs"
           audiences:
             - "YOUR_CLIENT_ID"

2. Guarde o novo conteúdo de openapi.yaml.

Nota: o ficheiro de exemplo openapi-appengine.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.

Este tutorial usa uma extensão específica da Google à especificação OpenAPI que lhe permite configurar o nome do serviço. O método para especificar o nome do serviço depende da versão da especificação OpenAPI que está a usar.

OpenAPI 2.0

Use o campo host para especificar o nome do serviço:

host: YOUR_PROJECT_ID.appspot.com

Para configurar pontos finais:

1. Abra o ficheiro openapi-appengine.yaml.
2. No campo host, substitua YOUR_PROJECT_ID pelo seu Google Cloud ID do projeto.
3. Guarde o ficheiro openapi-appengine.yaml.

OpenAPI 3.x

Use o campo url no objeto servers para especificar o nome do serviço:

servers:
- url: https://YOUR_PROJECT_ID.appspot.com
  x-google-endpoint: {}

Para configurar pontos finais:

1. Abra o ficheiro openapi-appengine.yaml.
2. Se o ficheiro openapi-appengine.yaml tiver um campo host, remova-o.
3. Adicione um objeto servers, conforme mostrado.
4. No campo url, substitua YOUR_PROJECT_ID pelo seu Google Cloud ID do projeto.
5. Guarde o ficheiro openapi-appengine.yaml.

Nota: tem de incluir x-google-endpoint: {} no objeto server para especificar o URL correto que os servidores devem usar. Podem ser incluídos outros servidores nesta lista, mas exatamente um tem de ter x-google-endpoint: {} para especificar o correto. Todos os outros são ignorados.

Implementação da 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 onde se encontra o ficheiro de configuração openapi.yaml.
2. Carregue a configuração e crie um serviço gerido:

   gcloud endpoints services deploy openapi.yaml
   

O comando gcloud chama a API Service Management para criar um serviço gerido com o nome especificado no campo host ou servers.url 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 a 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 [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.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:

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

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

3. Certifique-se de que está no diretório endpoints/getting-started, onde se encontra o ficheiro de configuração openapi.yaml.
4. 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.

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: $Env:ENDPOINTS_KEY="AIza..."

Envie o pedido

1. 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"

2. 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!

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.

Acompanhamento da atividade da API

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

2. Consulte os registos de pedidos da sua API na página do explorador de registos.

   Aceda à página do Explorador de registos

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

Limpar

Consulte o artigo Eliminar uma API e instâncias de API para obter informações sobre como parar os serviços usados por este tutorial.

O que se segue?

• Partilhe a sua API com outro programador
• Saiba mais acerca da autenticação
• Saiba mais sobre as opções de apoio técnico da comunidade