O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Extensões OpenAPI 3.x no gateway de API

O gateway de API 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 APIs, 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.

Esta página descreve 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 da OpenAPI.

A tabela a seguir descreve os campos de 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 OpenAPI.
`ai`	`AI`	Não	Vazio	Configure recursos de inteligência artificial, incluindo o roteamento de modelos.
`mcp`	`MCP` ou `bool`	Não	Vazio	Ativar ou configurar recursos do Protocolo de Contexto de Modelo (MCP).

Objeto `Metric`

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

A tabela a seguir descreve os campos de 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 de Quota:

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

Objeto `QuotaLimit`

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

A tabela a seguir descreve os campos de 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 `Backends`

Obrigatório.

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

A tabela a seguir descreve os campos de Backends:

Campo	Tipo	Obrigatório	Padrão	Descrição
`address`	`string`	Sim	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 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 autenticação baseada em JWT e o público-alvo esperado é diferente do valor especificado no campo de endereço. Para back-ends remotos implantados no App Engine ou com IAP, é necessário substituir 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 tradução de caminhos ao fazer proxy de solicitações 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` está ativado 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 a serem aguardados por uma resposta completa de uma solicitação. As respostas que excederem esse prazo vão expirar. Em um endpoint SSE ou de transferência em partes, o prazo ainda limita a duração de todo o fluxo. Em um endpoint gRPC ou WebSocket, ele limita a lacuna entre as mensagens. Consulte Definir o prazo da transmissão para ver os tempos limite aplicáveis a cada tipo de solicitação. O prazo pode ser configurado em até 3.600 segundos. Um gateway não de streaming impõe um máximo menor de 600 segundos, rejeitando um prazo maior na criação ou atualização do gateway em vez de na criação da configuração da API.
`protocol`	`string`	Não	`http/1.1`	Defina o protocolo para enviar uma solicitação ao back-end. Os valores aceitos são `http/1.1` e `h2`. Os requisitos de protocolo dependem do tipo de streaming: - gRPC: defina o protocolo como `h2`. - WebSockets: use `http/1.1`. - Eventos enviados pelo servidor (SSE) e entrega incremental de respostas: use `http/1.1` ou `h2`. Recomendamos `h2` para melhorar o desempenho.

Objeto `AI`

O objeto AI configura recursos de inteligência artificial para seu serviço, como o roteamento de modelos.

A tabela a seguir descreve os campos de AI:

Campo	Tipo	Obrigatório	Padrão	Descrição
`models`	`Models`	Não	Vazio	Configurar integrações de modelos de IA.

Objeto `Models`

O objeto Models define configurações específicas do modelo.

A tabela a seguir descreve os campos de Models:

Campo	Tipo	Obrigatório	Padrão	Descrição
`routing`	`Routing`	Não	Vazio	Configure as configurações de roteamento de modelos.

Objeto `Routing`

O objeto Routing define regras e roteadores de roteamento de modelo.

A tabela a seguir descreve os campos de Routing:

Campo	Tipo	Obrigatório	Padrão	Descrição
`routers`	`map[string]Router`	Não	Vazio	Defina roteadores de modelo nomeados.

Objeto `Router`

O objeto Router define um roteador de modelo nomeado.

A tabela a seguir descreve os campos de Router:

Campo	Tipo	Obrigatório	Padrão	Descrição
`defaultModel`	`DefaultModel`	Sim	Vazio	O destino do modelo substituto obrigatório usado quando uma solicitação recebida não corresponde a nenhuma regra explícita.
`rules`	`[Rule]`	Não	Vazio	Lista de regras explícitas de roteamento de modelo.

Objeto `DefaultModel`

O objeto DefaultModel especifica o destino alternativo.

A tabela a seguir descreve os campos de DefaultModel:

Campo	Tipo	Obrigatório	Padrão	Descrição
`backend`	`string`	Sim	Vazio	Referencie um back-end declarado em `x-google-api-management.backends`.
`targetModel`	`string`	Sim	Vazio	Especifique o identificador do modelo de destino no formato `<provider>/<model-id>`. Para rotas compatíveis com a OpenAI, esse valor é encaminhado como o atributo `model` de saída no corpo da solicitação quando ocorre um fallback.

Objeto `Rule`

O objeto Rule define uma regra explícita de roteamento de modelo.

A tabela a seguir descreve os campos de Rule:

Campo	Tipo	Obrigatório	Padrão	Descrição
`model`	`string`	Sim	Vazio	A string recebida corresponde ao atributo `model` no payload JSON do cliente. Para rotas compatíveis com a OpenAI, essa string é encaminhada como o atributo `model` de saída no corpo da solicitação e precisa ser uma string `<provider>/<model-id>` válida.
`backend`	`string`	Sim	Vazio	Referencie um back-end declarado em `x-google-api-management.backends`.
`targetModel`	`string`	Sim	Vazio	Especifique o identificador do modelo de destino no formato `<provider>/<model-id>`. Esse valor seleciona a tradução do provedor e é repetido no campo `model` da resposta.

Objeto `MCP`

O objeto MCP configura recursos do Protocolo de Contexto de Modelo (MCP) para seu serviço. É possível definir mcp como um valor booleano ou um objeto. Defina como true para ativar o MCP globalmente em todas as operações qualificadas com as configurações padrão.

A tabela a seguir descreve os campos do objeto MCP:

Campo	Tipo	Obrigatório	Padrão	Descrição
`tools-list`	`ToolsList`	Não	Vazio	Configure as definições do método `tools/list` do MCP.

Objeto `ToolsList`

O objeto ToolsList configura as definições do método tools/list do MCP.

A tabela a seguir descreve os campos de ToolsList:

Campo	Tipo	Obrigatório	Padrão	Descrição
`security`	`map`	Não	Vazio	Ativa a autenticação no `tools/list`. Como prática recomendada de segurança, é altamente recomendável configurar essa opção. É necessário nomear exatamente um esquema de segurança de JWT ou chave de API definido em `components.securitySchemes`.

`x-google-auth`

Opcional.

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

A tabela a seguir descreve os campos de 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: formato de conjunto JWK. Por exemplo: `jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"` 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 contém a string de chave codificada em 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 para o token JWT. Por padrã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`.

