Primeiros passos com o Endpoints Frameworks para Python

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

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

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

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

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

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