攔截器的類型

您可以在閘道上設定兩種攔截器：REQUEST 攔截器和 RESPONSE 攔截器。攔截器承載結構取決於閘道上設定的目標類型。

本主題涵蓋 MCP 目標和 HTTP 目標（例如 Amazon Bedrock AgentCore 執行期）的攔截器合約。

請求攔截器

在閘道呼叫閘道上設定的目標之前，會叫用 REQUEST 攔截器。您可以使用 REQUEST 攔截器來執行任何自訂驗證或授權。

請求攔截器輸入承載範例

下列範例顯示請求攔截器 Lambda 函數接收的輸入承載結構：


{
  "interceptorInputVersion": "1.0",
  "mcp": {
    "rawGatewayRequest": {
        "body": "<raw_request_body>"
    },
    "gatewayRequest" : {
        "path": "/mcp",
        "httpMethod": "POST",
        "headers": {
            "Accept": "application/json",
            "Authorization": "<bearer_token>",
            "SomeHeader": "headerValue1",
            "Mcp-Session-Id": "<session_id>",
            "User-Agent": "<client_user_agent>"
        },
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/list"
        }
    }
  }
}

注意

只有在攔截器組態true中passRequestHeaders將設定為時，才會包含 headers 欄位。欄位gatewayResponse不存在於請求攔截器，因為尚未產生回應。

請求攔截器輸出承載範例

下列範例顯示請求攔截器 Lambda 函數應傳回的輸出承載結構：


{
  "interceptorOutputVersion": "1.0",
  "mcp": {
    "transformedGatewayRequest" : {
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/list"
        }
    },
    "transformedGatewayResponse" : {
        "statusCode": 200,
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "result": {
                "<result_content>": "<result_value>"
            }
        }
    }
  }
}

重要

有關請求攔截器輸出的重要備註： * interceptorOutputVersion 必須設定為 "1.0" 。* 如果攔截器輸出包含 transformedGatewayResponse ，閘道會立即回應該內容，即使 transformedGatewayRequest 也提供。* 如果同時設定 REQUEST 和 RESPONSE 攔截器，且 REQUEST 攔截器輸出包含 transformedGatewayResponse ，則仍會叫用 RESPONSE 攔截器。

回應攔截器

在閘道回應呼叫者之前，會叫用 RESPONSE 攔截器。您可以使用 RESPONSE 攔截器來執行任何自訂修訂或新增回應給發起人。

回應攔截器輸入承載範例

下列範例顯示回應攔截器 Lambda 函數接收的輸入承載結構：


{
  "interceptorInputVersion": "1.0",
  "mcp": {
    "rawGatewayRequest": {
        "body": "<raw_request_body>"
    },
    "gatewayRequest" : {
        "path": "/mcp",
        "httpMethod": "POST",
        "headers": {
            "Accept": "application/json",
            "Authorization": "<bearer_token>",
            "SomeHeader": "headerValue1",
            "Mcp-Session-Id": "<session_id>",
            "User-Agent": "<client_user_agent>"
        },
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/list"
        }
    },
    "gatewayResponse" : {
        "statusCode": 200,
        "headers": {
            "SomeHeader": "headerValue1",
            "Mcp-Session-Id": "<session_id>"
        },
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "result": {
                "tools": []
            }
        }
    }
  }
}

注意

只有在攔截器組態中passRequestHeaders將設定為時，gatewayRequest才會包含 true中的 headers 欄位。回應攔截器同時接收原始請求和閘道的回應，可讓您在回應傳回給發起人之前修改回應。

回應攔截器輸出承載範例

下列範例顯示回應攔截器 Lambda 函數應傳回的輸出承載結構：


{
  "interceptorOutputVersion": "1.0",
  "mcp": {
    "transformedGatewayRequest" : {
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/list"
        }
    },
    "transformedGatewayResponse" : {
        "statusCode": 200,
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "result": {
                "<result_content>": "<result_value>"
            }
        }
    }
  }
}

重要

有關回應攔截器輸出的重要備註： * interceptorOutputVersion 必須設定為 "1.0" 。* 如果攔截器輸出包含 transformedGatewayResponse ，閘道會立即回應該內容，即使 transformedGatewayRequest 也提供。* 如果同時設定 REQUEST 和 RESPONSE 攔截器，且 REQUEST 攔截器輸出包含 transformedGatewayResponse ，則仍會叫用 RESPONSE 攔截器。

啟用串流的回應攔截器

注意

