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

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

Lista de tarefas

Ao seguir o tutorial, use a lista geral de tarefas abaixo. A todas elas é exigido que as solicitações para a API sejam enviadas com sucesso.

  1. Configure um projeto do Cloud Platform, instale o software necessário e crie um aplicativo do App Engine. Consulte Antes de começar.
  2. Faça o download do código de amostra. Consulte Como conseguir o código de amostra.
  3. Configure o arquivo openapi-appengine.yaml, usado para configurar o Endpoints. Consulte Como configurar o Endpoints.
  4. Implante a configuração do Endpoints para criar um serviço do Cloud Endpoints. Consulte Como implantar a configuração do Endpoints.
  5. Crie um back-end para veicular a API e implante-a. Consulte Como implantar o back-end da API.
  6. Envie uma solicitação à API. Consulte Como enviar uma solicitação à API.
  7. Rastreie a atividade da API. Consulte Como rastrear a atividade da API.
  8. Evite cobranças na sua conta do Google Cloud Platform. Consulte Fazer a limpeza.

Antes de começar

  1. Faça login na sua Conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. Selecione ou crie um projeto do GCP.

    Acessar a página Gerenciar recursos

  3. Verifique se o faturamento foi ativado para o projeto.

    Saiba como ativar o faturamento

  4. Anote o código do projeto. Ele será necessário mais adiante.
  5. Este tutorial requer o .NET Core 2.x SDK, que você pode usar com qualquer editor de texto. Um ambiente de desenvolvimento integrado (IDE, na sigla em inglês) não é necessário, mas, para fins de conveniência, recomendamos que você use um dos seguintes IDEs:
  6. Você precisará de um aplicativo para enviar solicitações à API de amostra. Neste tutorial, fornecemos um exemplo usando Invoke-WebRequest, que é compatível com PowerShell 3.0 e posterior.

  7. Faça o download do Google Cloud SDK.
  8. Atualize o Cloud SDK e instale os componentes do Endpoints.
    gcloud components update
  9. Verifique se o Cloud SDK (gcloud) tem autorização para acessar seus dados e serviços no Google Cloud Platform:
    gcloud auth login
    Uma nova guia do navegador será aberta, e você precisará escolher uma conta.
  10. Configure o projeto padrão como o código do projeto.
    gcloud config set project [YOUR_PROJECT_ID]

    Substitua [YOUR_PROJECT_ID] pelo código do seu projeto no Cloud. Para usar o gcloud no gerenciamento de outros projetos do Cloud Platform, consulte Como gerenciar configurações do SDK do Cloud.

  11. Selecione a região onde pretende criar o aplicativo do App Engine. Execute o comando a seguir para visualizar uma lista de regiões:
    gcloud app regions list
  12. Crie um aplicativo do App Engine com o comando a seguir. Substitua [YOUR_PROJECT_ID] pelo código do projeto do Cloud e [YOUR_REGION] pela região em que o aplicativo do App Engine deverá ser criado.
      gcloud app create \
      --project=[YOUR_PROJECT_ID] \
      --region=[YOUR_REGION]
    

Como conseguir o código de amostra

Para fazer o download da API de Por exemplo:

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

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

  3. Abra o GettingStarted.sln com o Visual Studio ou use seu editor preferido 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 OpenAPI, openapi-appengine.yaml, baseado na especificação OpenAPI v2.0.

Para configurar o Endpoints:
  1. No diretório do 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:

    • É necessário modificar as linhas próximas ao campo host, exibidas na amostra de configuração. Para implantar openapi-appengine.yaml no Cloud Endpoints, é necessário o documento completo da OpenAPI.
    • O openapi-appengine.yaml de exemplo contém uma seção para configurar a autenticação que não é necessária para este tutorial. Você não precisa configurar as linhas com YOUR-SERVICE-ACCOUNT-EMAIL e YOUR-CLIENT-ID.
    • A OpenAPI é uma especificação agnóstica de linguagem. O mesmo arquivo openapi-appengine.yaml está na amostra de introdução em cada repositório do GitHub de linguagem para fins de conveniência.
  2. Na linha com o campo host, substitua YOUR-PROJECT-ID pelo código do projeto do Cloud. Por exemplo:
    host: "example-project-12345.appspot.com"
    

O Cloud 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 é criada automaticamente com um nome no formato YOUR-PROJECT-ID.appspot.com.

