Principais considerações e limitações Estratégia de autorização Especificação do esquema OpenAPI

Alvos 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 alvos de API.

Os destinos OpenAPI conectam seu gateway às APIs REST definidas usando as especificações do OpenAPI. O Gateway traduz 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 uma meta do OpenAPI é aplicável ao seu caso de uso. Se for o caso, você pode criar um esquema que siga as especificações e, em seguida, configurar as 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 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 destinos OpenAPI, tenha em mente os seguintes requisitos e limitações:

As versões 3.0 e 3.1 do 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 um URL válido do endpoint real
Somente application/json o tipo de conteúdo é totalmente suportado
Recursos de esquema complexo, como oneOf, anyOf e allOf, não são suportados
Serializadores de parâmetros de caminho e serializadores de parâmetros para parâmetros de consulta, cabeçalho e cookie não são suportados
Cada LLM terá ToolSpec restrições. Se o OpenAPI tiver APIs/properties/object nomes não compatíveis com os ToolSpec respectivos LLMs downstream, o plano de dados falhará. 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 as metas do 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 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 restringidos adequadamente. 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 irrestritos
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 internos da rede (falsificação de Server-Side solicitação)
Exfiltre credenciais ou dados confidenciais

Práticas recomendadas:

Use URLs estáticos e 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 em seu domínio controlado, mantendo a flexibilidade para implantações de vários locatários. O uso de restrições de enumeração evita valores arbitrários e ajuda a proteger contra ataques SSRF ao limitar 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 do OpenAPI que são suportados e não suportados pelo Gateway:

Recursos compatíveis	Recursos sem suporte
Definições do esquema Tipos de dados básicos (string, número, inteiro, booleano, matriz, objeto) Validação de campo necessária Estruturas de objetos aninhados Definições de matriz com especificações do item	Composição do esquema Uma das especificações Qualquer especificação do Of Todas as especificações do Of
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 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}`) Consulte matrizes de parâmetros 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 booleanos	Retornos de chamada e webhooks Operações de retorno de chamada Definições de webhook
Request/Response Corpos de solicitação e resposta JSON Órgãos 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 do OpenAPI:

Sem autorização — O gateway invoca o destino OpenAPI sem autorização pré-configurada. Essa abordagem não é recomendada.
OAuth — O gateway suporta OAuth de duas pernas (tipo de concessão de credenciais do cliente) e 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 OpenAPI. Você configura o provedor da 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 OpenAPI usando SigV4 com as credenciais da função de serviço do gateway. Você configura um IamCredentialProvider com um nome de serviço necessá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 do 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 o 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 do 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 destino OpenAPI estiver hospedado por trás de um desses serviços, use OAuth ou autorização de chave de API.

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

Especificação do esquema OpenAPI

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

Para obter informações sobre o formato da especificação OpenAPI, consulte Especificação OpenAPI.
Para obter informações sobre recursos compatíveis e não suportados ao usar uma especificação OpenAPI com o AgentCore Gateway, consulte a tabela em Suporte a recursos do OpenAPI. Cumpra esses requisitos para evitar erros durante a criação e invocação do alvo.

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:

Veja a seguir 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"
          }
        }
      }
    }
  }
}

Veja a seguir 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"}
  ]
}

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Fases do API Gateway

Modelos Smithy