Extensões OpenAPI 3.x

Os pontos finais aceitam 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. Compreender estas extensões ajuda a personalizar o comportamento do serviço e a integrar-se com as funcionalidades dos Endpoints.

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 Não Vazio Configure serviços de back-end.
apiName string Não Vazio Associar um nome às operações definidas no documento OpenAPI.
allowCors bool Não False Encaminhar todos os pedidos CORS (OPTIONS) para o back-end.

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, os Endpoints criam 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 está definido ao nível superior, o valor predefinido de pathTranslation é APPEND_PATH_TO_ADDRESS. Quando x-google-backend é definido numa operação, 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.
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 os pontos finais. 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

Obrigatório.

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
target string Não Especifique o endereço IP para o qual o anfitrião é resolvido.
allowCors bool Não false Permitir pedidos CORS.

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?

  • Explore a especificação OpenAPI.
  • Reveja a documentação dos Endpoints para configurações específicas dos Endpoints ou do ESPv2.