Como implantar a configuração do Endpoints

OpenAPI | gRPC

Depois de configurar o Cloud Endpoints em um documento da OpenAPI, é preciso implantá-lo para que ele forneça as informações necessárias no gerenciamento da API. Para implantar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Esse comando usa a Service Infrastructure, a plataforma de serviços fundamentais do Google. Ela é usada pelo Endpoints e por outros serviços para criar e gerenciar APIs e serviços. Nesta página, descrevemos como implantar um documento do OpenAPI no Endpoints.

Pré-requisitos

Como ponto de partida, nesta página presume-se que você:

criou um projeto do Google Cloud Platform em que você tem o papel Editor ou Proprietário. Após a implantação inicial, conceda o papel mais restritivo Editor de configuração do serviço a um usuário, grupo ou conta de serviço. Consulte Como conceder e revogar o acesso à API para mais informações;
Configurar o Endpoints.
se estiver usando um nome de domínio personalizado, como my-api.example.com, verificou o nome de domínio antes de implantar o documento da OpenAPI.

Como preparar a Google Cloud CLI para implantação

Use a ferramenta de linha de comando gcloud para implantar a configuração. Consulte a Referência da gcloud para mais informações sobre os comandos.

Para se preparar para a implantação:

Instale e inicialize a gcloud CLI.
Atualize a gcloud CLI:
```
gcloud components update
```
Verifique se a CLI gcloud está autorizada a acessar seus dados e serviços:
```
gcloud auth login
```
Uma nova guia do navegador será aberta e você precisará escolher uma conta.
Defina o projeto padrão. Substitua [YOUR-PROJECT-ID] pelo ID do projeto do GCP.
```
gcloud config set project [YOUR-PROJECT-ID]
```
Se você estiver implantando o back-end da API para o Kubernetes ou Kubernetes Engine, execute o comando a seguir para receber novas credenciais de usuário para o Application Default Credentials. As credenciais de usuário são necessárias para autorizar kubectl.
```
gcloud auth application-default login
```
Uma nova guia do navegador será aberta e você precisará escolher uma conta.

Como validar a sintaxe `openapi.json`

O arquivo do documento da OpenAPI pode estar no formato YAML ou JSON. Se estiver em JSON, recomendamos que a sintaxe seja confirmada antes da implantação do arquivo. Para verificar se o openapi.json é um arquivo JSON bem formatado, é possível abri-lo em um editor de texto de validação de JSON, como vim, usar um serviço de linter JSON on-line ou usar Python, por exemplo:

python -m json.tool openapi.json

Para melhorar a legibilidade, é possível formatar o estilo do arquivo JSON:

python -m json.tool input.json > output.json

Substitua input.json pelo caminho do seu arquivo openapi.json. output.json é o arquivo JSON bem impresso.

Como validar o documento do OpenAPI

Nem todas as criações do OpenAPI são compatíveis atualmente com o Cloud Endpoints. Antes da implantação, valide o documento do OpenAPI.

Para isso:

Altere o diretório para o local que contém o documento do OpenAPI.
Confirme o projeto do Google Cloud em que você quer criar o serviço. Se você estiver usando um nome de domínio personalizado, como myapi.example.com, valide o ID do projeto retornado do comando a seguir para que o serviço não seja criado no projeto errado.
```
gcloud config list project
```
Se precisar alterar o projeto padrão, execute o seguinte comando e substitua [YOUR_PROJECT_ID] pelo ID do projeto do Google Cloud em que você quer criar o serviço:
```
gcloud config set project [YOUR_PROJECT_ID]
```
Execute o seguinte comando e substitua [YOUR_OPENAPI_DOCUMENT] pelo nome do documento do OpenAPI que descreve a API:
```
gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT] --validate-only
```

Em seguida, o comando gcloud chama a API Service Management para criar um serviço gerenciado com o nome especificado no campo host no documento da OpenAPI. Quando você especifica a sinalização --validate-only, um serviço ainda é criado, mas a configuração não é implantada. Não há como validar o documento da OpenAPI sem criar um serviço. É possível excluir o serviço, mas o Service Management impede a criação de um com o mesmo nome por aproximadamente 30 dias.

Como implantar o documento da OpenAPI

Quando estiver tudo pronto para implantar a API, execute a Google Cloud CLI, que usa o Service Management para fazer o upload da configuração da API e criar (ou atualizar) um serviço gerenciado.

Para implantar o documento da OpenAPI:

Altere o diretório para o local que contém o documento do OpenAPI.
Valide o código do projeto retornado do seguinte comando para garantir que o serviço não seja criado no projeto incorreto.
```
gcloud config list project
```
Se você precisar alterar o projeto padrão, execute o seguinte comando e substitua [YOUR_PROJECT_ID] pelo ID do projeto do Google Cloud em que você quer criar o serviço:
```
gcloud config set project [YOUR_PROJECT_ID]
```
Execute o seguinte comando e substitua [YOUR_OPENAPI_DOCUMENT] pelo nome do documento do OpenAPI que descreve a API:
```
gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT]
```

Na primeira vez que você executa o comando anterior, o Service Management cria um novo serviço do Endpoints no projeto padrão com um nome que corresponde ao texto especificado no campo host no documento da OpenAPI e envia a configuração do serviço.

Durante a criação e a configuração do serviço, o Service Management envia informações ao terminal. Após a conclusão, uma linha semelhante a esta é exibida com o ID da configuração e o nome do serviço:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

No exemplo anterior, 2017-02-13r0 é o ID de configuração do serviço e echo-api.endpoints.example-project-12345.cloud.goog é o nome do serviço.

Após a implantação bem-sucedida, é possível ver a API na página Endpoints > Serviços no console do Google Cloud.

Se você receber uma mensagem de erro, consulte Como solucionar problemas de implantação na configuração do Endpoints.

Como fazer a reimplantação

Sempre que você fizer mudanças no documento da OpenAPI, implante-o novamente para que a versão mais recente da configuração da API esteja disponível para o Endpoints. Não é necessário reimplantar ou reiniciar o ESP se você já tiver implementado o ESP com a opção rollout definida como managed. Essa opção configura o ESP para usar a implantação mais recente da configuração do serviço. Quando você especifica essa opção, até 5 minutos depois de implantar uma nova configuração de serviço, o ESP detecta a alteração e começa a usá-la automaticamente. Recomendamos especificar essa opção em vez de um ID de configuração específico para uso do ESP.

Após a implantação inicial da configuração do Endpoints, é possível conceder a um usuário, conta de serviço ou grupo um papel que permita a reimplantação da configuração do Endpoints. Consulte Como conceder e revogar o acesso à API para mais informações.