Amazon API 網關重要說明

以下部分詳細說明了可能會影響您使用 API Gateway 的注意事項。

Amazon API 網關RESTAPIs、HTTPAPIs和的重要注意事項 WebSocket APIs

• 簽名版本 4A 不受 Amazon API 網關的官方支援。

Amazon API 網關REST和重要注意事項 WebSocket APIs

• API閘道不支援在REST和之間共用自訂網域名稱 WebSocket APIs。

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

• 系統會為服務運作狀態檢查保留 /ping 和 /sping 的路徑。將這些用於具有自定義域的API根級資源將無法產生預期的結果。

• API閘道目前將記錄事件限制為 1024 位元組。大於 1024 位元組的記錄事件 (例如要求和回應本文) 會在提交至 CloudWatch 記錄檔之前被 API Gateway 截斷。

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

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

Amazon API 網關重要注意事項 WebSocket APIs

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

Amazon API 網關重要注意事項 REST APIs

• 任何請求URL查詢字串都不支援純文字管道字元 (|)，且必須使用 URL-code。

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

• RESTAPIs在將URL編碼的請求參數傳遞給後端整合之前，先解碼。對於 UTF -8 個請求參數，RESTAPIs解碼參數，然後將它們作為 unicode 傳遞給後端集成。

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

• 對於具有私有整合的APIResource或Method實體，您應該在移除. VpcLink 否則，您會有懸置的整合，並收到錯誤訊息，指出即使刪除Resource或Method實體，VPC連結仍在使用中。私有整合透過階段變數參考 VpcLink 時，此行為不適用。

• 下列後SSL端可能不支援與 API Gateway 相容的用戶端驗證：

  • NGINX

  • Heroku

• API閘道支援大部分的 Open API 2.0 規格和 Open API 3.0 規格，但下列例外：

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

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

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

  • securitySchemes 類型 (若已使用) 必須是 apiKey。不過，Lambda 授權人支援 OAuth 2 和HTTP基本驗證；Open API 組態是透過廠商擴充功能來實現的。

  • 此deprecated欄位不受支援，而且會在匯出時捨棄此欄位APIs。

  • API閘道模型是使用JSON結構描述草稿 4 來定義，而不是 Open 使用的JSON結構描述API。

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

  • 不支援 example 標籤。

  • exclusiveMinimumAPI閘道不支援。

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

  • oneOf不支援「開放 API 2.0」或「SDK層代」。

  • 不支援 readOnly 欄位。

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

  • 開啟API文件根目錄中不支援"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閘道不使用 Open API 規格中定義的根層級安全性。因此您需要在操作層級中定義安全性，以便適當應用。

  • 不支援 default 關鍵字。

• API閘道在處理具有 Lambda 整合或HTTP整合的方法時，會制定下列限制和限制。

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

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

    • 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網關API生成SDK的安卓系統使用該java.net.HttpURLConnection類。針對將 WWW-Authenticate 標頭重新對應至 X-Amzn-Remapped-WWW-Authenticate 的 401 回應，在執行 Android 4.4 和之前版本的裝置上，此類別將會擲回未處理的例外狀況。

• 與API閘道生成SDKs的 Java，Android 和 iOS 不同API，由API網關API生成 JavaScript SDK的不支持重試 500 級錯誤。

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

• 當通過傳遞X-HTTP-Method-Override標頭將請求發送到時，APIGateway 覆蓋該方法。API為了將標頭傳遞至後端，您需要將該標頭新增至整合請求中。

• 當請求在其Accept標頭中包含多個媒體類型時，APIGateway 僅遵循第一種Accept媒體類型。如果您無法控制Accept媒體類型的順序，並且二進制內容的媒體類型不是列表中的第一個，則可以在列表中添加第一種Accept媒體類型API，APIGateway 將以二進制形式返回您的內容。binaryMediaTypes例如，要使用瀏覽器中的元<img>素發送JPEG文件，瀏覽器可能會在請求Accept:image/webp,image/*,*/*;q=0.8中發送。通過添加image/webp到binaryMediaTypes列表中，端點將以二進製JPEG文件形式接收文件。

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

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