Para mais informações sobre os campos no documento da OpenAPI exigido pelo Cloud 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. Esse comando usa o Service Infrastructure, um serviço de infraestrutura do GCP que gerencia outras APIs e serviços, incluindo serviços criados com o Cloud Endpoints.

Para implantar a configuração do Endpoints:
  1. Acesse o diretório endpoints/getting-started.
  2. Chame o comando a seguir:
    gcloud endpoints services deploy openapi-appengine.yaml

    Com esse comando, é criado um novo serviço do Cloud Endpoints com o nome especificado no campo host do arquivo openapi-appengine.yaml, caso ainda não exista. O serviço é atualizado de acordo com o documento OpenAPI. Seja qual for o nome do serviço do Endpoints, quando você implanta a API no App Engine, um registro DNS é criado com o formato de nome PROJECT-ID.appspot.com, que é o FQDN usado no envio de solicitações à API.

    Durante a criação e a configuração do serviço, o Service Management envia uma grande quantidade de informações ao terminal. É seguro ignorar os avisos sobre os caminhos no openapi-appengine.yaml que não exigem uma chave de API. Após a conclusão, será exibida uma linha como esta, que exibe o código de configuração e o nome do serviço:

    Service Configuration [2017-02-13-r0] uploaded for service [example-project-12345.appspot.com]
    

No exemplo acima, 2017-02-13-r0 é o código de configuração do serviço e example-project-12345.appspot.com é o nome do serviço. 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 openapi-appengine.yaml novamente no mesmo dia, o número de revisão será alterado no código de configuração do serviço.

Se você receber uma mensagem de erro, consulte Como solucionar problemas de implantação na configuração do Endpoints.

Para mais informações, consulte Como implantar a configuração do Endpoints.

Como implantar o back-end da API

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

Para implantar o back-end da API:

  1. Abra endpoints/getting-started/src/IO.Swagger/app.yaml e adicione o nome do serviço:
  2. 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 do Endpoints. Esse nome é o mesmo que você configurou no campo host do documento da 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 implantação mais recente da configuração do serviço. Quando essa opção é especificada, a alteração é detectada e começa a ser usada automaticamente pelo ESP um minuto após você ter feito a implantação da nova configuração de serviço. Recomendamos especificar essa opção em vez de um código de configuração específico para uso do ESP.

  3. Salve o arquivo app.yaml.
  4. Como a seção endpoints_api_service está incluída no app.yaml, o ESP é implantado e configurado pelo comando gcloud app deploy no ambiente flexível do App Engine em um contêiner separado. 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.

  5. Verifique se você está no diretório endpoints/getting-started, onde está localizado o arquivo de configuração openapi-appengine.yaml.
  6. Execute os seguintes comandos para implantar a API de exemplo no App Engine:
  7.     dotnet restore
        dotnet publish
        gcloud app deploy src\IO.Swagger\bin\Debug\netcoreapp2.0\publish\app.yaml
    

    Recomendamos aguardar o término da inicialização do App Engine antes de enviar solicitações à API.

Consulte Como solucionar problemas de implantação flexível no App Engine caso receba uma mensagem de erro.

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 GCP 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 GCP, consulte Como ativar uma API no projeto do Cloud.

    Conseguir uma chave de API

  2. Clique em Criar credenciais e selecione Chave de API.
  3. Copie a chave para a área de transferência.
  4. Clique em Close.
  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 seu código de projeto do GCP:

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

  2. Teste uma solicitação HTTP usando o cmdlet Invoke-WebRequest e 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 saber mais 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 você não tiver recebido uma resposta bem-sucedida, veja Solução de problemas em erros de respostas.

Você acabou de implantar e testar uma API no Cloud Endpoints.

Como rastrear atividade da API

  1. Veja os gráficos de atividades da API na página "Endpoints".
    Ver gráficos de atividades 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 "Visualizador de registros".
    Ver registros de solicitações do Endpoints

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 que você pode usar para interagir com a API de amostra. Para saber mais, consulte a Visão geral do Portal do Cloud Endpoints.

Limpar

Para evitar cobranças na sua conta do GCP pelo uso de recursos neste guia de início rápido:

Consulte Como excluir uma API e as instâncias relacionadas para saber mais informações sobre como parar os serviços usados neste tutorial.

Próximas etapas

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Cloud Endpoints com OpenAPI
Precisa de ajuda? Acesse nossa página de suporte.