Primeiros passos com o Endpoints Frameworks para Python

Nesta página, você aprenderá a configurar, implantar e enviar solicitações para uma API de amostra usando o Cloud Endpoints Frameworks para Python. Ele é integrado ao ambiente de execução padrão do App Engine para Python 2.7. O Endpoints Frameworks consiste em ferramentas, bibliotecas e recursos que permitem gerar APIs e bibliotecas de clientes a partir de um aplicativo do App Engine.

Objetivos

Ao seguir o tutorial, use a lista detalhada de tarefas abaixo. Para enviar solicitações à API, é necessário concluir todas as tarefas.

  1. Configure um projeto do Google Cloud. Consulte Antes de começar.
  2. Instale o software necessário e crie um aplicativo do App Engine. Consulte Como instalar e configurar o software necessário.
  3. Faça o download do código de amostra. Consulte Como conseguir o código de amostra.
  4. Gerar um documento da OpenAPI. Consulte Como configurar o Endpoints.
  5. Implante a configuração do Endpoints para criar um serviço. Consulte Como implantar a configuração do Endpoints.
  6. Execute a amostra no seu computador. Consulte Como executar a amostra localmente.
  7. Crie um back-end para exibir a API e implante-a. Consulte Como implantar o back-end da API.
  8. Envie uma solicitação para a API. Consulte Como enviar uma solicitação para a API.
  9. Acompanhar a atividade da API. Consulte Como rastrear a atividade da API.
  10. Evite cobranças na sua conta do Google Cloud. Consulte Fazer limpeza.

Custos

Neste tutorial, usamos os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem ser qualificados para uma avaliação gratuita.

Ao concluir este tutorial, exclua os recursos criados para evitar o faturamento contínuo. Para mais informações, consulte Como 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. No Console do Cloud, na página do seletor de projetos, selecione ou crie um projeto do Cloud.

    Acessar a página do seletor de projetos

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud. Saiba como confirmar se a cobrança está ativada para o seu projeto.

  4. Anote o ID do projeto do Google Cloud, porque ele será necessário posteriormente.

Como instalar e configurar o software necessário

  1. Siga as instruções em Como instalar o SDK do Cloud para Python para configurar o ambiente de desenvolvimento padrão do App Engine. Verifique se os componentes app-engine-python e app-engine-python-extras gcloud estão instalados.
  2. Execute os seguintes comandos:
    1. Atualize o SDK do Cloud.
      gcloud components update
    2. Verifique se o SDK do Cloud (gcloud) está autorizado a acessar seus dados e serviços no Google Cloud:
      gcloud auth login
    3. Na nova guia aberta do navegador, escolha uma conta.
    4. Defina o projeto padrão como o ID do projeto.
      gcloud config set project [YOUR_PROJECT_ID]

      Substitua [YOUR_PROJECT_ID] pelo ID do projeto do Google Cloud. Se você tiver outros projetos do Google Cloud e quiser usar gcloud para gerenciá-los, consulte Como gerenciar configurações do SDK do Cloud.

  3. Você precisará que um aplicativo envie solicitações à API de amostra.

    • Usuários de Linux e macOS: este tutorial fornece um exemplo de uso de curl, que normalmente vem pré-instalado em seu sistema operacional. Caso não tenha curl, faça o download na página Versões e downloads (em inglês) do curl.
    • Usuários do Windows: neste tutorial, há um exemplo que usa Invoke-WebRequest (em inglês), que é compatível com o PowerShell 3.0 e versões posteriores.
  4. Verifique se o ambiente de desenvolvimento do Python inclui pip.
  5. Compile as extensões de C para Python.
    • Windows: é necessário ter o Microsoft Visual C++ 9.0 ou posterior. Faça o download do Compilador do Microsoft Visual C++ para Python 2.7 no Centro de Download da Microsoft (em inglês).
    • Outros sistemas operacionais: dependendo do sistema operacional, será preciso instalar ferramentas de compilador (às vezes em um pacote chamado build-essential) ou os cabeçalhos de desenvolvimento em Python (às vezes em um pacote chamado python-dev).
  6. Para Linux, configure a variável de ambiente ENDPOINTS_GAE_SDK no caminho da pasta do SDK do App Engine: [Path-to-Google-Cloud-SDK]/platform/google_appengine.

    Substitua [Path-to-Google-Cloud-SDK] pela saída do comando a seguir:

    gcloud info --format="value(installation.sdk_root)"

  7. Crie um aplicativo do App Engine:
    1. Selecione a região em que você quer criar o aplicativo do App Engine. Execute o comando a seguir para visualizar uma lista de regiões:
      gcloud app regions list
    2. Crie um aplicativo do App Engine usando o comando a seguir. Substitua [YOUR_PROJECT_ID] pelo ID do projeto do Google Cloud e [YOUR_REGION] pela região em que você quer que o aplicativo do App Engine seja criado.
      gcloud app create \
      --project=[YOUR_PROJECT_ID] \
      --region=[YOUR_REGION]

      Por exemplo:

      gcloud app create --project=example-project-12345 --region=us-central

