Extensões OpenAPI 3.x

O Endpoints 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 Endpoints.

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

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 Endpoints 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, o pathTranslation padrão é APPEND_PATH_TO_ADDRESS. Quando x-google-backend é definido em uma operação, 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.
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. É preciso definir essa extensão para o Endpoints. É 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

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 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
target string Não Especifique o endereço IP que o host resolve.
allowCors bool Não false Permita solicitações de CORS.

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

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