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 da 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 essas extensões, é 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 da OpenAPI. Entender essas extensões ajuda a personalizar o comportamento do serviço e integrar com os recursos do gateway de API.

Nesta página, descrevemos as extensões específicas do Google para a especificação OpenAPI 3.x.

Embora os exemplos fornecidos estejam no formato YAML, o JSON também é aceito.

`x-google-api-management`

Obrigatório.

A extensão x-google-api-management define as configurações de gerenciamento de APIs 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	Configurar serviços de back-end.
`apiName`	`string`	Não	Vazio	Associe um nome às operações definidas no documento da OpenAPI.
`ai`	`AI`	Não	Vazio	Configurar 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 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	Referencie 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. É preciso 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 o 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 de 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 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` é 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 para aguardar uma resposta completa de uma solicitação. As respostas que excedem esse prazo expiram. Em um endpoint de SSE ou de transferência em blocos, o prazo ainda limita a duração de todo o stream. Em um endpoint de gRPC ou WebSocket, ele limita o intervalo entre as mensagens. Consulte Definir o prazo do stream para ver os tempos limite que se aplicam a cada tipo de solicitação. Omita o campo ou defina-o como `0` para usar o padrão. Um valor negativo é rejeitado. O prazo é configurável até 3.600 segundos. Um gateway que não é de streaming aplica 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 compatíveis incluem `http/1.1` e `h2`. Os requisitos de protocolo dependem do tipo de streaming: - gRPC: é necessário definir o protocolo como `h2`. - WebSockets: é necessário usar `http/1.1`. - Eventos enviados pelo servidor (SSE) e entrega de resposta incremental: é possível usar `http/1.1` ou `h2`. Recomendamos o `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	Defina as configurações de roteamento de modelos.

Objeto `Routing`

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

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 roteamento de modelos nomeados.

Objeto `Router`

O objeto Router define um roteador de modelos 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 modelos.

Objeto `DefaultModel`

O objeto DefaultModel especifica o destino de fallback.

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 o fallback.

Objeto `Rule`

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

A tabela a seguir descreve os campos de Rule:

Campo	Tipo	Obrigatório	Padrão	Descrição
`model`	`string`	Sim	Vazio	A string de entrada que 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 os 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	Defina as configurações do método MCP `tools/list`.

Objeto `ToolsList`

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

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. Precisa 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	Especifique 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	Informe 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 esta extensão da 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 do 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 que contém o JWT ou o nome 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. É preciso 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 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 modelos 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 as especificações OpenAPI 3.x. Ela não pode ser usada com as 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 modelos e não modelos em caminhos diferentes na mesma especificação de API. Além disso, não é possível usar o roteamento de modelos em conjunto 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, se quiser, substituir o nome e a descrição gerados para a ferramenta.

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 de ferramenta geradas.

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. Somente uma entrada de servidor no documento da 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 de x-google-endpoint:

Campo	Tipo	Obrigatório	Padrão	Descrição
`allowCors`	`bool`	Não	`false`	Permitir 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 caracteres 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 da OpenAPI 3.x.

A seguir

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

Extensões da 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`