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;
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 gcloud CLI 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
. Uma nova guia do navegador será aberta e você precisará escolher uma conta.gcloud auth application-default login
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 upload da configuração da API e para 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, é possível exibir a API na 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
.
O ESP é configurado 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.
A seguir
- Primeiros passos no uso do Portal do Cloud Endpoints
- Implantar o back-end da API
- Como implantar no Kubernetes
- Como executar o ESP localmente ou em outra plataforma
- Como conseguir o nome e o ID de configuração do serviço