Começar a usar os frameworks do Cloud Endpoints para Python

---

Esta página mostra como configurar, implementar e enviar pedidos para uma API de exemplo através dos Cloud Endpoints Frameworks para Python. O Endpoints Frameworks para Python está integrado com o ambiente de tempo de execução padrão do Python 2.7 do App Engine. Os Frameworks de Endpoints consistem em ferramentas, bibliotecas e capacidades que lhe permitem gerar APIs e bibliotecas cliente a partir de uma aplicação do App Engine.

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. Consulte a secção Antes de começar.
2. Instale o software necessário e crie uma aplicação do App Engine. Consulte o artigo Instalar e configurar o software necessário.
3. Transfira o exemplo de código. Consulte a secção Obter o exemplo de código.
4. Gerar um documento OpenAPI. Consulte o artigo Configurar pontos finais.
5. Implemente a configuração do Endpoints para criar um serviço do Endpoints. Consulte o artigo Implementar a configuração dos Endpoints.
6. Execute o exemplo no seu computador. Veja o artigo Executar o exemplo localmente.
7. Crie um back-end para publicar a API e implemente a API. Consulte o artigo Implementar o back-end da API.
8. Envie um pedido para a API. Consulte o artigo Enviar um pedido para a API.
9. Acompanhe a atividade da API. Consulte o artigo Acompanhamento da atividade da API.
10. 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:

• Endpoints
• App Engine

Para gerar uma estimativa de custos com base na sua utilização projetada, 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

Nota: certifique-se de que tem o Python 2.7.x instalado. O Python 3.x não é suportado pelos frameworks de pontos finais.

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. Tome nota do Google Cloud ID do projeto, uma vez que é necessário mais tarde.

Instalar e configurar o software necessário

1. Siga as instruções em Instalar a CLI Google Cloud para Python para configurar o seu ambiente de desenvolvimento padrão do App Engine. Certifique-se de que instala os componentes app-engine-python e app-engine-python-extras gcloud.
2. Execute os seguintes comandos:
   1. Atualize a CLI gcloud.

      gcloud components update

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

   3. No novo separador do navegador apresentado, escolha uma conta.
   4. Defina o projeto predefinido para o ID do seu projeto.

      gcloud config set project [YOUR_PROJECT_ID]

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

3. Precisa de uma aplicação para enviar pedidos para a API de exemplo.

   • Utilizadores do Linux e macOS: este tutorial oferece um exemplo de utilização do curl, que normalmente vem pré-instalado no seu sistema operativo. Se não tiver o curl, pode transferi-lo na curl página de lançamentos e transferências.
   • Utilizadores do Windows: este tutorial fornece um exemplo com Invoke-WebRequest, que é suportado no PowerShell 3.0 e posterior.
4. Certifique-se de que o seu ambiente de desenvolvimento Python inclui o pip.
5. Certifique-se de que consegue compilar extensões C para Python.
   • Windows: é necessário o Microsoft Visual C++ 9.0 ou superior. Pode transferir o compilador Microsoft Visual C++ para Python 2.7 a partir do Centro de Transferências da Microsoft .
   • Outros sistemas operativos: consoante o seu sistema operativo, pode ter de instalar ferramentas de compilação (por vezes, num pacote denominado build-essential) ou os cabeçalhos de desenvolvimento do Python (por vezes, num pacote denominado python-dev).

6. Para o Linux, defina a variável de ambiente ENDPOINTS_GAE_SDK para o 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 seguinte comando:

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

7. Crie uma aplicação do App Engine:
   1. 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

   2. Crie uma aplicação do App Engine com o seguinte comando. 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]

      Por exemplo:

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

Obter o exemplo de código

Para clonar a API de exemplo do GitHub:

1. Clone o repositório de exemplo para a sua máquina local:

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples
   

2. Altere para o diretório que contém o código de exemplo:

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

Configurar pontos finais

