Amazon API Gateway 重要說明 - Amazon API Gateway
適用於 REST API、HTTP API 和 WebSocket API 的重要說明適用於 HTTP API 的 Amazon API Gateway 重要說明適用於 REST API 和 WebSocket API 的重要說明適用於 WebSocket API 的重要說明適用於 REST API 的重要說明

Amazon API Gateway 重要說明

下一節詳細說明可能會影響您使用 API Gateway 的備註。

適用於 REST API、HTTP API 和 WebSocket API 的 Amazon API Gateway 重要說明

  • Amazon API Gateway 未正式支援簽章版本 4A。

適用於 HTTP API 的 Amazon API Gateway 重要說明

  • HTTP API 會將傳入 X-Forwarded-* 標頭轉譯為標準 Forwarded 標頭，並附加傳出 IP、主機和通訊協定。

適用於 REST 和 WebSocket API 的 Amazon API Gateway 重要說明

  • API Gateway 不支援在 REST 和 WebSocket API 間共用自訂網域名稱。

  • 階段名稱僅可含有英數字元、連字號與底線。長度上限為 128 字元。

  • 系統會為服務運作狀態檢查保留 /ping 和 /sping 的路徑。針對具有自訂網域的 API 根層級資源使用這些項目，將會無法產生預期的結果。

  • API Gateway 目前將日誌事件限制為 1024 個位元組。API Gateway 會先截斷大於 1024 個位元組的日誌事件 (例如請求和回應內文)，再提交至 CloudWatch Logs。

  • CloudWatch 指標目前會將維度名稱和值限制為 255 有效的 XML 字元。(如需更多詳細資訊，請參閱 CloudWatch 使用者指南。) 維度值是使用者定義的名稱的函數，包括 API 名稱、標籤 (階段) 名稱和資源名稱。選擇這些名稱時，請小心不要超過 CloudWatch 指標限制。

  • 映射範本的大小上限為 300 KB。

適用於 WebSocket API 的 Amazon API Gateway 重要說明

  • API Gateway 將支援高達 128 KB 的訊息承載，影格大小上限為 32 KB。如果訊息超過 32 KB，則必須分割成多個影格，每個為 32 KB 或以下。如果接收到更大的訊息，則該連線會關閉，並出現程式碼 1009。

