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. Em todas elas, é necessário que as solicitações para a API sejam enviadas com sucesso.

1. Configurar 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. Gere 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 à API. Consulte Como enviar uma solicitação à API.
9. Rastreie a atividade da API. Consulte Como rastrear a atividade da API.
10. Para evitar cobranças na sua conta do Google Cloud . Consulte Limpeza.

Custos

Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:

• Endpoints
• App Engine

Para gerar uma estimativa de custo baseada na sua projeção de uso, use a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste gratuito.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Para mais informações, consulte Limpeza.

Antes de começar

Observação: verifique se o Python 2.7.x está instalado. O Python 3.x não é compatível com o Endpoints Frameworks.

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 (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 (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. Anote o ID do projeto Google Cloud , porque ele será necessário mais tarde.

Como instalar e configurar o software necessário

1. Siga as instruções em Como instalar a Google Cloud CLI 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 a CLI gcloud.

      gcloud components update

   2. Verifique se a Google Cloud CLI (gcloud) está autorizada a acessar seus dados e serviços em 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 Google Cloud. Se você tiver outros projetos do Google Cloud e quiser usar gcloud para gerenciá-los, consulte Como gerenciar configurações da CLI gcloud.

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 Google Cloude [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]

      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 Python do Endpoints Frameworks. 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.

Observação: não execute o Python em um ambiente virtual. Os pacotes do Endpoints Frameworks precisam ser instalados no subdiretório lib do diretório do projeto no computador.

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

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.

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

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

2. Open the app.yaml file in the python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo directory.

   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

Faça as seguintes alterações na seção env_variables:

• No campo ENDPOINTS_SERVICE_NAME, substitua YOUR-PROJECT-ID pelo ID do projeto do 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

Execute este comando:

gcloud app deploy

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 Google Cloud ID do projeto:

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

Aplicativo de terceiros

É possível usar um aplicativo de terceiros, como o Postman, uma extensão do navegador Chrome, para enviar a solicitação:

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

Observação: se quiser nos contar do que você gostou neste tutorial, envie um feedback na parte inferior desta página. Isso é muito importante para a melhoria dos tutoriais.
Se ocorrer um erro, entre no grupo do Google google-cloud-endpoints e informe o que aconteceu. Nesse grupo, são enviadas respostas de outros usuários do Endpoints e de engenheiros do Google, que o monitoram.

Rastrear a atividade da API

1. Veja os gráficos de atividade da API no console do Google 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 Análise de registros

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Cuidado: excluir um projeto tem os seguintes efeitos:
• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.
1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

A seguir

• Saiba mais sobre a arquitetura do Endpoints Frameworks.
• Saiba mais sobre como criar uma API.
• Saiba mais sobre como criar um servidor da Web para disponibilizar sua API.
• Saiba mais sobre como exibir sua API a partir de um caminho diferente.
• Saiba mais sobre como monitorar a API.
• Saiba mais sobre como restringir o acesso com chaves de API.
• Saiba mais sobre como configurar um nome de domínio personalizado.
• Saiba mais sobre como gerenciar o controle de versões da API.
• Saiba mais sobre as opções de suporte.