如果您的閘道上啟用了回應串流，您的回應攔截器 Lambda 函數必須檢查中的 isStreamingResponse 欄位gatewayResponse，以區分串流和非串流回應。對於串流回應，每個請求處理多個叫用 — 每個合格事件一個 — 並請注意，只有第一個叫用可以覆寫 headers和 statusCode。

在閘道上啟用回應串流時，回應攔截器行為會變更。在串流回應期間多次叫用攔截器，每個合格事件一次，而不是完整回應一次。

叫用回應攔截器時

回應攔截器會針對包含 JSON-RPC id 欄位的事件叫用：

第一個事件 — 串流上的第一個 JSON-RPC 回應或伺服器起始的請求（例如，工具結果或 / elicitation/create sampling/createMessage請求）。
後續事件 — 任何額外的 JSON-RPC 回應或伺服器啟動的請求（例如，完成引出後的最終工具結果）。

不會針對下列項目叫用回應攔截器：

notifications/progress — 進度更新會直接轉送至用戶端。
notifications/message — 日誌訊息會直接轉送至用戶端。
Ping：保持連線訊號會直接轉送至用戶端。

串流回應攔截器輸入承載

輸入承載包含設為的新isStreamingResponse欄位true。gatewayResponse.body 欄位包含目前的事件內文。

第一個事件 — 攔截器接收 headers、 statusCode和 body：


{
  "interceptorInputVersion": "1.0",
  "mcp": {
    "rawGatewayRequest": {
        "body": "<raw_request_body>"
    },
    "gatewayRequest" : {
        "path": "/mcp",
        "httpMethod": "POST",
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "myTool",
                "arguments": {}
            }
        }
    },
    "gatewayResponse" : {
        "statusCode": 200,
        "headers": {
            "Mcp-Session-Id": "<session_id>"
        },
        "isStreamingResponse": true,
        "body": {
            "jsonrpc": "2.0",
            "id": "elicit-1",
            "method": "elicitation/create",
            "params": {
                "message": "Confirm this action?",
                "requestedSchema": {}
            }
        }
    }
  }
}

後續事件 — 攔截器只會接收 body（標頭和狀態碼已傳送至用戶端）：


{
  "interceptorInputVersion": "1.0",
  "mcp": {
    "rawGatewayRequest": {
        "body": "<raw_request_body>"
    },
    "gatewayRequest" : {
        "path": "/mcp",
        "httpMethod": "POST",
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "myTool",
                "arguments": {}
            }
        }
    },
    "gatewayResponse" : {
        "isStreamingResponse": true,
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "result": {
                "content": [{"type": "text", "text": "Tool result"}]
            }
        }
    }
  }
}

串流回應攔截器輸出承載

攔截器可以覆寫的內容取決於它是第一個還是後續事件：

事件	可以覆寫	如果傳回則忽略
第一個事件	`headers`, `statusCode`, `body`	N/A
後續事件	僅限 `body`	`headers`、 `statusCode`（已傳送至用戶端）
非串流（未變更）	`headers`, `statusCode`, `body`	N/A

HTTP 目標的攔截器

HTTP 目標使用與 MCP 目標不同的攔截器承載結構。HTTP 目標 (AgentCore 執行期和傳遞）和推論目標都使用此http承載結構。推論是不同的目標類型，會共用 HTTP 攔截器承載形狀。承載使用 http金鑰而非 mcp金鑰。請求和回應內文是 base64 編碼的字串，而不是剖析的 JSON 物件。

HTTP 目標在緩衝模式下支援 REQUEST 和 RESPONSE 攔截器，其中閘道會在叫用回應攔截器之前緩衝完整回應。串流模式中尚未支援攔截器。

下列清單摘要說明 HTTP 目標攔截器的關鍵行為：

httpMethod 欄位為唯讀。
請求和回應body欄位是 base64 編碼的字串。
只有在攔截器組態中將設定為 passRequestHeaders 時，請求承載true才會包含 headers 欄位。
如果 REQUEST 攔截器的輸出中transformedGatewayResponse存在，閘道會立即傳回該回應，而不會呼叫目標（短路）。RESPONSE 攔截器在短路後不會執行。

請求攔截器輸入承載範例

下列 JSON 範例顯示您的請求攔截器 Lambda 函數在處理 HTTP 目標請求時接收的輸入承載結構：


{
  "interceptorInputVersion": "1.0",
  "http": {
    "gatewayRequest": {
      "path": "/my-target-name/invocations",
      "httpMethod": "POST",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "<bearer_token>"
      },
      "body": "<base64_encoded_body>"
    }
  }
}

注意

請注意下列有關輸入承載的事項：

