Extensões OpenAPI 3.x no gateway de API

O API Gateway aceita um conjunto de extensões específicas do Google para a especificação OpenAPI que configuram os comportamentos do gateway. Com elas, é possível especificar configurações de gerenciamento de API, métodos de autenticação, limites de cota e integrações de back-end diretamente no documento OpenAPI. Entender essas extensões ajuda você a adaptar o comportamento do serviço e se integrar aos recursos do gateway de API.

Nesta página, você vai encontrar descrições das extensões específicas do Google para a especificação OpenAPI 3.x.

Os exemplos abaixo estão no formato YAML, mas o formato JSON também é aceito.

x-google-api-management

Obrigatório.

A extensão x-google-api-management define as configurações de gerenciamento de API de nível superior para seu serviço. Coloque essa extensão na raiz do documento OpenAPI.

A tabela a seguir descreve os campos para x-google-api-management:

Campo Tipo Obrigatório Padrão Descrição
metrics map[string]Metric Não Vazio Defina métricas para aplicar limites de cota.
quota map[string]Quota Não Vazio Especifique os limites de cota para seu serviço.
backends map[string]Backend Sim Vazio Configure os serviços de back-end.
apiName string Não Vazio Associe um nome às operações definidas no documento da OpenAPI.

Objeto Metric

O objeto Metric define uma métrica usada para a aplicação de cotas.

A tabela a seguir descreve os campos para Metric:

Campo Tipo Obrigatório Padrão Descrição
displayName string Não Vazio Nome de exibição da métrica.

Objeto Quota

O objeto Quota define limites de cota.

A tabela a seguir descreve os campos para Quota:

Campo Tipo Obrigatório Padrão Descrição
limits map[string]QuotaLimit Não Vazio Especifique limites de cota.

Objeto Quota Limit

O objeto QuotaLimit define um limite de cota específico.

A tabela a seguir descreve os campos para QuotaLimit:

Campo Tipo Obrigatório Descrição
metric string Sim Referencia uma métrica declarada neste documento da OpenAPI.
values int64 Sim Defina o valor máximo que a métrica pode atingir antes que as solicitações do cliente sejam negadas.

Objeto Backend

O objeto Backend configura um serviço de back-end. É necessário definir jwtAudience ou disableAuth.

A tabela a seguir descreve os campos para Backend:

Campo Tipo Obrigatório Padrão Descrição
address string Não Vazio Especifique o URL do back-end.
jwtAudience string Não Vazio Por padrão, o gateway de API cria o token de ID da instância com um público-alvo do JWT que corresponde ao campo de endereço. Especificar jwt_audience manualmente é necessário somente quando o back-end de destino usa autenticação com base no JWT, e o público esperado é diferente do valor especificado no campo de endereço. Para back-ends remotos implantados no App Engine ou com o IAP, modifique o público-alvo do JWT. O App Engine e o IAP usam o ID do cliente OAuth como público esperado.
disableAuth bool Não False Impedir que o proxy do plano de dados receba um token de ID da instância e o anexe à solicitação.
pathTranslation string Não APPEND_PATH_TO_ADDRESS ou CONSTANT_ADDRESS Defina a estratégia de conversão de caminho ao enviar solicitações de proxy para o back-end de destino. Quando x-google-backend é definido no nível superior e nenhum path_translation é especificado, o pathTranslation padrão é APPEND_PATH_TO_ADDRESS. Quando x-google-backend é definido no nível da operação e nenhum path_translation é especificado, o padrão é CONSTANT_ADDRESS.
deadline double Não 15.0 Especifique o número de segundos de espera para uma resposta completa de uma solicitação. As respostas que excederem esse prazo vão expirar.
protocol string Não http/1.1 Defina o protocolo para enviar uma solicitação ao back-end. Os valores aceitos incluem http/1.1 e h2.

x-google-auth

Opcional.

A extensão x-google-auth define configurações de autenticação em um objeto de esquema de segurança.

A tabela a seguir descreve os campos para x-google-auth:

