View a markdown version of this page

Destinos do esquema OpenAPI - Amazon Bedrock AgentCore
Principais considerações e limitaçõesEstratégia de autorizaçãoEspecificação do esquema OpenAPI

Destinos do esquema OpenAPI

O OpenAPI (anteriormente conhecido como Swagger) é um padrão amplamente usado para descrever APIs RESTful. O Gateway oferece suporte às especificações do OpenAPI 3.0 para definir destinos de API.

Os destinos da OpenAPI conectam seu gateway às APIs REST definidas usando as especificações da OpenAPI. O Gateway converte as solicitações MCP recebidas em solicitações HTTP para essas APIs e manipula a formatação da resposta.

Analise as principais considerações e limitações, incluindo o suporte a recursos, para ajudá-lo a decidir se um alvo da OpenAPI é aplicável ao seu caso de uso. Se estiver, você pode criar um esquema que siga as especificações e, em seguida, configurar permissões para que o gateway possa acessar o destino. Escolha um tópico para saber mais:

Principais considerações e limitações

Importante

A especificação da OpenAPI deve incluir operationId campos para todas as operações que você deseja expor como ferramentas. O OperationID é usado como o nome da ferramenta na interface MCP.

Ao usar alvos da OpenAPI, tenha em mente os seguintes requisitos e limitações:

  • As versões 3.0 e 3.1 da OpenAPI são suportadas (o Swagger 2.0 não é suportado)

  • O arquivo OpenAPI deve estar livre de erros semânticos

  • O atributo do servidor precisa ter uma URL válida do endpoint real

  • Somente application/json o tipo de conteúdo é totalmente suportado

  • Recursos de esquema complexos, como OneOf, AnyOf e AllOf, não são suportados

  • Não há suporte para serializadores de parâmetros de caminho e serializadores de parâmetros para parâmetros de consulta, cabeçalho e cookie

  • Cada LLM terá ToolSpec restrições. Se a OpenAPI tiver APIs/properties/object nomes não compatíveis com os respectivos LLMs downstream, o plano de dados falhará. ToolSpec Os erros comuns são o nome da propriedade que excede o tamanho permitido ou o nome que contém caracteres não suportados.

Para obter melhores resultados com os alvos da OpenAPI:

  • Sempre inclua OperationID em todas as operações

  • Use estruturas de parâmetros simples em vez de serialização complexa

  • Implemente autenticação e autorização fora da especificação

  • Use somente os tipos de mídia compatíveis para obter a máxima compatibilidade

Práticas recomendadas de segurança para parâmetros de URL

Atenção

Ao definir URLs de servidor em suas especificações da OpenAPI, evite usar padrões de parâmetros de URL excessivamente permissivos que possam expor seu gateway a riscos de segurança.

Os parâmetros de URL nas definições do servidor OpenAPI permitem a configuração dinâmica do endpoint. No entanto, certos padrões podem introduzir vulnerabilidades de segurança se não forem adequadamente restringidos. Especificamente, evite usar padrões de domínio totalmente dinâmicos, como:

  • https://{yourDomain}/- Permite a substituição arbitrária de domínios

  • https://{subdomain}.{env}.{domain}.com- Vários espaços reservados sem restrições

  • https://{host}/api/- Parâmetro de host irrestrito

Esses padrões podem ser potencialmente explorados para:

  • Redirecione solicitações para endpoints não intencionais ou maliciosos

  • Acesse recursos de rede internos (falsificação de Server-Side solicitação)

  • Exfiltre credenciais ou dados confidenciais

Práticas recomendadas:

  • Use URLs estáticos totalmente qualificados sempre que possível: https://api.example.com/v1

  • Limite os parâmetros aos subdomínios em seu domínio controlado e implemente a validação em seu aplicativo

  • Evite usar parâmetros que permitam a substituição arbitrária de domínio ou host

  • Implemente validação adicional em sua API para verificar se os valores dos parâmetros de tempo de execução correspondem aos padrões esperados

AgentCore O gateway valida automaticamente os parâmetros da região e bloqueia solicitações para intervalos de IP privados.

Exemplo de uma configuração segura de URL de servidor:

{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}

Se forem necessários parâmetros dinâmicos, use domínios totalmente qualificados com espaços reservados mínimos e restrições de enumeração:

{
  "servers": [
    {
      "url": "https://{tenant}.api.example.com/v1",
      "variables": {
        "tenant": {
          "default": "default-tenant",
          "description": "Customer tenant identifier",
          "enum": ["tenant1", "tenant2", "tenant3"]
        }
      }
    }
  ]
}

Essa abordagem restringe os parâmetros de URL a subdomínios específicos dentro do seu domínio controlado, mantendo a flexibilidade para implantações multilocatárias. O uso de restrições de enumeração evita valores arbitrários e ajuda a proteger contra ataques de SSRF, limitando os parâmetros a valores predefinidos e seguros. Além disso, sempre valide os valores do inquilino na lógica do seu aplicativo.

Ao considerar o uso de destinos do esquema OpenAPI com o AgentCore Gateway, revise a tabela de suporte de recursos a seguir.

Suporte ao recurso OpenAPI

A tabela a seguir descreve os recursos da OpenAPI que são suportados e não suportados pelo Gateway:

Recursos compatíveis Recursos sem suporte

Definições de esquema Tipos de dados básicos (string, número, inteiro, booleano, matriz, objeto) Validação de campo obrigatória Estruturas de objetos aninhados Definições de matriz com especificações de itens

