Amazon API Gateway REST API 階段作為目標

API Gateway REST API 目標會將閘道連線至 REST API 的階段。閘道會將傳入的 MCP 請求轉換為 HTTP 請求到您的 REST API，並處理回應格式。當您新增或更新 API Gateway 目標時，AgentCore Gateway 會代表您呼叫 API Gateway 的 GetExport API。

您可以在目標組態中指定工具篩選條件和工具覆寫。工具篩選條件可讓您將特定資源路徑和 HTTP 方法組合作為閘道上的工具提供。這些篩選條件會建立允許清單，只公開您指定為工具的操作。

您也可以從 API Gateway 主控台將 API Gateway REST API 階段設定為閘道目標。若要進一步了解，請參閱 Amazon API Gateway 文件中的將階段新增至 AgentCore 閘道。

重要考量和限制

使用 API Gateway REST API 階段做為目標時，請記住下列要求和限制：

API Gateway 工具組態

當您新增 API Gateway REST API 做為閘道目標時，您需要提供 API Gateway 工具組態。API Gateway 工具組態會定義 REST API 中的哪些操作會公開為工具。它需要工具篩選條件清單來選取要公開的操作，並選擇性地接受工具覆寫來自訂工具中繼資料，例如工具名稱和描述。

工具篩選條件

工具篩選條件可讓您使用路徑和方法組合選取 REST API 操作。每個篩選條件支援兩個路徑比對策略：

每個篩選條件都會指定路徑和 HTTP 方法清單。篩選條件解析為 API 中存在的相符組合。多個篩選條件可以重疊，並自動刪除重複項目。

工具覆寫

根據預設，MCP 工具名稱會從符合您篩選條件的每個路徑和方法組合operationId的 中取得。如果沒有篩選條件相符operationId項目的 ，您將需要提供名稱的對應工具覆寫。如果 operationId和 覆寫名稱都遺失，則目標建立和更新將會失敗驗證。如需 AgentCore Gateway 中工具名稱的詳細資訊，請參閱了解如何命名 AgentCore Gateway 工具。

工具覆寫是選用的。它們可讓您在篩選後自訂特定操作的工具名稱或描述。每個覆寫都必須指定明確的路徑和單一 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 Gateway 目標，AgentCore Gateway 會代表您呼叫 API Gateway 的 GetExport 操作，以取得 API 定義的 OpenAPI 3.0 格式匯出。這有助於閘道將傳入的 MCP 請求正確轉譯為 HTTP 請求並處理回應。以下是 AgentCore Gateway 呼叫 GetExport 操作時的考量：

在 REST API 上更新 operationId

您可以更新 REST API，以確保 GetExport 傳回的 OpenAPI 定義已operationId設定。這是提供工具覆寫的替代方案。以下說明設定 的兩種方式operationId。

更新 OpenAPI 定義以設定 operationID

呼叫 GetExport ，更新缺少 的操作，並重新匯入您的 API，以從部署的 API 階段匯出 OpenAPI operationId 定義。

透過更新 REST API 的 方法operationId來設定

您可以使用 operationName UpdateMethod 命令，將 API Gateway 方法設定為新增 。匯出 API 時， operationName會變成 operationId。

API Gateway API 支援的傳出授權方法

您可以設定 AgentCore Gateway 目標，以使用傳出身分驗證呼叫 API。

AgentCore Gateway 支援下列 API Gateway 目標的傳出授權類型：

若要進一步了解，請參閱為您的閘道設定傳出授權。

IAM 傳出授權

API Gateway 可讓您使用 IAM 保護 REST API。啟用 IAM 授權時，用戶端必須使用 Signature 第 4 版 (SigV4 或 SigV4a) 以 AWS 登入資料簽署其請求。

設定 IAM 傳出授權

API Gateway 資源政策

API Gateway 資源政策是您連接到 API Gateway REST API 的 JSON 政策文件，以控制指定的委託人是否可以叫用 API。若要讓 AgentCore Gateway 使用資源政策呼叫 REST API，您必須執行下列動作：

以下是授予 AgentCore Gateway 存取 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 Identity 服務來建立登入資料提供者，以及透過 API Gateway 為 設定的 API 金鑰。

設定 API 金鑰傳出授權