Campo Tipo Obrigatório Padrão Descrição
issuer string Não Vazio Especifica o emissor de uma credencial. Os valores podem ser um nome de host ou um endereço de e-mail.
jwksUri string Não Vazio

Forneça o URI do conjunto de chaves públicas do provedor para validar a assinatura do JSON Web Token. O gateway de API é compatível com dois formatos de chave pública assimétrica definidos por essa extensão OpenAPI:

  1. formato de conjunto JWK. Por exemplo: jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  2. X509. Por exemplo: jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

Se você estiver usando um formato de chave simétrica, defina jwksUri como o URI de um arquivo que contenha a string de chave codificada por base64url.
audiences [string] Não Vazio Liste os públicos-alvo que o campo aud do JWT precisa corresponder durante a autenticação do JWT.
jwtLocations [JwtLocations] Não Vazio Personalize os locais do token JWT. Por padrão, um JWT é transmitido no cabeçalho Authorization (prefixado por "Bearer "), no cabeçalho X-Goog-Iap-Jwt-Assertion ou no parâmetro de consulta access_token.

Objeto JwtLocations

O objeto JwtLocations fornece locais personalizados para o token JWT.

A tabela a seguir descreve os campos para JwtLocations:

Campo Tipo Obrigatório Padrão Descrição
header | query string Sim N/A Especifique o nome do cabeçalho que contém o JWT ou o nome do parâmetro de consulta com o JWT.
valuePrefix string Não Vazio Somente para cabeçalho. Quando definido, o valor dele precisa corresponder ao prefixo do valor do cabeçalho que contém o JWT.

x-google-quota

Opcional.

A extensão x-google-quota define limites de cota. É possível definir essa extensão no nível superior do documento da OpenAPI ou para uma operação individual.

A tabela a seguir descreve os campos para x-google-quota:

Campo Tipo Obrigatório Descrição
self map[string]int64 Sim O objeto quota (self) faz referência a todas as métricas definidas nele. Nesse caso, mapeie uma métrica (como read-requests) para um valor e incremente a métrica. As solicitações são rejeitadas quando o valor da métrica atinge o limite de cota.

x-google-backend

Obrigatório.

A extensão x-google-backend faz referência a um back-end definido em x-google-api-management. É necessário definir essa extensão para o gateway de API. É possível definir essa extensão no nível superior do documento da OpenAPI ou para uma operação individual.

A tabela a seguir descreve os campos para x-google-backend:

Campo Tipo Obrigatório Descrição
self string Sim Referencie o ID de um back-end definido em x-google-api-management.

x-google-endpoint

Opcional.

A extensão x-google-endpoint é usada para configurar as propriedades de um servidor definido na matriz servers de um documento OpenAPI 3.x. Apenas uma entrada de servidor no documento OpenAPI pode usar a extensão x-google-endpoint.

A extensão também define outros recursos de back-end, incluindo:

  • CORS: é possível ativar o compartilhamento de recursos entre origens (CORS) definindo a propriedade allowCors como true.

  • Caminho base: o caminho base definido no servidor com x-google-endpoint é usado para sua API. Por exemplo, a configuração a seguir define v1 como o caminho base:

servers:
  - url: https://API_NAME.apigateway.PROJECT_ID.cloud.goog/v1
    x-google-endpoint: {}

A tabela a seguir descreve os campos para x-google-endpoint:

Campo Tipo Obrigatório Padrão Descrição
allowCors bool Não false Permita solicitações de CORS.

x-google-parameter

Opcional.

A extensão x-google-parameter é definida em um item parameter. Isso pode ser usado quando o caminho usa modelos de caminho para especificar que o comportamento de correspondência de curinga duplo deve ser usado.

A tabela a seguir descreve os campos para x-google-parameter:

Campo Tipo Obrigatório Descrição
pattern string Sim Ele precisa ser definido como **.

Entender as limitações da extensão OpenAPI

Essas extensões da OpenAPI têm limitações específicas. Para saber mais, consulte Limitações de recursos da OpenAPI 3.x.

A seguir