Como criar uma configuração de API

Pré-requisitos

Antes de criar uma configuração de API, verifique se você tem:

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

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

  2. 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
  3. Veja a ajuda do comando api-configs create:

    gcloud api-gateway api-configs create --help
  4. 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.

  5. 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'
  6. 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 Google Cloud CLI tem muitas opções, incluindo as descritas na Referência da 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

A seguir