Como conseguir o código de amostra

Para clonar o exemplo de API do GitHub:

  1. Clone o repositório de amostra na sua máquina local:

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples
    
  2. Mude para o diretório que contém o código de amostra:

    cd python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    

Como configurar o Endpoints

Para configurar o Endpoints, instale a biblioteca do Endpoints Frameworks para Python. Em seguida, use uma ferramenta da biblioteca do Endpoints Frameworks para gerar um documento da OpenAPI para a API de amostra. A biblioteca do Endpoints Frameworks e o documento da OpenAPI são necessários para que a API seja gerenciada pelo Endpoints. Para mais informações, consulte Como adicionar gerenciamento de API.

Como instalar a biblioteca do Endpoints Frameworks

Esta seção contém orientações sobre como usar o pip do Python para adicionar a biblioteca Endpoints Frameworks ao diretório do projeto da API de amostra.

Para adicionar a biblioteca do Endpoints Frameworks à amostra, realize as ações a seguir:

  1. Verifique se você está no diretório principal da API de amostra, python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo.

  2. Crie um subdiretório /lib no projeto:

    mkdir lib
    
  3. No diretório principal de amostra python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo, execute o comando de instalação:

    pip install --target lib --requirement requirements.txt --ignore-installed
    

    Observações:

    • O comando pip pode usar o GNU Compiler Collection (GCC) para compilar módulos de extensão. Se você usar o macOS e for executar o GCC no sistema pela primeira vez, talvez seja necessário aceitar a licença de XCode da Apple. Para fazer isso, execute sudo xcodebuild -license.

    • Se você tiver várias versões do Python instaladas no computador, verifique se está usando uma versão de pip correspondente à versão do Python usada neste tutorial. As incompatibilidades de versão (pip do Python 3.4 ao usar python do Python 2.7, por exemplo) podem causar erros difíceis de entender. Se necessário, execute pip como um módulo Python: substitua pip, no comando anterior, por python -m pip.

    • Se pip não conseguir encontrar um pacote adequado ao executar o comando, tente fazer o upgrade executando pip install --upgrade pip. Quando o processo for concluído, teste o comando de instalação novamente.

    • Em algumas versões do Debian e do Ubuntu, pip pode falhar com DistutilsOptionError. Se encontrar esse erro, adicione a sinalização --system.

Se o processo foi bem-sucedido, o diretório lib é preenchido com os arquivos necessários para criar o aplicativo Endpoints Frameworks.

Como gerar um documento da OpenAPI

Use uma ferramenta da biblioteca Endpoints Frameworks para gerar um documento que descreve a API REST do código de amostra.

Para gerar o documento da OpenAPI:

  1. Verifique se você está no diretório principal de amostra:

    python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    
  2. Gere o documento da OpenAPI:

    python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi --hostname [YOUR_PROJECT_ID].appspot.com
    

    Substitua [YOUR_PROJECT_ID] pelo ID do projeto do Google Cloud. Ignore os avisos exibidos. A ferramenta do Endpoints gera um documento da OpenAPI chamado echov1openapi.json no diretório atual. Ela nomeia o arquivo com base no nome e na versão do serviço especificado no decorador @endpoints.api. Para mais informações, consulte Como criar a API.

    O Endpoints usa o texto especificado no argumento hostname como o nome do serviço. O formato de nome YOUR_PROJECT_ID.appspot.com corresponde à entrada DNS criada automaticamente ao implantar a API no back-end do App Engine. Neste caso, o nome do serviço do Endpoints e o nome do domínio totalmente qualificado (FQDN, na sigla em inglês) são iguais.

Após a conclusão, a seguinte mensagem é exibida: OpenAPI spec written to ./echov1openapi.json

Como implantar a configuração do Endpoints

Para implantar a configuração do Endpoints, use o Service Infrastructure, a plataforma de serviços básicos do Google usada pelo Endpoints e outros produtos para a criação e o gerenciamento de APIs e serviços.

Para implantar o arquivo de configuração:

  1. Verifique se você está no diretório principal de amostra:
    python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    
  2. Implante o documento da OpenAPI gerado na seção anterior com o seguinte comando:
    gcloud endpoints services deploy echov1openapi.json
    

    Isso cria um novo serviço do Endpoints com o nome especificado no argumento hostname ao executar a ferramenta do Endpoints para gerar o documento da OpenAPI. Não importa o nome do serviço do Endpoints, ao implantar a API no App Engine, um registro DNS é criado usando o formato de nome YOUR_PROJECT_ID.appspot.com. Este é o FQDN usado ao enviar solicitações para a API.

    Durante a criação e configuração do serviço, o Service Management envia uma grande quantidade de informações ao terminal. Ignore os avisos sobre os caminhos em echov1openapi.json que não exigem uma chave de API. Quando a implantação for concluída, uma mensagem semelhante à seguinte será exibida:

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

    No exemplo anterior, 2017-02-13-r2 é o ID de configuração do serviço e example-project-12345.appspot.com é o nome do serviço.

    Para mais informações, consulte gcloud endpoints services deploy na documentação de referência da gcloud.

