Amazon API Gateway に関する重要な注意点 - Amazon API Gateway
Amazon API Gateway の HTTP API に関する重要な注意点Amazon API Gateway の HTTP および WebSocket API に関する重要な注意点REST API と WebSocket API に関する重要な注意点WebSocket API に関する重要な注意点REST API に関する重要な注意点

Amazon API Gateway に関する重要な注意点

次のセクションでは、API Gateway の使用に影響する可能性がある注意点について詳しく説明します。

Amazon API Gateway の HTTP API に関する重要な注意点

  • HTTP API は受信 X-Forwarded-* ヘッダーを標準 Forwarded ヘッダーに変換し、出力 IP、ホスト、プロトコルを追加します。

  • ペイロードがなく、Content-Length が 0 の場合、API Gateway は Content-type ヘッダーをリクエストに追加します。

Amazon API Gateway の HTTP および WebSocket API に関する重要な注意点

  • 署名バージョン 4A は、Amazon API Gateway で HTTP および WebSocket API 向けに正式にはサポートされていません。

Amazon API Gateway の REST および WebSocket API に関する重要な注意点

  • API Gateway では、REST と WebSocket API 間でのカスタムドメイン名の共有はサポートされていません。

  • ステージ名には、英数字、ハイフン、およびアンダースコアのみ含めることができます。最大長は 128 文字です。

  • /ping および /sping のパスは、サービスのヘルスチェック専用です。カスタムドメインを使用した API ルートレベルでの使用は良い結果を生みません。

  • API Gateway は現在、ログイベントを 1024 バイトに制限しています。リクエストやレスポンスの本文など、1024 バイトを超えるログイベントは、CloudWatch Logs への送信前に API Gateway によって切り捨てられます。

  • 現在、CloudWatch メトリクスではディメンション名と値が 255 文字の有効な XML 文字に制限されています (詳細については、CloudWatch ユーザーガイドを参照してください)。ディメンション値は、API 名、ラベル (ステージ) 名、およびリソース名を含む、ユーザーが定義した名前の関数です。これらの名前を選択するときは、CloudWatch メトリクスの制限を超えないように注意してください。

  • マッピングテンプレートの最大サイズは 300 KB です。

Amazon API Gateway の WebSocket API に関する重要な注意点

  • API Gateway は最大 128 KB までのメッセージペイロードをサポートし、最大フレームサイズは 32 KB です。メッセージが 32 KB を超えた場合は、それぞれが 32 KB 以下の複数のフレームに分割する必要があります。大きなメッセージが受信された場合、接続は 1009 コードで閉じられます。