Objeto `JwtLocations`

O objeto JwtLocations fornece locais personalizados para o token JWT.

A tabela a seguir descreve os campos de JwtLocations:

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

`x-google-quota`

Opcional.

A extensão x-google-quota é usada em operações individuais para especificar quais métricas definidas em x-google-api-management.metrics são afetadas por solicitações para essa operação.

x-google-quota é um objeto que contém pares de chave-valor, em que cada chave é um nome de métrica e o valor é o custo inteiro de cada solicitação para a operação. Exemplo:

x-google-api-management:
  metrics:
    read-requests:
      displayName: "Greeter requests"
    write-requests:
      displayName: "Greeter requests by name"
  quota:
    limits:
      read-requests-limit:
        metric: read-requests
        values: 1
# Set at the top-level so this applies to all operations (unless overridden)
x-google-quota:
    read-requests: 1
paths:
  /v1/projects/projectId/pets:
    get:
      # Set at the path level, so it overrides the top level quota
      x-google-quota:
          write-requests: 1

`x-google-backend`

Obrigatório.

A extensão x-google-backend faz referência a um back-end definido em x-google-api-management.backends. Quando usado, o valor precisa ser uma string que corresponda ao nome de um back-end definido em x-google-api-management.backends. É necessário definir essa extensão para o gateway de API. É possível definir essa extensão no nível superior do documento OpenAPI ou para uma operação individual para substituir o back-end de nível superior.

Exemplo:

x-google-api-management:
  backends:
    my-backend:
      address: myapp.run.app
x-google-backend: my-backend

`x-google-model-router`