Para configurar os Endpoints, tem de instalar primeiro a biblioteca Python dos Frameworks dos Endpoints. Em seguida, usa uma ferramenta da biblioteca Endpoints Frameworks para gerar um documento OpenAPI para a API de exemplo. Precisa da biblioteca Endpoints Frameworks e do documento OpenAPI para que o Endpoints possa gerir a API. Para mais informações, consulte Adicionar gestão de APIs.

Instalar a biblioteca Endpoints Frameworks

Esta secção explica como usar o pip do Python para adicionar a biblioteca Endpoints Frameworks ao diretório do projeto da API de exemplo.

Nota: não execute o Python num ambiente virtual. Os pacotes do Frameworks de Endpoints têm de ser instalados no subdiretório lib no diretório do projeto no seu computador.

Para adicionar a biblioteca Endpoints Frameworks ao exemplo:

1. Certifique-se de que está no diretório principal da API de exemplo, python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo.

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

   mkdir lib
   

3. A partir do diretório principal de exemplo python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo, execute o comando de instalação:

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

   Tenha em conta o seguinte:

   • Este comando pip pode usar a GNU Compiler Collection (GCC) para compilar módulos de extensão. Se estiver no macOS e esta for a primeira vez que executa o GCC no seu sistema, pode ter de aceitar a licença do XCode da Apple. Para o fazer, execute sudo xcodebuild -license.

   • Se tiver várias versões do Python instaladas no seu computador, certifique-se de que está a usar uma versão do pip correspondente à versão do Python que está a usar neste tutorial. As incompatibilidades de versões (por exemplo, pip do Python 3.4 enquanto usa python do Python 2.7) podem causar erros que podem ser difíceis de compreender. Se necessário, pode executar o pip como um módulo do Python: substitua pip no comando anterior por python -m pip.

   • Se pip não conseguir encontrar um pacote adequado quando executar o comando, experimente atualizá-lo executando pip install --upgrade pip. Após a conclusão da atualização, experimente novamente o comando de instalação.

   • Em algumas versões do Debian e Ubuntu, a instalação do pip pode falhar com o erro DistutilsOptionError. Se vir este erro, adicione a flag --system.

Após a conclusão com êxito, o diretório lib é preenchido com os ficheiros necessários para criar a aplicação Endpoints Frameworks.

A gerar o documento OpenAPI

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

Para gerar o documento OpenAPI:

1. Certifique-se de que está no diretório principal de exemplo:

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

2. Gere o documento OpenAPI:

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

   Substitua [YOUR_PROJECT_ID] pelo ID do seu Google Cloud projeto. Ignore os avisos apresentados. A ferramenta Endpoints gera um documento OpenAPI denominado echov1openapi.json no diretório atual. A ferramenta Endpoints atribui ao ficheiro o nome com base no nome e na versão do serviço especificados no decorador @endpoints.api. Consulte a secção Criar a API para mais informações.

   Os Endpoints usam o texto especificado no argumento hostname como o nome do serviço. O formato do nome YOUR_PROJECT_ID.appspot.com corresponde à entrada DNS criada automaticamente quando implementa a API no back-end do App Engine. Neste caso, o nome do serviço e o nome do domínio totalmente qualificado (FQDN) do Endpoints são iguais.

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

Implementar a configuração dos pontos finais

Para implementar a configuração do Endpoints, usa a infraestrutura de serviços, a plataforma de serviços fundamentais da Google, usada pelo Endpoints e outros serviços para criar e gerir APIs e serviços.

Para implementar o ficheiro de configuração:

1. Certifique-se de que está no diretório principal de exemplo:

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