Amazon API Gateway の REST API に関する重要な注意点

  • プレーンテキストのパイプ文字 (|) と中かっこ文字 ({ または }) は、リクエスト URL クエリ文字列ではサポートされておらず、URL エンコードする必要があります。

  • セミコロン文字 (;) はリクエスト URL クエリ文字列に対してサポートされておらず、この結果、データが分割されます。

  • REST API は、URL エンコードされたリクエストパラメータをデコードしてからバックエンド統合に渡します。UTF-8 リクエストパラメータの場合、REST API は、パラメータをデコードしてから、バックエンド統合にユニコードとして渡します。REST API は、パーセント文字 (%) を URL エンコードしてからバックエンド統合に渡します。

  • API Gateway コンソールを使用して API をテストするとき、バックエンドに自己署名証明書が存在する、中間証明書が証明書チェーンにない、または他の認識されない証明書関連の例外がバックエンドからスローされた場合に「不明なエンドポイントのエラー」レスポンスが返されることがあります。

  • プライベート統合の API Resource または Method エンティティの場合は、VpcLink のハードコーディングされたリファレンスを削除した後で、それを削除する必要があります。それ以外の場合は、ダングリング統合があり、Resource または Method エンティティが削除されても VPC リンクがまだ使用中であることを示すエラーが表示されます。プライベート統合がステージ変数を通じて 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 にする必要があります。ただし、OAuth 2 および HTTP Basic 認証は Lambda オーソライザーによってサポートされています。OpenAPI 設定は、ベンダー拡張機能によって実現されます。

    • この deprecated フィールドはサポートされておらず、エクスポートされた API では削除されます。

    • API Gateway モデルは、OpenAPI が使用する JSON スキーマではなく、JSON スキーマのドラフト 4 を使用して定義されます。

    • discriminatorパラメータは、どのスキーマオブジェクトでもサポートされません。

    • example タグはサポートされません。

    • nullable フィールドはサポートされません。

    • exclusiveMinimum は API Gateway ではサポートされていません。

    • 単純なリクエストの検証には maxItems タグと minItems タグは含まれません。この問題を回避するには、インポートした後で、検証を行う前にモデルを更新します。

    • OpenAPI 3.0 では、同じスキーマ内の定義に $ref を使用する oneOf、anyOf、または allOf を持つことはできません。スキーマを直接入力するか、別の API Gateway モデルリソースを定義できます。詳細については、「より複雑なモデルの作成」を参照してください。

    • oneOf は、OpenAPI 2.0 または SDK の生成ではサポートされていません。

    • readOnly フィールドはサポートされません。

    • $ref を使用して他のファイルを参照することはできません。

    • "500": {"$ref": "#/responses/UnexpectedError"} フォームのレスポンス定義は、OpenAPI ドキュメントルートではサポートされません。回避策として、参照をインラインスキーマに置き換えます。

    • Int32 タイプまたは Int64 タイプの数値はサポートされていません。例を以下に示します。

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

    • 10 進数型 ("format": "decimal") は、スキーマ定義でサポートされません。

    • メソッドレスポンスでは、スキーマ定義をオブジェクト型にする必要があり、プリミティブ型にすることはできません。たとえば、"schema": { "type": "string"} はサポートされません。ただし、回避策として次のオブジェクト型を使用できます。

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

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

    • API Gateway は、OpenAPI 仕様に定義されているルートレベルのセキュリティを使用しません。したがって、オペレーションレベルでセキュリティを定義して、セキュリティが適切に適用されるようにする必要があります。

    • default のキーワードはサポートされていません。

  • API Gateway は、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 パススルー 除外/[Passthrough]/[Passthrough]
      Accept-Charset パススルー パススルー
      Accept-Encoding パススルー パススルー
      Authorization パススルー * Remapped
      Connection パススルー/パススルー/除外 Remapped
      Content-Encoding パススルー/除外/パススルー パススルー
      Content-Length パススルー (本文に基づいて生成された) パススルー
      Content-MD5 除外 Remapped
      Content-Type パススルー パススルー
      Date パススルー 上書きされ再マッピングされた
      Expect 除外 除外
      Host 統合エンドポイントに上書きされます 除外
      Max-Forwards 除外 Remapped
      Pragma パススルー パススルー
      Proxy-Authenticate 除外 除外
      Range パススルー パススルー
      Referer パススルー パススルー
      Server 除外 上書きされ再マッピングされた
      TE 除外 除外
      Transfer-Encoding 除外/除外/例外 除外
      Trailer 除外 除外
      Upgrade 除外 除外
      User-Agent パススルー Remapped
      Via 除外/除外/パススルー パススルー/除外/除外
      Warn パススルー パススルー
      WWW-Authenticate 除外 Remapped

      * Signature Version 4 の署名が含まれているか、AWS_IAM 認可が使用されている場合、Authorization ヘッダーは削除されます。

  • API Gateway で生成された API の Android SDK では、java.net.HttpURLConnection クラスを使用します。このクラスは、Android 4.4 以前を実行するデバイスでは、WWW-Authenticate ヘッダーから X-Amzn-Remapped-WWW-Authenticate への再マッピングに伴う 401 レスポンスに対して、処理されない例外をスローします。

  • API Gateway で生成された Java や、API の Android および iOS SDK とは異なり、API Gateway で生成された API の JavaScript SDK では、500 レベルのエラーの再試行はサポートされていません。

  • メソッドのテスト呼び出しでは、application/json のデフォルトコンテンツタイプを使用し、その他のコンテンツタイプの使用は無視されます。

  • X-HTTP-Method-Override ヘッダーを渡して API にリクエストを送信すると、API Gateway によってメソッドがオーバーライドされます。したがって、ヘッダーをバックエンドに渡すには、ヘッダーを統合リクエストに追加する必要があります。

  • リクエストの Accept ヘッダーに複数のメディアタイプが含まれている場合、API Gateway は最初の Accept メディアタイプのみ受け入れます。Accept メディタイプの順序を制御できず、バイナリコンテンツのメディアタイプがリストの先頭にない場合、API の Accept リストに最初の binaryMediaTypes メディアタイプを追加できます。 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 です。