Como verificar os serviços obrigatórios

Para fornecer gerenciamento de API, o Endpoints Frameworks requer os seguintes serviços:
Nome Título
servicemanagement.googleapis.com API Service Management
servicecontrol.googleapis.com API Service Control
endpoints.googleapis.com Google Cloud Endpoints

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 Pontos de extremidade 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.

Como executar a amostra no local

Depois de implantar a configuração do Endpoints, execute a amostra no local usando o servidor de desenvolvimento local.

  1. Verifique se você está no diretório principal de amostra:

    python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
    
  2. Inicie o servidor de desenvolvimento local:

    dev_appserver.py ./app.yaml
    

    Por padrão, o servidor de desenvolvimento detecta http://localhost:8080, conforme indicado nos registros do Console do Google Cloud impressos por dev_appserver.py:

    INFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080
    
  3. Envie uma solicitação para o servidor de desenvolvimento local:

Linux ou Mac OS

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    http://localhost:8080/_ah/api/echo/v1/echo

No curl anterior:

  • A opção --data especifica os dados a serem enviados para a API.
  • A opção --header especifica que os dados estão no formato JSON.

PowerShell

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://localhost:8080/_ah/api/echo/v1/echo").Content

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"
}

Como implantar o back-end da API

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

Para implantar o back-end da API:

  1. Exiba o ID de configuração do serviço, executando o seguinte comando:

    gcloud endpoints configs list --service=[YOUR_PROJECT_ID].appspot.com
    

    Substitua [YOUR_PROJECT_ID] pelo ID do projeto. Por exemplo:

    gcloud endpoints configs list --service=example-project-12345.appspot.com
    

  2. Abra o arquivo app.yaml no diretório python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo.
    env_variables:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy swagger.json' command.
      ENDPOINTS_SERVICE_NAME: YOUR-PROJECT-ID.appspot.com
      ENDPOINTS_SERVICE_VERSION: 2016-08-01r0
  3. Faça as seguintes alterações na seção env_variables:
    • No campo ENDPOINTS_SERVICE_NAME, substitua YOUR-PROJECT-ID pelo ID do seu projeto no Google Cloud.
    • No campo ENDPOINTS_SERVICE_VERSION, substitua o texto pelo ID de configuração do serviço. Por exemplo:
      ENDPOINTS_SERVICE_NAME: example-project-12345.appspot.com
      ENDPOINTS_SERVICE_VERSION: 2017-02-13r2
    
  4. Execute este comando:
    gcloud app deploy
    
  5. Siga as instruções na tela. Aguarde um momento até a implantação ser bem-sucedida, ignorando as mensagens de aviso. Quando a implantação for concluída, uma mensagem semelhante à seguinte será exibida:
    File upload done.
    Updating service [default]...done.
    

    Se você receber uma mensagem de erro, consulte a seção Solução de problemas na documentação do App Engine para informações.

    Recomendamos aguardar a inicialização completa do App Engine antes de enviar solicitações à API.

Como enviar uma solicitação à API de exemplo

Linux ou Mac OS

Envie uma solicitação HTTP usando curl. Substitua [YOUR_PROJECT_ID] pelo ID do projeto do Google Cloud.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo

No curl anterior:

  • A opção --data especifica os dados a serem enviados para a API.
  • A opção --header especifica que os dados estão no formato JSON.

PowerShell

Envie uma solicitação HTTP usando Invoke-WebRequest. Substitua [YOUR_PROJECT_ID] pelo ID do projeto do Google Cloud.

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} -URI `
     "https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content

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

App de terceiros

É possível usar um aplicativo terceirizado para enviar a solicitação, como o Postman (em inglês), uma extensão do navegador Chrome:

  • Selecione POST como o verbo HTTP.
  • Para o cabeçalho, selecione a chave content-type e o valor application/json.
  • Para o corpo, digite isto:
    {"message":"hello world"}
  • Digite o URL para o aplicativo de amostra. Por exemplo:
    https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

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.

Como rastrear atividade da API

  1. Veja os gráficos de atividade para sua API no Console do Cloud na página Endpoints > Serviço.

    Ir para a página Serviços do Endpoints

    Pode levar alguns instantes para que a solicitação apareça nos gráficos.

  2. Verifique os registros de solicitações da API na página "Visualizador de registros".

    Acessar a página "Logs Viewer"

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 Visão geral do Portal do Cloud Endpoints.

Como fazer a limpeza

Para evitar cobranças na conta do Google Cloud Platform, referentes aos recursos usados neste tutorial:

  1. No Console do Cloud, acesse a página Gerenciar recursos:

    Acessar a página "Gerenciar recursos"

  2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
  3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

A seguir