Opcional.

A extensão x-google-model-router faz referência a um roteador de modelo definido em x-google-api-management.ai.models.routing.routers. Quando usado, o valor precisa ser uma string que corresponda ao nome de um roteador definido em x-google-api-management.ai.models.routing.routers.

Essa extensão é compatível apenas com especificações OpenAPI 3.x e não pode ser usada com especificações OpenAPI 2.0 (Swagger). É possível definir essa extensão apenas no nível da operação individual para operações que usam o método HTTP POST. Não é possível especificar x-google-model-router e x-google-backend na mesma operação, nem misturar operações de roteamento de modelo e sem modelo em diferentes caminhos na mesma especificação de API. Além disso, não é possível usar o roteamento de modelo com o Protocolo de Contexto de Modelo (MCP). Ativar x-google-api-management.mcp torna essa extensão indisponível.

Exemplo:

x-google-api-management:
  backends:
    gemini-backend:
      address: https://aiplatform.googleapis.com/v1/...
  ai:
    models:
      routing:
        routers:
          my-router:
            defaultModel:
              backend: gemini-backend
              targetModel: google/gemini-3.5-flash-lite
paths:
  /v1/chat:
    post:
      x-google-model-router: my-router

`x-google-mcp-tool`

Opcional.

A extensão x-google-mcp-tool é usada em operações individuais para expô-las como ferramentas do MCP e, opcionalmente, substituir o nome e a descrição gerados da ferramenta.

Essa extensão é compatível apenas com especificações OpenAPI 3.x e não pode ser usada com especificações OpenAPI 2.0 (Swagger). Essa extensão só pode ser definida no nível da operação individual.

Aceita um booleano ou um objeto.

Formulário booleano: defina como true para ativar essa operação. Defina como false para desativar, substituindo uma ativação global.
Formulário de objeto: ative e substitua as configurações da ferramenta gerada.

A tabela a seguir descreve os campos de x-google-mcp-tool quando usado como um objeto:

Campo	Tipo	Obrigatório	Padrão	Descrição
`name`	`string`	Não	O `operationId` da operação	O nome da ferramenta do MCP. Precisa corresponder a `[A-Za-z0-9_.-]{1,128}` e ser exclusivo em toda a especificação.
`description`	`string`	Não	A descrição da operação, voltando ao resumo	A descrição da ferramenta MCP. Esse é o principal indicador que um LLM usa para selecionar ferramentas.

Exemplo:

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

`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 de base:

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

A tabela a seguir descreve os campos de 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 criação de modelos de caminho para especificar que o comportamento de correspondência de curinga duplo deve ser usado.

A tabela a seguir descreve os campos de 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 do OpenAPI 3.x.

A seguir

Confira a especificação OpenAPI.
Modifique um gateway para usar a OpenAPI 3.0.

Extensões OpenAPI 3.x no gateway de API

x-google-api-management

Objeto Metric

Objeto Quota

Objeto QuotaLimit

Objeto Backends

Objeto AI

Objeto Models

Objeto Routing

Objeto Router

Objeto DefaultModel

Objeto Rule

Objeto MCP

Objeto ToolsList

x-google-auth

Objeto JwtLocations

x-google-quota

x-google-backend

x-google-model-router

x-google-mcp-tool

x-google-endpoint

x-google-parameter

Entender as limitações da extensão OpenAPI

A seguir

`x-google-api-management`

Objeto `Metric`

Objeto `Quota`

Objeto `QuotaLimit`

Objeto `Backends`

Objeto `AI`

Objeto `Models`

Objeto `Routing`

Objeto `Router`

Objeto `DefaultModel`

Objeto `Rule`

Objeto `MCP`

Objeto `ToolsList`

`x-google-auth`

Objeto `JwtLocations`

`x-google-quota`

`x-google-backend`

`x-google-model-router`

`x-google-mcp-tool`

`x-google-endpoint`

`x-google-parameter`