適用於 REST API 的 Amazon API Gateway 重要說明

  • 任何請求 URL 查詢字串不支援純文字管道字元 (|) 和大括號字元 ({ 或 })，而且必須進行 URL 編碼。

  • 任何請求 URL 查詢字串不支援分號字元 (;) 且會 導致資料分割。

  • REST API 會先解碼 URL 編碼的請求參數，然後再將它們傳遞至後端整合。對於 UTF-8 請求參數，REST API 會解碼參數，然後將參數當作 Unicode 傳遞至後端整合。REST API 在將百分號字元 (%) 傳遞到後端整合之前對其進行 URL 編碼。

  • 使用 API Gateway 主控台測試 API 時，如果向後端呈現自我簽署憑證、憑證鏈遺失中繼憑證，或後端擲回任何其他無法辨識憑證的相關例外狀況，則您可能會收到「不明端點錯誤」回應。

  • 針對具有私有整合的 API Resource 或 Method 實體，您應該在移除 VpcLink 的任何硬式編碼參考之後將其刪除。否則，您會有一個懸置整合，並收到錯誤，指出仍在使用 VPC 連結，即使刪除 Resource 或 Method 實體也是一樣。私有整合透過階段變數參考 VpcLink 時，此行為不適用。

  • 下列後端可能不支援使用與 API Gateway 相容的方式來進行 SSL 用戶端身分驗證：

  • API Gateway 支援大部分 OpenAPI 2.0 規格和 OpenAPI 3.0 規格，除了以下例外：

    • 路徑區段只能包含英數字元、底線、連字號、句號、逗號、冒號和大括號。路徑參數必須是個別的路徑區段。例如，"resource/{path_parameter_name}" 有效，"resource{path_parameter_name}" 卻無效。

    • 模型名稱只能包含英數字元。

    • 針對輸入參數，只支援下列屬性：name、in、required、type、description。其他屬性一概忽略。

    • securitySchemes 類型 (若已使用) 必須是 apiKey。不過，透過 Lambda 授權方支援 OAuth 2 和 HTTP 基本驗證；透過供應商延伸完成 OpenAPI 組態。

    • 不支援 deprecated 欄位，且會在匯出的 API 中刪除此欄位。

    • 使用 JSON 結構描述草稿第 4 版定義 API Gateway 模型，而非 OpenAPI 所使用的 JSON 結構描述。

    • 在任何結構描述物件中，不支援 discriminator 參數。

    • 不支援 example 標籤。

    • API Gateway 不支援 exclusiveMinimum。

    • 簡單請求驗證不包含 maxItems 和 minItems 標籤。若要解決這個問題，請在執行驗證之前於匯入後更新模型。

    • oneOf 不支援 OpenAPI 2.0 或 SDK 開發套件產生。

    • 不支援 readOnly 欄位。

    • $ref 無法用於參考其他檔案。

    • 在 OpenAPI 文件根中，不支援 "500": {"$ref": "#/responses/UnexpectedError"} 形式的回應定義。若要解決這個問題，請將參考取代為內嵌結構描述。

    • 不支援 Int32 或 Int64 類型的數字。範例顯示如下：

      "elementId": {
    "description": "Working Element Id",
    "format": "int32",
    "type": "number"
}

    • 在結構描述定義中，不支援小數格式類型 ("format": "decimal")。

    • 在方法回應中，結構描述定義必須為物件類型，而且不能是基本類型。例如，不支援 "schema": { "type": "string"}。不過，您可以使用下列物件類型來解決這個問題：

      "schema": {
     "$ref": "#/definitions/StringResponse"
            }

 "definitions": {
    "StringResponse": {
      "type": "string"
    }
  }

    • API Gateway 不會使用 OpenAPI 規格中定義的根層級安全性，因此您需要在操作層級中定義安全性，以便適當應用。

    • 不支援 default 關鍵字。

  • 使用 Lambda 整合或 HTTP 整合處理方法時，API Gateway 制定下列限制。

    • 標頭名稱和查詢參數是以區分大小寫的方式進行處理。

    • 傳送至整合端點或由整合端點送回時，可能會將下列資料表清單中的標頭捨棄或修改：在此資料表中：

      • Remapped 表示標頭名稱從 <string> 變更為 X-Amzn-Remapped-<string>。

        Remapped Overwritten 表示標頭名稱從 <string> 變更為 X-Amzn-Remapped-<string> 並且覆寫原來的值。

      標頭名稱 請求 (http/http_proxy/lambda) 回應 (http/http_proxy/lambda)
      Age 傳遞 傳遞
      Accept 傳遞 已捨棄/傳遞/傳遞
      Accept-Charset 傳遞 傳遞
      Accept-Encoding 傳遞 傳遞
      Authorization 傳遞 * 已重新對應
      Connection 傳遞/傳遞/已捨棄 已重新對應
      Content-Encoding 傳遞/已捨棄/傳遞 傳遞
      Content-Length 傳遞 (依據內文產生) 傳遞
      Content-MD5 已捨棄 已重新對應
      Content-Type 傳遞 傳遞
      Date 傳遞 已重新對應覆寫
      Expect 已捨棄 已捨棄
      Host 覆寫至整合端點 已捨棄
      Max-Forwards 已捨棄 已重新對應
      Pragma 傳遞 傳遞
      Proxy-Authenticate 已捨棄 已捨棄
      Range 傳遞 傳遞
      Referer 傳遞 傳遞
      Server 已捨棄 已重新對應覆寫
      TE 已捨棄 已捨棄
      Transfer-Encoding 已捨棄/已捨棄/例外 已捨棄
      Trailer 已捨棄 已捨棄
      Upgrade 已捨棄 已捨棄
      User-Agent 傳遞 已重新對應
      Via 已捨棄/已捨棄/傳遞 傳遞/已捨棄/已捨棄
      Warn 傳遞 傳遞
      WWW-Authenticate 已捨棄 已重新映射

      * 如果其包含簽章版本 4 的簽章或使用 AWS_IAM 授權，則 Authorization 標頭將被丟棄。

  • API Gateway 所產生之 API 的 Android 軟體開發套件使用 java.net.HttpURLConnection 類別。針對將 WWW-Authenticate 標頭重新對應至 X-Amzn-Remapped-WWW-Authenticate 的 401 回應，在執行 Android 4.4 和之前版本的裝置上，此類別將會擲回未處理的例外狀況。

  • 與 API Gateway 所產生之 API 的 Java、Android 和 iOS 開發套件不同，API Gateway 所產生之 API 的 JavaScript 軟體開發套件不支援 500 層級錯誤重試。

  • 方法測試呼叫會使用預設的 application/json 內容類型，並忽略任何其他內容類型的規格。

  • 傳遞 X-HTTP-Method-Override 標頭以傳送請求至 API 時，API Gateway 即會覆寫該方法。為了將標頭傳遞至後端，您需要將該標頭新增至整合請求中。

  • 當請求在其 Accept 標頭中包含多個媒體類型時，API Gateway 只會採用第一個 Accept 媒體類型。如果您無法控制 Accept 媒體類型的順序，而且二進位內容的媒體類型不是清單中的第一個類型，您可以在 API 的 binaryMediaTypes 清單中新增第一個 Accept 媒體類型，API Gateway 將會傳回二進位格式的內容。例如，若要在瀏覽器中使用 <img> 元素來傳送 JPEG 檔案，瀏覽器可能會在請求中傳送 Accept:image/webp,image/*,*/*;q=0.8。透過新增 image/webp 至 binaryMediaTypes 清單，端點就能收到二進位格式的 JPEG 檔案。

  • 目前不支援自訂 413 REQUEST_TOO_LARGE 的預設閘道回應。

  • API Gateway 包含所有整合回應的 Content-Type 標頭。內容類型預設為 application/json。