Composição do esquema Uma das especificações Qualquer uma das especificações Todas as especificações

Métodos HTTP Métodos HTTP padrão (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)

Esquemas de segurança Esquemas de segurança no nível de especificação da OpenAPI (a autenticação deve ser configurada usando a configuração de autorização de saída do Gateway)

Tipos de mídia application/json application/xml multipart/form -data -www-form-urlencoded application/x

Tipos de mídia Tipos de mídia personalizados além da lista suportada Tipos de mídia binária

Parâmetros de caminho Definições simples de parâmetros de caminho (exemplo: /users/ {userId})

Serialização de parâmetros Serializadores de parâmetros de caminho complexo (exemplo:/users { ;id\*} { ?metadata}) Matrizes de parâmetros de consulta com serialização complexa Serializadores de parâmetros de cabeçalho Serializadores de parâmetros de cookie

Parâmetros de consulta Definições básicas de parâmetros de consulta Tipos simples de string, número e booleano

Retornos de chamada e webhooks Operações de retorno de chamada Definições de webhook

Request/Response Corpos de solicitação e resposta JSON Corpos de solicitação e resposta XML Códigos de status HTTP padrão (200, 201, 400, 404, 500, etc.)

Links Links entre operações

Estratégia de autorização

Os seguintes tipos de autorização de saída são compatíveis com destinos da OpenAPI:

  • Sem autorização — O gateway invoca o alvo da OpenAPI sem autorização pré-configurada. Essa abordagem não é recomendada.

  • OAuth — O gateway suporta tanto o OAuth de duas pernas (tipo de concessão de credenciais do cliente) quanto o OAuth de três pernas (tipo de concessão de código de autorização). Você configura o provedor de autorização no Amazon Bedrock AgentCore Identity na mesma conta e região do gateway.

  • Chave de API — O gateway usa um provedor de credenciais de chave de API para se autenticar com o destino da OpenAPI. Você configura o provedor de chave de API no Amazon Bedrock AgentCore Identity na mesma conta e região do gateway.

  • IAM (AWS Signature Version 4 (Sig V4)) — O gateway assina solicitações para o destino da OpenAPI usando SigV4 com as credenciais da função de serviço do gateway. Você configura um IamCredentialProvider com um nome de serviço obrigatório para assinatura SigV4 e uma região opcional (o padrão é a região do gateway).

Importante

A autorização de saída do IAM (SigV4) exige que o destino da OpenAPI seja hospedado por trás de um AWS serviço que ofereça suporte nativo à autenticação do IAM. O gateway assina solicitações de saída com SigV4, mas não modifica a configuração de autenticação no destino. O serviço de destino deve ser capaz de verificar as assinaturas SigV4.

Os AWS serviços a seguir oferecem suporte nativo à autenticação do IAM e são compatíveis com a autorização de saída do IAM para destinos da OpenAPI:

  • Amazon API Gateway

  • URLs da função Lambda

  • Amazon Bedrock AgentCore Gateway

Serviços que não verificam nativamente as assinaturas SigV4, como o Application Load Balancer ou endpoints diretos do Amazon EC2, não são compatíveis com a autorização de saída do IAM. Se seu alvo da OpenAPI estiver hospedado por trás de um desses serviços, use OAuth ou autorização de chave de API em vez disso.

Para obter mais informações sobre como configurar a autorização de saída, consulte Configurar a autorização de saída para seu gateway.

Especificação do esquema OpenAPI

A especificação OpenAPI define a API REST que seu Gateway vai expor. Consulte os seguintes recursos ao configurar sua especificação OpenAPI:

Depois de definir seu esquema OpenAPI, você pode fazer o seguinte:

  • Faça o upload para um bucket do Amazon S3 e consulte a localização do S3 ao adicionar o destino ao seu gateway.

  • Cole a definição em linha ao adicionar o destino ao seu gateway.

Expanda uma seção para ver exemplos de especificações OpenAPI suportadas e não suportadas:

A seguir, mostra um exemplo de uma especificação OpenAPI compatível

Exemplo de uma especificação OpenAPI compatível:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Weather API",
    "version": "1.0.0",
    "description": "API for retrieving weather information"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "paths": {
    "/weather": {
      "get": {
        "summary": "Get current weather",
        "description": "Returns current weather information for a location",
        "operationId": "getCurrentWeather",
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "description": "City name or coordinates",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "units",
            "in": "query",
            "description": "Units of measurement (metric or imperial)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["metric", "imperial"],
              "default": "metric"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "location": {
                      "type": "string"
                    },
                    "temperature": {
                      "type": "number"
                    },
                    "conditions": {
                      "type": "string"
                    },
                    "humidity": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "404": {
            "description": "Location not found"
          }
        }
      }
    }
  }
}

A seguir, mostra outro exemplo de uma especificação OpenAPI compatível.

{
  "openapi": "3.0.0",
  "info": {
    "title": "Search API",
    "version": "1.0.0",
    "description": "API for searching content"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "paths": {
    "/search": {
      "get": {
        "summary": "Search for content",
        "operationId": "searchContent",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "description": "Search query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "snippet": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          }
        }
      }
    }
  }
}

Veja a seguir um exemplo de um esquema sem suporte com oneOf:

{
  "oneOf": [
    {"$ref": "#/components/schemas/Pencil"},
    {"$ref": "#/components/schemas/Pen"}
  ]
}