2. Implemente o documento OpenAPI gerado na secção anterior executando o seguinte comando:

   gcloud endpoints services deploy echov1openapi.json

   Esta ação cria um novo serviço Endpoints com o nome que especificou no argumento hostname quando executou a ferramenta Endpoints para gerar o documento OpenAPI. Independentemente do nome do serviço Endpoints, quando implementa a API no App Engine, é criado um registo DNS com o formato de nome YOUR_PROJECT_ID.appspot.com, que é o FQDN que usa quando envia pedidos para a API.

   À medida que cria e configura o serviço, o Service Management envia muitas informações para o terminal. Pode ignorar com segurança os avisos sobre os caminhos em echov1openapi.json que não requerem uma chave da API. Quando a implementação estiver concluída, é apresentada uma mensagem semelhante à seguinte:

   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.

   Consulte gcloud endpoints services deploy na documentação de referência da gcloud para mais informações.

A verificar os serviços necessários

Para fornecer a gestão de APIs, o Endpoints Frameworks requer os seguintes serviços:

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.

Executar o exemplo localmente

Após implementar a configuração dos Endpoints, pode executar o exemplo localmente através do servidor de desenvolvimento local.

1. Certifique-se de que está no diretório principal de exemplo:

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

2. Inicie o servidor de desenvolvimento local:

   dev_appserver.py ./app.yaml
   

   Por predefinição, o servidor de desenvolvimento escuta em http://localhost:8080, conforme indicado nos registos da consola impressos por dev_appserver.py: Google Cloud

   INFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080
   

3. Envie um pedido para o servidor de programação 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

Nos curl anteriores:

• A opção --data especifica os dados a publicar na 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 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"
}

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 amostra no App Engine.

Para implementar o back-end da API:

1. Execute o seguinte comando para apresentar o ID de configuração do serviço:

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

   Substitua [YOUR_PROJECT_ID] pelo ID do seu projeto. Por 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 secção env_variables:

• No campo ENDPOINTS_SERVICE_NAME, substitua YOUR-PROJECT-ID pelo seu Google Cloud ID do projeto.
• 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 o seguinte comando:

gcloud app deploy

Siga as instruções no ecrã. Aguarde alguns momentos para que a implementação seja bem-sucedida, ignorando as mensagens de aviso. Quando a implementação estiver concluída, é apresentada uma mensagem semelhante à seguinte:

File upload done.
Updating service [default]...done.

Se recebeu uma mensagem de erro, consulte a secção Resolução de problemas na documentação do App Engine para informações.

Recomendamos que aguarde alguns minutos antes de enviar pedidos para a sua API enquanto o App Engine é completamente inicializado.

Enviar um pedido para a API de exemplo

Linux ou Mac OS

Envie um pedido HTTP através de curl. Substitua [YOUR_PROJECT_ID] pelo seu 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

Nos curl anteriores:

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

PowerShell

Envie um pedido HTTP através de Invoke-WebRequest. Substitua [YOUR_PROJECT_ID] pelo ID do seu Google Cloud projeto:

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

App de terceiros

Pode usar uma aplicação de terceiros, como a extensão do navegador Chrome Postman, para enviar o pedido:

• Selecione POST como verbo HTTP.
• Para o cabeçalho, selecione a chave content-type e o valor application/json.
• Para o corpo, introduza o seguinte:
  {"message":"hello world"}
• Introduza o URL da aplicação de exemplo. Por exemplo:
  https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

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.

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 Google Cloud consola na página Endpoints > Serviço.

   Aceda à página Serviços de pontos finais

   Pode demorar alguns momentos até que o pedido seja refletido 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.

Atenção: a eliminação de um projeto tem os seguintes efeitos:
• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar 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.

O que se segue?

• Saiba mais acerca da arquitetura dos Frameworks de Endpoints.
• Saiba como criar uma API.
• Saiba como criar um servidor Web para publicar a sua API.
• Saiba como servir a sua API a partir de um caminho diferente.
• Saiba como monitorizar a sua API.
• Saiba como restringir o acesso com chaves de API.
• Saiba como configurar um nome de domínio personalizado.
• Saiba como tratar o controlo de versões da API.
• Saiba mais acerca das opções de apoio técnico.