本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

亚马逊 API Gateway REST API 分阶段作为目标

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

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

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

主要注意事项和局限性

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

API 网关工具配置

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

工具过滤器

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

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

工具覆盖

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

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

API 网关工具配置示例

以下示例 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 网关导出

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

在 REST API 上更新 operationID

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

通过更新 OpenAPI 定义来设置 operationID

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

通过更新 REST API 的方法来设置 operat ionID

您可以使用UpdateMethod命令将 API 网关https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html方法配置为operationName添加。导出您的 API 时，operationName变成operationId.

API 网关 API 支持的出站授权方法

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

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

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

IAM 出站授权

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

设置 IAM 出站授权

API 网关资源政策

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

以下是授予 AgentCore 网关访问您的 REST API 权限的 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 密钥出站授权