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.
- Configure um projeto do Google Cloud. Consulte Antes de começar.
- Instale o software necessário e crie um aplicativo do App Engine. Consulte Como instalar e configurar o software necessário.
- Faça o download do código de amostra. Consulte Como conseguir o código de amostra.
- Gere um documento da OpenAPI. Consulte Como configurar o Endpoints.
- Implante a configuração do Endpoints para criar um serviço. Consulte Como implantar a configuração do Endpoints.
- Execute a amostra no seu computador. Consulte Como executar a amostra localmente.
- Crie um back-end para exibir a API e implante-a. Consulte Como implantar o back-end da API.
- Envie uma solicitação à API. Consulte Como enviar uma solicitação à API.
- Rastreie a atividade da API. Consulte Como rastrear a atividade da API.
- Evite cobranças na sua conta do Google Cloud. Consulte Fazer limpeza.
Custos
Neste documento, você usará 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.
Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.
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.
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
- Anote o ID do projeto do Google Cloud, porque ele será necessário posteriormente.
Como instalar e configurar o software necessário
- Siga as instruções em
Como instalar o CLI do Google Cloud para Python para configurar o ambiente de desenvolvimento padrão do App Engine. Verifique se os componentes
app-engine-python
eapp-engine-python-extras
gcloud
estão instalados. -
Execute os seguintes comandos:
-
Atualizar a CLI gcloud.
gcloud components update
-
Verifique se a CLI do Google Cloud (
gcloud
) está autorizada a acessar seus dados e serviços no Google Cloud:gcloud auth login
- Na nova guia aberta do navegador, escolha uma conta.
-
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 usargcloud
para gerenciá-los, consulte Como gerenciar configurações da CLI gcloud.
-
Atualizar a CLI gcloud.
-
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 tenhacurl
, faça o download na página Versões e downloads (em inglês) docurl
. - 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.
- Usuários de Linux e macOS: este tutorial fornece um exemplo de uso de
- Verifique se o ambiente de desenvolvimento do Python inclui pip.
- 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 chamadopython-dev
).
-
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)"
- Crie um aplicativo do App Engine:
- 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
- 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
- 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:
Como conseguir o código de amostra
Para clonar o exemplo de API do GitHub:
Clone o repositório de amostra na sua máquina local:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples
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, você vai usar uma ferramenta da do Endpoints Frameworks para gerar uma 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:
Verifique se você está no diretório principal da API de amostra,
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
.Crie um subdiretório
/lib
no projeto:mkdir lib
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, executesudo 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 usarpython
do Python 2.7, por exemplo) podem causar erros difíceis de entender. Se necessário, execute pip como um módulo Python: substituapip
, no comando anterior, porpython -m pip
.Se
pip
não conseguir encontrar um pacote adequado ao executar o comando, tente fazer o upgrade executandopip 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:
Verifique se você está no diretório principal de amostra:
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
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 chamadoechov1openapi.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
. Consulte Como criar a API para mais informações.O Endpoints usa o texto especificado no argumento
hostname
como o nome do serviço. O formato de nomeYOUR_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:
- Verifique se você está no diretório principal de amostra:
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
- 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 nomeYOUR_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 eexample-project-12345.appspot.com
é o nome do serviço.Para mais informações, consulte
gcloud endpoints services deploy
na documentação de referência dagcloud
.
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.comgcloud 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 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 camponame
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.
Verifique se você está no diretório principal de amostra:
python-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
Inicie o servidor de desenvolvimento local:
dev_appserver.py ./app.yaml
Por padrão, o servidor de desenvolvimento detecta em
http://localhost:8080
, conforme indicado nos registros do console do Google Cloud impressos pordev_appserver.py
:INFO 2018-01-01 [...] Starting module "default" running at: http://localhost:8080
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:
- 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
- Open the
app.yaml
file in thepython-docs-samples/appengine/standard/endpoints-frameworks-v2/echo
directory. - Faça as seguintes alterações na seção
env_variables
:- No campo
ENDPOINTS_SERVICE_NAME
, substituaYOUR-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
- No campo
- 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.
- 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. - Selecione
POST
como o verbo HTTP. - Para o cabeçalho, selecione a chave
content-type
e o valorapplication/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
Confira os gráficos de atividade da sua API no console do Google Cloud em 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.
Verifique os registros de solicitações da API na página "Visualizador de registros".
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:
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.
Aplicativo de terceiros
É possível usar um aplicativo de terceiros, como o Postman, uma extensão do navegador Chrome, para enviar a solicitação:
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.
Rastrear a atividade da API
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 a Visão geral do Portal do Cloud Endpoints.
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.
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- 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.
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2024-10-04 UTC.