本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 亚马逊 API Gateway REST API 分阶段作为目标
API Gateway REST API 目标将您的网关连接到 REST API [ 的某个](https://docs.amazonaws.cn/apigateway/latest/developerguide/set-up-stages.html)阶段。网关将传入的 MCP 请求转换为发给 REST API 的 HTTP 请求，并处理响应格式。当您添加或更新 API 网关目标时，Gate AgentCore way 会代表您调用 [ GetExport ](https://docs.amazonaws.cn/apigateway/latest/api/API_GetExport.html) API Gateway 的 API。
您可以在目标配置中指定工具筛选器和工具替代。工具过滤器使您可以将特定的资源路径和 HTTP 方法组合作为工具在网关上使用。这些过滤器会创建允许列表，该列表仅显示您指定为工具的操作。
您还可以从 API 网关控制台将 API 网关 REST API 阶段配置为网关目标。要了解更多信息，请参阅 Amazon API AgentCore Gateway 文档[中的向网关](https://docs.amazonaws.cn/apigateway/latest/developerguide/mcp-server.html)添加阶段。
**Topics**
+ [主要注意事项和局限性](#gateway-target-api-gateway-limitations)
+ [API 网关工具配置](#gateway-target-api-gateway-configuration)
+ [API 网关导出](#gateway-target-api-gateway-export)
+ [API 网关 API 支持的出站授权方法](#gateway-target-api-gateway-outbound)
## 主要注意事项和局限性
使用 API 网关 REST API 阶段作为目标时，请记住以下要求和限制：
+ 您的 API 必须与您的 AgentCore 网关位于同一个账户中。
+ 您的 API 必须与您的 AgentCore 网关位于同一区域。
+ 您的 API 必须是 API 网关 REST API。我们不支持 API 网关 [ HTTP API ](https://docs.amazonaws.cn/apigateway/latest/developerguide/http-api.html) 或 [ WebSocket API。](https://docs.amazonaws.cn/apigateway/latest/developerguide/apigateway-websocket-api.html)
+ 您的 API 必须使用公共[终端节点类型进行配置](https://docs.amazonaws.cn/apigateway/latest/developerguide/api-gateway-api-endpoint-types.htm)。不支持私有端点。要创建可以访问您的 VPC 中资源的网关目标，您应使用公有终端节点和 [ API 网关私有集成](https://docs.amazonaws.cn/apigateway/latest/developerguide/set-up-private-integration.html)。
+ 如果您的 REST API 的方法使用`AWS_IAM`授权并需要 [ API 密钥](https://docs.amazonaws.cn/apigateway/latest/developerguide/api-gateway-api-usage-plans.html)，则 AgentCore 网关将不支持此方法。它将被排除在处理范围之外。
+ 如果您的 API 使用代理资源，例如`/pets/{proxy+}`， AgentCore Gateway 将不支持此方法。
+ 要设置您的 API 网关目标，Gate AgentCore way 会代表您调用 [ GetExport ](https://docs.amazonaws.cn/apigateway/latest/api/API_GetExport.html) API Gateway 的 API，以获取 OpenAPI 3.0 格式导出您的 REST API 定义。有关此问题及其可能如何影响您的 Target 配置的更多详细信息，请参阅 [ API 网关导出。](#gateway-target-api-gateway-export)
## API 网关工具配置
当您将 API 网关 REST API 添加为网关目标时，您需要提供 API 网关工具配置。API 网关工具配置定义了您的 REST API 中的哪些操作作为工具公开。它需要工具过滤器列表来选择要公开的操作，并且可以选择接受工具替代来自定义工具元数据，例如工具名称和描述。
### 工具过滤器
工具筛选器允许您使用路径和方法组合选择 REST API 操作。每个过滤器支持 2 种路径匹配策略：
+ **显式路径 **-匹配单个特定路径，例如 `/pets/{petId}`
+ **通配符路径 **-匹配所有以指定前缀开头的路径，例如 /pets/ \*
每个过滤器都指定路径和 HTTP 方法列表。过滤器解析为您的 API 中存在的匹配组合。多个过滤器可以重叠，重复项会自动消除。
### 工具覆盖
默认情况下，MCP 工具名称取自与过滤器匹配`operationId`的每种路径和方法组合。如果没有匹配`operationId`的过滤器，则需要相应的工具替代项来提供名称。如果`operationId`和覆盖名称都缺失，则目标创建和更新将无法通过验证。有关 AgentCore Gateway 中工具名称的更多信息，请参阅[了解 AgentCore 网关工具的命名方式](gateway-tool-naming.md)。
工具覆盖是可选的。它们允许您在筛选后为特定操作自定义工具名称或描述。每个重写都必须指定一个显式路径和一个 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"]
}
```
**结果**
+ `GET /pets/{petId}`
+ `POST /pets/{petId}`
**明确的路径和方法列表 **
工具配置：
```
{
"filterPath": "/pets/{petId}",
"methods": ["GET", "POST"]
}
```
**结果**
+ `GET /pets/{petId}`
+ `POST /pets/{petId}`
**显式路径和显式方法列表（最具体）**
工具配置：
```
{
[
{
"filterPath": "/pets/{petId}",
"methods": ["POST"]
},
{
"filterPath": "/pets/{petId}",
"methods": ["GET"]
}
]
}
```
**结果**
+ `GET /pets/{petId}`
+ `POST /pets/{petId}`
**混合搭配显式路径和通配符路径：**
工具配置：
```
{
[
{
"filterPath": "/pets/{petId}",
"methods": ["GET"]
},
{
"filterPath": "/*",
"methods": ["GET"]
}
]
}
```
**结果**
+ `GET /pets/{petId}`
+ `GET /pets/`
**刀具过滤器和工具超控 **
您可以提供工具过滤器并添加替代。该覆盖在 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"
}
]
}
```
**结果**
+ `GET /pets/{petId}`— 由第一个匹配`toolFilter`，但名称和描述将根据中的条目被覆盖 `toolOverrides`
+ `POST /pets/{petId}`— 与第一个匹配，`toolFilter`但将使用导出的 OpenAPI 规范中的`operationId`和`description`作为工具名称和描述
+ `GET /`— 与第二个明确的工具过滤器相匹配，该过滤器命名了路径和单个方法
## API 网关导出
要设置您的API网关目标， AgentCore 网关代表您调用API网关的[GetExport](https://docs.amazonaws.cn/apigateway/latest/api/API_GetExport.html)操作，以获取OpenAPI 3.0格式的API定义导出。这有助于网关正确地将传入的 MCP 请求转换为 HTTP 请求并处理响应。以下是 AgentCore Gateway 调用该 GetExport 操作时的注意事项：
+ 该 GetExport 请求使用[前向访问会话提出，](https://docs.amazonaws.cn/IAM/latest/UserGuide/access_forward_access_sessions.html)并使用呼叫者的证书。
+ 创建目标的调用者必须拥有[GetExport](https://docs.amazonaws.cn/apigateway/latest/api/API_GetExport.html)在 API 网关中调用 API 的权限。
+ 该`GetExport`请求将被登录 CloudTrail。
+ 导出的 API 受到与 OpenAPI 目标类型相同的[注意事项和限制](gateway-schema-openapi.md#gateway-schema-openapi-considerations)。
+ 从 API Gateway 导出的 OpenAPI 规范的最大大小为 50 MB。
### 在 REST API 上更新 operationID
**重要**
导出的 OpenAPI 规范必须包含您要作为工具公开的所有操作的`operationId`字段。`operationId`在 MCP 接口中用作工具名称。
你可以更新你的 REST API，确保返回的 OpenAPI 定义[GetExport](https://docs.amazonaws.cn/apigateway/latest/api/API_GetExport.html)已`operationId`设置。这是提供工具替代的替代方案。以下说明了设置的 2 种方法`operationId`。
#### 通过更新 OpenAPI 定义来设置 operationID
通过调用[GetExport](https://docs.amazonaws.cn/apigateway/latest/api/API_GetExport.html)、更新缺失`operationId`的操作和重新导入 API，从已部署的 API 阶段导出 OpenAPI 定义。
1. 通过调[GetExport](https://docs.amazonaws.cn/apigateway/latest/api/API_GetExport.html)用将 OpenAPI 定义从部署的 API 阶段导出。你可以使用 CLI 执行此操作：
```
aws apigateway get-export \
--rest-api-id rest-api-id \
--stage-name api-stage \
--export-type oas30 \
--parameters 'extensions=apigateway' \
'/path/to/api_oas30_template.json'
```
1. 手动编辑 OpenAPI 定义，将添加到缺少该属性的操作中。`operationId`
1. 使用导入更新后的 OpenAPI 定义。[ PutRestApi ](https://docs.amazonaws.cn/apigateway/latest/api/API_PutRestApi.html)你可以使用 Amazon CLI 执行此操作：
```
aws apigateway put-rest-api \
--rest-api-id rest-api-id \
--mode merge \
--body 'fileb:///path/to/api_oas30_template.json'
```
1. 使用 Amazon CLI 将您的 API 重新部署到您的阶段：
```
aws apigateway create-deployment \
--rest-api-id rest-api-id \
--stage-name api-stage \
--description 'deployment-description'
```
#### `通过更新 REST API 的方法来设置 operat` ionID
您可以使用[UpdateMethod](https://docs.amazonaws.cn/apigateway/latest/api/API_UpdateMethod.html)命令将 API 网关[https://docs.amazonaws.cn/apigateway/latest/api/API_Method.html](https://docs.amazonaws.cn/apigateway/latest/api/API_Method.html)方法配置为`operationName`添加。导出您的 API 时，`operationName`变成`operationId`.
1. [UpdateMethod](https://docs.amazonaws.cn/apigateway/latest/api/API_UpdateMethod.html)使用 Amazon CLI 拨打电话：
```
aws apigateway update-method \
--rest-api-id rest-api-id \
--resource-id resource-id \
--http-method http-method \
--patch-operations '[
{
"op": "replace",
"path": "/operationName",
"value": operation-id
}
]'
```
1. 使用 Amazon CLI 将您的 API 重新部署到您的阶段：
```
aws apigateway create-deployment \
--rest-api-id rest-api-id \
--stage-name api-stage \
--description 'deployment-description'
```
## API 网关 API 支持的出站授权方法
您可以将 AgentCore 网关目标配置为使用出站身份验证调用您的 API。
**AgentCore 网关支持 API 网关目标的以下类型的出站授权：**
+ **IAM-based 出站授权 ** — 使用[网关服务角色](gateway-prerequisites-permissions.md#gateway-service-role-permissions)使用[签名版本 4（SigV4 或 Sigv4a）验证对网关目标的访问权限。](https://docs.amazonaws.cn/IAM/latest/UserGuide/reference_sigv.html)要求您的 API 网关 API 启用 IAM 授权。
+ **API 密钥 ** — 使用由 AgentCore Gateway 管理的 API 密钥调用您的 API。这与 API 网关[中的 ](https://docs.amazonaws.cn/apigateway/latest/developerguide/api-gateway-api-usage-plans.html) API 密钥不同。
+ **无授权（不推荐）**-某些目标类型为您提供绕过出站授权的选项。
要了解更多信息，请参阅[为网关设置出站授权](gateway-outbound-auth.md)。
### IAM 出站授权
API Gateway 允许您使用 IAM 保护您的 REST API。启用 IAM 授权后，客户必须使用[签名版本 4（Sigv4 或 Sigv4A）使用](https://docs.amazonaws.cn/IAM/latest/UserGuide/reference_sigv.html)证书签署请求。 Amazon
**设置 IAM 出站授权 **
1. 根据[AgentCore 网关服务角色权限创建具有正确信任权限的 IAM 角色](gateway-prerequisites-permissions.md#gateway-service-role-permissions)。
1. 向您的角色添加策略以允许该操作，`execute-api:Invoke`以及与您用于设置目标的 REST API ID 和阶段相对应的资源，例如以下策略：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"execute-api:Invoke"
],
"Resource": "arn:aws:execute-api:aws-region:account-id:rest-api-id/api-stage/*/*",
"Effect": "Allow"
}
]
}
```
#### API 网关资源政策
API 网关资源策略是 JSON 策略文档，您可以将其附加到 API 网关 REST API，用于控制指定的委托人是否可以调用 API。为了让 AgentCore Gateway 使用资源策略调用您的 REST API，您必须执行以下操作：
+ 将您作为工具提供的任何 REST API 方法的方法授权类型设置为。`AWS_IAM`
+ 配置您的资源策略以允许`bedrock-agentcore.amazonaws.com`委托人调用您的服务。您可以向该策略添加其他委托人。
以下是授予 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 密钥出站授权 **
1. 根据在 API Gateway 中为 REST API [ 设置 API 密钥，在 API 网关中创建 API 密钥](https://docs.amazonaws.cn/apigateway/latest/developerguide/api-gateway-setup-api-keys.html)。
1. 按照步骤使用 API 密钥[设置出站授权](gateway-outbound-auth.md)，提供您通过 API 网关创建的 API 密钥。