Como criar uma configuração de API
Pré-requisitos
Antes de criar uma configuração de API, verifique se você tem:
Prepare seu ambiente de desenvolvimento conforme descrito em Como configurar seu ambiente de desenvolvimento.
criou uma definição de API como uma especificação OpenAPI;
Se preferir, crie uma API, conforme descrito em Como criar uma API. Se a API ainda não existe, a criação dela é criada.
Requisitos do ID de configuração da API
Muitos dos comandos gcloud mostrados abaixo exigem que você especifique o ID de configuração da API, no formato: CONFIG_ID.
A API Gateway aplica os seguintes requisitos ao ID de configuração da API:
- Os valores têm comprimento máximo de 63 caracteres.
- Use somente letras minúsculas, números ou hifens
- Não pode começar com um traço.
- Não pode conter um sublinhado.
Como criar uma configuração de API
Use a Google Cloud CLI para fazer upload da definição da API e criar uma configuração. Ao fazer o upload da definição da API, é necessário especificar o nome dela. Se a API ainda não existir no gateway de API, esse comando também a criará.
Para criar uma configuração de API:
Mude o diretório para o diretório que contém a definição da API.
Para mais informações sobre como criar a especificação OpenAPI para sua definição, consulte a Visão geral da OpenAPI e o Guia de início rápido: implantar uma API no gateway de API.
Para mais informações sobre como criar uma definição e uma configuração do serviço gRPC para a definição da API, consulte Como configurar um serviço gRPC e Primeiros passos com o gateway de API e o Cloud Run para gRPC.
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 PROJECT_ID pelo ID do projeto do Google Cloud em que você quer criar o serviço:
gcloud config set project PROJECT_ID
Veja a ajuda do comando
api-configs create:gcloud api-gateway api-configs create --help
Execute este comando para criar a configuração de API:
gcloud api-gateway api-configs create CONFIG_ID \ --api=API_ID --openapi-spec=API_DEFINITION \ --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
onde:
- CONFIG_ID especifica o ID da nova configuração da API.
- API_ID especifica o ID da API Gateway associado à configuração da API. Se a API ainda não existir, este comando a criará.
- API_DEFINITION especifica o nome da especificação OpenAPI que contém a definição da API.
- PROJECT_ID especifica o ID do projeto do Google Cloud.
- SERVICE_ACCOUNT_EMAIL especifica a conta de serviço usada para assinar tokens de back-ends com autenticação configurada. Para mais informações, consulte Como configurar uma conta de serviço.
Durante a criação da API e da configuração da API, o gateway de API gera informações para o terminal. Essa operação pode levar vários minutos para ser concluída conforme a configuração da API é propagada para os sistemas downstream. A criação de uma configuração de API complexa pode levar até dez minutos para ser concluída. Enquanto uma configuração estiver sendo criada, não tente criar outra configuração para a mesma API. Somente uma configuração pode ser criada por vez para qualquer API.
Após a conclusão, o comando a seguir pode ser usado para ver detalhes sobre a nova configuração da API:
gcloud api-gateway api-configs describe CONFIG_ID \ --api=API_ID --project=PROJECT_ID
Este comando mostra o seguinte:
createTime: '2020-02-04T18:33:11.882707149Z' displayName: CONFIG_ID gatewayConfig: backendConfig: googleServiceAccount: 1111111@developer.gserviceaccount.com labels: '' name: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID serviceRollout: rolloutId: 2020-02-04r2 state: ACTIVE updateTime: '2020-02-04T18:33:12.219323647Z'Ative a API usando o nome de serviço gerenciado da API. Esse valor está na coluna "Serviço gerenciado" da API na página de destino das APIs:
gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
Você só precisa executar esse comando uma vez ao criar a API. Se você modificar a API posteriormente, não precisará executar o comando novamente.
A CLI do Google Cloud tem muitas opções, incluindo as descritas Referência do gcloud. Além disso, para o gateway de API, é possível definir as seguintes opções ao criar uma configuração de API:
--async: retorna o controle para o terminal imediatamente, sem aguardar a conclusão da operação.--display-name=NAME: especifica o nome de exibição da configuração da API, o que significa o nome mostrado na IU. Não use espaços no nome. Use hifens e sublinhados. O valor padrão é CONFIG_ID.--labels=KEY1=VALUE1,KEY2=VALUE2,...: especifica rótulos associados à configuração da API.
Exemplo:
gcloud api-gateway api-configs create CONFIG_ID \ --api=API_ID --openapi-spec=API_DEFINITION \ --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL \ --async --display-name=MyConfig --labels=a=1,b=2
É possível ver os rótulos na saída do comando describe mostrado acima ou no comando list, incluindo a opção --format:
gcloud api-gateway api-configs list \ --api=API_ID --project=PROJECT_ID --format="table(name, labels)"
Como listar configurações da API
Para listar configurações da API para um projeto específico:
gcloud api-gateway api-configs list --project=PROJECT_ID
Este comando mostra o seguinte:
NAME DISPLAY_NAME ROLLOUT_ID STATE CREATE_TIME projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID CONFIG_ID 2020-02-04r0 ACTIVE 2020-02-04T16:18:02.369859863Z
Para listar configurações de uma API específica em um projeto:
gcloud api-gateway api-configs list --api=API_ID --project=PROJECT_ID
Use o projeto, a API e os IDs de configuração para ver informações detalhadas sobre a configuração.
gcloud api-gateway api-configs describe CONFIG_ID \ --api=API_ID --project=PROJECT_ID
Como atualizar uma configuração de API
Você não pode modificar uma configuração de API existente além de atualizar os rótulos e o nome de exibição.
Use o seguinte gcloud para atualizar uma configuração de API existente:
--display-name--update-labels--clear-labels--remove-labels
Exemplo:
gcloud api-gateway api-configs update CONFIG_ID \ --api=API_ID --project=PROJECT_ID \ --update-labels=a=1,b=2
Use o seguinte comando para ver todas as opções de atualização:
gcloud api-gateway api-configs update --help
Como excluir uma configuração de API
Use o seguinte comando gcloud para excluir uma configuração de API atual:
gcloud api-gateway api-configs delete CONFIG_ID --api=API_ID --project=PROJECT_ID