Extensões OpenAPI 3.x no API Gateway

O API Gateway aceita um conjunto de extensões específicas da Google à especificação OpenAPI que configuram os comportamentos da gateway. Estas extensões permitem-lhe especificar definições de gestão de APIs, métodos de autenticação, limites de quotas e integrações de back-end diretamente no seu documento OpenAPI. A compreensão destas extensões ajuda a personalizar o comportamento do seu serviço e a integrar-se com as funcionalidades do API Gateway.

Esta página descreve as extensões específicas da Google à especificação OpenAPI 3.x.

Embora os exemplos apresentados estejam no formato YAML, o formato JSON também é suportado.

x-google-api-management

Obrigatório.

A extensão x-google-api-management define as definições de gestão de APIs de nível superior para o seu serviço. Coloque esta extensão na raiz do seu documento OpenAPI.

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

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

Metric Objeto

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

A tabela seguinte descreve os campos para Metric:

Campo Tipo Obrigatória Predefinição Descrição
displayName string Não Vazio Nome a apresentar da métrica.

Quota Objeto

O objeto Quota define os limites de quota.

A tabela seguinte descreve os campos para Quota:

Campo Tipo Obrigatória Predefinição Descrição
limits map[string]QuotaLimit Não Vazio Especifique limites de quotas.

Quota Limit Objeto

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

A tabela seguinte descreve os campos para QuotaLimit:

Campo Tipo Obrigatória Descrição
metric string Sim Referencie uma métrica declarada neste documento OpenAPI.
values int64 Sim Defina o valor máximo que a métrica pode atingir antes de os pedidos do cliente serem recusados.

Backend Objeto

O objeto Backend configura um serviço de back-end. Tem de definir jwtAudience ou disableAuth.

A tabela seguinte descreve os campos para Backend:

Campo Tipo Obrigatória Predefinição Descrição
address string Não Vazio Especifique o URL do back-end.
jwtAudience string Não Vazio Por predefinição, o API Gateway cria o token de ID da instância com um público-alvo JWT que corresponde ao campo de endereço. A especificação manual de jwt_audience só é necessária quando o back-end de destino usa a autenticação baseada em JWT e o público-alvo esperado é diferente do valor especificado no campo de endereço. Para back-ends remotos implementados no App Engine ou com a IAP, tem de substituir o público-alvo do JWT. O App Engine e o IAP usam o respetivo ID de cliente OAuth como público-alvo esperado.
disableAuth bool Não False Impedir que o proxy do plano de dados obtenha um token de ID da instância e o anexe ao pedido.
pathTranslation string Não APPEND_PATH_TO_ADDRESS ou CONSTANT_ADDRESS Defina a estratégia de tradução de caminhos quando usar um proxy para pedidos para o back-end de destino. Quando x-google-backend é definido ao nível superior e não é especificado nenhum path_translation, o pathTranslation predefinido é APPEND_PATH_TO_ADDRESS. Quando x-google-backend está definido ao nível da operação e não é especificado nenhum path_translation, a predefinição é CONSTANT_ADDRESS.
deadline double Não 15.0 Especifique o número de segundos a aguardar por uma resposta completa de um pedido. As respostas que excederem este prazo vão expirar.
protocol string Não http/1.1 Defina o protocolo para enviar um pedido para o back-end. Os valores suportados incluem http/1.1 e h2.

x-google-auth

Opcional.

A extensão x-google-auth define as definições de autenticação num objeto SecurityScheme.

A tabela seguinte descreve os campos para x-google-auth:

Campo Tipo Obrigatória Predefinição Descrição
issuer string Não Vazio Especifique o emissor de uma credencial. Os valores podem ser um nome de anfitrião ou um endereço de email.
jwksUri string Não Vazio

Faculte o URI do conjunto de chaves públicas do fornecedor para validar a assinatura do símbolo da Web JSON. O API Gateway suporta dois formatos de chave pública assimétricos definidos por esta extensão OpenAPI:

  1. Formato do 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 estiver a usar um formato de chave simétrica, defina o jwksUri para o URI de um ficheiro que contenha a string da chave codificada em base64url.
audiences [string] Não Vazio Liste os públicos-alvo com os quais o campo aud do JWT tem de corresponder durante a autenticação JWT.
jwtLocations [JwtLocations] Não Vazio Personalize as localizações para o token JWT. Por predefinição, um JWT é transmitido no cabeçalho Authorization (com o prefixo "Bearer "), no cabeçalho X-Goog-Iap-Jwt-Assertion ou no parâmetro de consulta access_token.

JwtLocations Objeto

O objeto JwtLocations fornece localizações personalizadas para o token JWT.

A tabela seguinte descreve os campos para JwtLocations:

Campo Tipo Obrigatória Predefiniçã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 que contém o JWT.
valuePrefix string Não Vazio Apenas para o cabeçalho. Quando definido, o valor tem de 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 quota. Pode definir esta extensão no nível superior do seu documento OpenAPI ou para uma operação individual.

A tabela seguinte descreve os campos para x-google-quota:

Campo Tipo Obrigatória Descrição
self map[string]int64 Sim O objeto quota (self) faz referência a quaisquer métricas definidas no objeto. Neste caso, mapeie uma métrica (como read-requests) para um valor de forma a incrementá-la. Os pedidos são rejeitados quando o valor da métrica atinge o limite da quota.

x-google-backend

Obrigatório.

A extensão x-google-backend faz referência a um back-end definido em x-google-api-management. Tem de definir esta extensão para o API Gateway. Pode definir esta extensão no nível superior do seu documento OpenAPI ou para uma operação individual.

A tabela seguinte descreve os campos para x-google-backend:

Campo Tipo Obrigatória 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 seu documento OpenAPI pode usar a extensão x-google-endpoint.

A extensão também define outras funcionalidades de back-end, incluindo:

  • CORS: pode ativar a partilha de recursos de origem cruzada (CORS) definindo a propriedade allowCors como true.

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

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

A tabela seguinte descreve os campos para x-google-endpoint:

Campo Tipo Obrigatória Predefinição Descrição
allowCors bool Não false Permitir pedidos CORS.

x-google-parameter

Opcional.

A extensão x-google-parameter está definida num item parameter. Isto pode ser usado quando o caminho usa modelos de caminhos para especificar que deve ser usado o comportamento de correspondência de carateres universais duplos.

A tabela seguinte descreve os campos para x-google-parameter:

Campo Tipo Obrigatória Descrição
pattern string Sim Tem de ser definido como **.

Compreenda as limitações das extensões da OpenAPI

Estas extensões da OpenAPI têm limitações específicas. Para saber mais, consulte o artigo Limitações das funcionalidades da OpenAPI 3.x.

O que se segue?