只有在攔截器組態true中passRequestHeaders將設定為時，才會包含 headers 欄位。
body 欄位是代表原始 HTTP 請求內文的 base64 編碼字串。
包含 httpMethod 欄位以供參考，但僅供讀取。攔截器無法變更它。

請求攔截器輸出承載範例

下列 JSON 範例顯示您的請求攔截器 Lambda 函數在轉換 HTTP 目標請求時必須傳回的輸出承載結構：


{
  "interceptorOutputVersion": "1.0",
  "http": {
    "transformedGatewayRequest": {
      "headers": {
        "Content-Type": "application/json",
        "X-Custom-Header": "custom-value"
      },
      "body": "<base64_encoded_body>"
    },
    "transformedGatewayResponse": {
      "contentType": "application/json",
      "statusCode": 200,
      "headers": {
        "X-Custom-Header": "custom-value"
      },
      "body": "<base64_encoded_body>"
    }
  }
}

重要

HTTP 請求攔截器輸出的重要備註：

interceptorOutputVersion 必須將設定為 "1.0"。
如果輸出包含 transformedGatewayResponse，閘道會立即傳回該回應，而不會呼叫目標。
body 欄位必須是 base64 編碼字串。
httpMethod 不會包含在輸出中，因為它無法修改。

回應攔截器輸入承載範例

當您為 HTTP 目標設定 RESPONSE 攔截器時，閘道會緩衝目標回應並將其傳遞給您的 Lambda 函數。下列 JSON 範例顯示輸入承載的結構：


{
  "interceptorInputVersion": "1.0",
  "http": {
    "gatewayRequest": null,
    "gatewayResponse": {
      "statusCode": 200,
      "headers": null,
      "body": "<base64_encoded_body>",
      "contentType": "application/json"
    }
  }
}

注意

請注意下列有關回應輸入承載的事項：

body 欄位是代表原始 HTTP 回應內文的 base64 編碼字串。
null 如果您使用承載篩選條件排除回應內文，body則欄位為。如需詳細資訊，請參閱處理大型回應承載。

回應攔截器輸出承載範例

下列 JSON 範例顯示您的回應攔截器 Lambda 函數在轉換 HTTP 目標回應時傳回的輸出承載結構：


{
  "interceptorOutputVersion": "1.0",
  "http": {
    "transformedGatewayResponse": {
      "statusCode": 200,
      "headers": {
        "X-Custom-Header": "custom-value"
      },
      "body": "<base64_encoded_body>",
      "contentType": "application/json"
    }
  }
}

重要

HTTP 回應攔截器輸出的重要備註：

interceptorOutputVersion 必須將設定為 "1.0"。
statusCode、 body和 contentType 欄位會覆寫原始回應值。如果您省略欄位（或將其設定為 null)，閘道會使用原始值。
body 欄位必須是 base64 編碼字串。
若要傳遞未變更的回應，請傳回空http物件：{"interceptorOutputVersion": "1.0", "http": {}}。

處理大型回應承載

Lambda 同步調用對請求和回應的加總有 6 MB 承載限制。如果目標傳回大型內文，這在推論模型中很常見，則 base64 編碼的承載可能會超過此限制並導致錯誤。

為了避免這種情況，請設定排除 RESPONSE_BODY 欄位的承載篩選條件，從攔截器輸入中排除回應內文。您的攔截器仍然可以檢查 statusCode、 contentType和 headers，並且可以插入標頭或覆寫狀態碼。排除回應內文時，輸入承載中的 body 欄位為 null，如果您的函數傳回 body: null，閘道會使用原始（未修改）回應內文。

用戶端內容

對於 HTTP 目標，閘道會透過呼叫的用戶端內容，將請求中繼資料傳遞至 Lambda 函數。您的函數可以讀取下列自訂值：GATEWAY_ARN、REQUEST_ID、 GATEWAY_ACCOUNT_ID和 SOURCE_IP。GATEWAY_ARN、 GATEWAY_ACCOUNT_ID和 REQUEST_ID值一律存在。只有在來源 IP 可用時，才會包含此SOURCE_IP值，因此您的函數應將其視為選用。

MCP 和 HTTP 攔截器承載之間的主要差異

下表摘要說明 MCP 和 HTTP 目標攔截器承載之間的差異。

欄位	MCP 目標	HTTP 目標
內文格式	Map<String， Object> （剖析的 JSON)	字串 (base64 編碼）
路徑	一律為 "/mcp"	實際 HTTP 路徑（例如 "/my-target-name/invocations")
httpMethod	固定	固定
rawGatewayRequest	包含	不包含
回應攔截器	支援	在緩衝模式下支援（在串流模式下尚不支援）

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

攔截器的許可

組態