本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Amazon API Gateway 重要說明 下一節詳細說明可能會影響您使用 API Gateway 的備註。 **Topics** + [適用於 HTTP API 的 Amazon API Gateway 重要說明](#api-gateway-known-issues-http-apis) + [適用於 HTTP 和 WebSocket API 的 Amazon API Gateway 重要說明](#api-gateway-known-issues-http-and-websocket-apis) + [適用於 REST 和 WebSocket API 的 Amazon API Gateway 重要說明](#api-gateway-known-issues-rest-and-websocket-apis) + [適用於 WebSocket API 的 Amazon API Gateway 重要說明](#api-gateway-known-issues-websocket-apis) + [適用於 REST API 的 Amazon API Gateway 重要說明](#api-gateway-known-issues-rest-apis) ## 適用於 HTTP API 的 Amazon API Gateway 重要說明 + HTTP API 會將傳入 `X-Forwarded-*` 標頭轉譯為標準 `Forwarded` 標頭，並附加傳出 IP、主機和通訊協定。 + 如果沒有承載且 Content-Length 為 0，API Gateway 會將 Content-type 標頭新增至您的請求。 ## 適用於 HTTP 和 WebSocket API 的 Amazon API Gateway 重要說明 + 適用於 HTTP 和 WebSocket API 的 Amazon API Gateway 未正式支援第 4A 版簽署程序。 ## 適用於 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 使用者指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension)。) 維度值是使用者定義的名稱的函數，包括 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 [https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) 或 [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) 實體，您應該在移除 [https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html](https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html) 的任何硬式編碼參考之後將其刪除。否則，您會有一個懸置整合，並收到錯誤，指出仍在使用 VPC 連結，即使刪除 `Resource` 或 `Method` 實體也是一樣。私有整合透過階段變數參考 `VpcLink` 時，此行為不適用。 + 下列後端可能不支援使用與 API Gateway 相容的方式來進行 SSL 用戶端身分驗證： + [NGINX](https://nginx.org/en/) + [Heroku](https://www.heroku.com/) + API Gateway 支援大部分 [OpenAPI 2.0 規格](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md)和 [OpenAPI 3.0 規格](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md)，除了以下例外： + 路徑區段只能包含英數字元、底線、連字號、句號、逗號、冒號和大括號。路徑參數必須是個別的路徑區段。例如，"resource/\$1path\$1parameter\$1name\$1" 有效，"resource\$1path\$1parameter\$1name\$1" 卻無效。 + 模型名稱只能包含英數字元。 + 針對輸入參數，只支援下列屬性：`name`、`in`、`required`、`type`、`description`。其他屬性一概忽略。 + `securitySchemes` 類型 (若已使用) 必須是 `apiKey`。不過，透過 [Lambda 授權方](apigateway-use-lambda-authorizer.md)支援 OAuth 2 和 HTTP 基本驗證；透過[供應商延伸](api-gateway-swagger-extensions-authorizer.md)完成 OpenAPI 組態。 + 不支援 `deprecated` 欄位，且會在匯出的 API 中刪除此欄位。 + 使用 [JSON 結構描述草稿第 4 版](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04)定義 API Gateway 模型，而非 OpenAPI 所使用的 JSON 結構描述。 + 在任何結構描述物件中，不支援 `discriminator` 參數。 + 不支援 `example` 標籤。 + 不支援 `nullable` 欄位。 + API Gateway 不支援 `exclusiveMinimum`。 + [簡單請求驗證](api-gateway-method-request-validation.md)不包含 `maxItems` 和 `minItems` 標籤。若要解決這個問題，請在執行驗證之前於匯入後更新模型。 + 對於 OpenAPI 3.0，您無法在相同結構描述內擁有對定義使用 `$ref` 的 `oneOf`、`anyOf` 或 `allOf`。您可以直接輸入結構描述，或定義個別 API Gateway 模型資源。如需詳細資訊，請參閱[建立更複雜的模型](models-mappings-models.md#api-gateway-request-validation-model-more-complex)。 + `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` 表示標頭名稱從 `` 變更為 `X-Amzn-Remapped-`。 `Remapped Overwritten` 表示標頭名稱從 `` 變更為 `X-Amzn-Remapped-` 並且覆寫原來的值。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/api-gateway-known-issues.html) \$1 如果其包含[簽章版本 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) 的簽章或使用 `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 將會傳回二進位格式的內容。例如，若要在瀏覽器中使用 `` 元素來傳送 JPEG 檔案，瀏覽器可能會在請求中傳送 `Accept:image/webp,image/*,*/*;q=0.8`。透過新增 `image/webp` 至 `binaryMediaTypes` 清單，端點就能收到二進位格式的 JPEG 檔案。 + 目前不支援自訂 `413 REQUEST_TOO_LARGE` 的預設閘道回應。 + API Gateway 包含所有整合回應的 `Content-Type` 標頭。內容類型預設為 `application/json`。