Amazon API Gateway REST API 阶段作为目标

API Gateway REST API 目标将你的网关连接到 REST API 的某个阶段。网关将传入的 MCP 请求转换为发送给 REST API 的 HTTP 请求并处理响应格式。当您添加或更新 API Gateway 目标时，Gate AgentCore way 会代表您调用 API Gateway 的 GetExportAPI。

您可以在目标配置中指定工具筛选器和工具覆盖。工具过滤器允许您在网关上使用特定的资源路径和 HTTP 方法组合作为工具。这些过滤器会创建一个允许列表，该列表仅显示您指定为工具的操作。

您也可以从 API Gateway 控制台将 API Gateway REST API 阶段配置为网关目标。要了解更多信息，请参阅 Amazon API AgentCore Gateway 文档中的向网关添加阶段。

主要考虑因素和限制

使用 API Gateway REST API 阶段作为目标时，请记住以下要求和限制：

API Gateway 工具配置

当你将 API Gateway REST API 添加为网关目标时，你需要提供 API 网关工具配置。API Gateway 工具配置定义了您的 REST API 中的哪些操作将作为工具公开。它需要工具筛选器列表来选择要显示的操作，也可以选择接受工具覆盖来自定义工具元数据，例如工具名称和描述。

工具过滤器

工具筛选器允许您使用路径和方法组合选择 REST API 操作。每个过滤器都支持两种路径匹配策略：

每个过滤器都指定路径和 HTTP 方法列表。过滤器解析为你的 API 中存在的匹配组合。多个过滤器可以重叠，重复项会自动删除。

工具覆盖

默认情况下，MCP 工具名称取自与您的过滤器匹配operationId的每个路径和方法组合。如果没有筛选器匹配项，则需要使用相应的工具替换来提供名称。operationId如果同时缺少operationId和覆盖名称，则目标创建和更新将无法通过验证。有关 AgentCore Gateway 中工具名称的更多信息，请参阅了解 AgentCore 网关工具的命名方式。

工具覆盖是可选的。它们允许您在筛选后为特定操作自定义工具名称或描述。每个覆盖都必须指定一个显式路径和一个 HTTP 方法。不支持通配符。覆盖必须与您的 API 中存在的操作相匹配，并且必须与您的过滤器解析的其中一个操作相对应。您无法覆盖未选择的操作。如果您在从操作中导入时遇到错误，operationId则可以改用工具覆盖。

API Gateway 工具配置示例

以下 API Gateway 工具配置示例，展示了如何使用筛选器和替代项。所有示例都使用具有以下路径和方法的 API：

/pets/{petId} - GET
/pets/{petId}  - POST
/pets/{petId}  - OPTIONS
/pets          - GET
/pets          - OPTIONS
/              - GET

通配符路径和方法列表

工具配置：

{
  "filterPath": "/pets/*",
  "methods": ["GET", "POST"]
}

结果

明确的路径和方法列表

工具配置：

{
  "filterPath": "/pets/{petId}",
  "methods": ["GET", "POST"]
}

结果

显式路径和显式方法列表（最具体）

工具配置：

{
  [
    {
        "filterPath": "/pets/{petId}",
        "methods": ["POST"]
    },
    {
        "filterPath": "/pets/{petId}",
        "methods": ["GET"]
    }
  ]
}

结果

混合搭配显式路径和通配符路径：

工具配置：

{
  [
    {
        "filterPath": "/pets/{petId}",
        "methods": ["GET"]
    },
    {
        "filterPath": "/*",
        "methods": ["GET"]
    }
  ]
}

结果

工具筛选器和工具覆盖

您可以提供工具过滤器并添加替换。该覆盖在 REST API 中指定资源路径，例如 /pets，以及要为指定路径公开的 HTTP 方法。覆盖必须与 REST API 中的现有路径明确匹配。

工具配置

{
  "toolFilters": [
    {
      "filterPath": "/pets/*",
      "methods": ["GET", "POST"]
    },
    {
      "filterPath": "/",
      "methods": ["GET"]
    }
  ],
  "toolOverrides": [
    {
      "path": "/pets/{petId}",
      "method": "GET",
      "name": "GetPetById",
      "description": "Retrieve a specific pet by its ID"
    }
  ]
}

结果

API Gateway 导出

要设置您的 API 网关目标，Gat AgentCore eway 会代表您调用 API Gateway 的GetExport操作，以获取 API 定义的 OpenAPI 3.0 格式导出。这有助于网关正确地将传入的 MCP 请求转换为 HTTP 请求并处理响应。以下是 AgentCore Gateway 何时调用该 GetExport 操作的注意事项：

更新 REST API 上的 operationID

您可以更新您的 REST API，以确保返回的 OpenAPI 定义GetExport已operationId设置。这是提供工具覆盖的替代方案。以下说明了两种设置方法operationId。

通过更新你的 OpenAPI 定义来设置操作 ID

通过调用GetExport、更新缺少operationId的操作并重新导入 API，从已部署的 API 阶段导出 OpenAPI 定义。

通过更新 REST API 的方法来设置 operation ID

您可以使用UpdateMethod命令将 API Gateway 方法配置为operationName添加。导出 API 后，operationName会变成operationId。

API Gateway API 支持的出站授权方法

您可以将 AgentCore 网关目标配置为通过出站身份验证调用您的 API。

AgentCore Gateway 支持 API 网关目标的以下类型的出站授权：

要了解更多信息，请参阅为您的网关设置出站授权。

IAM 出站授权

API Gateway 允许你使用 IAM 保护你的 REST API。启用 IAM 授权后，客户必须使用签名版本 4（Sigv4 或 sigv4A）使用证书签署请求。 AWS

设置 IAM 出站授权

API Gateway 资源政策

API Gateway 资源策略是您附加到 API Gateway REST API 的 JSON 策略文档，用于控制指定的委托人是否可以调用该 API。为了让 AgentCore Gateway 使用资源策略调用您的 REST API，您必须执行以下操作：

以下是 API 资源策略的示例，该策略授予 AgentCore 网关对您的 REST API 的访问权限。

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "execute-api:Invoke",
      "Resource": "arn:aws:execute-api:us-west-2:111122223333:abcd123/*/*/*",
      "Condition": {
        "ArnEquals": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:gateway/my-gateway-d4jrgkaske"
        }
      }
    }
  ]
}

API 密钥出站授权

要使用 API 密钥设置出站授权，您可以使用 AgentCore 身份服务创建凭据提供者，并使用您通过 API Gateway 配置的 API 密钥。

设置 API 密钥出站授权