AWS re:Post Knowledge Center Feedback Survey

Help us improve the AWS re:Post Knowledge Center by sharing your feedback in a brief survey. Your input can influence how we create and update our content to better support your AWS journey.

一般的なエラーを解決するために、API Gateway REST API を Amazon SQS と統合する方法を教えてください。

所要時間4分

Amazon API Gateway REST API を Amazon Simple Queue Service (Amazon SQS) と統合したいと考えています。また、統合エラーのトラブルシューティングもしたいと考えています。

解決策

次のいずれかの方法で、API Gateway REST API を Amazon SQS と統合します。

AWS クエリプロトコルを使用する
AWS JSON プロトコルを使用する

AWS クエリプロトコルを使用する

API Gateway REST API を Amazon SQS と統合するには、AWS クエリプロトコルを使用することができます。次の手順を実行します。

SQS キューを作成します。
AWS Identity and Access Management (IAM) ロールを作成し、SendMessage アクセス許可を持つ Amazon SQS ポリシーをアタッチします。このポリシーにより、API からのメッセージを Amazon SQS に発行できるようになります。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Resource": [
        "arn:aws:sqs:example-region:example-account-id:example-sqs-queue-name"
      ],
      "Action": [
        "sqs:SendMessage"
      ]
    }
  ]
}

注: お使いのものでそれぞれ、example-region を AWS リージョンに、** example-account-id** を AWS アカウント ID に、example-sqs-queue-name を SQS キュー名に置き換えます。

API Gateway に REST API を作成します。
API Gateway コンソールで、REST API 用の Amazon SQS 統合を作成します。
REST API リソースまたは REST API メソッドを作成します。
リソース 画面で、メソッドを作成を選択します。
メソッドタイプで POST を選択します。
[統合タイプ] では、[AWS サービス] を選択します。
AWS リージョンで、ご利用のリージョンを選択します。
AWS サービスでは、Simple Queue Service (SQS) を選択します。
(オプション) AWS サブドメインに、AWS のサービスで使用するサブドメインを入力します。AWS のサービスのドキュメントをチェックし、サブドメインの可用性を確認します。Amazon SQS のサンプルセットアップでは、これは空欄のままにします。
**[HTTP メソッド]**で POST を選択します。
[アクションの種類] で [パス上書きを使用する] を選択します。
**パス上書き (オプション)**には、アカウント ID と SQS キュー名を example-account-id/example-sqs-queue-name の形式で入力します。例: 1234567890/MySQSStandardQueue
**[実行ロール]**に IAM ロールの ARN を入力します。
[デフォルトタイムアウト]でセットアップに応じたオプションを選択します。
REST API インテグレーション情報の入力を続けます。
POST メソッドの統合リクエストを選択します。
[編集] を選択します。
リクエストボディパススルーでは、要件に合ったオプションを選択します。
URL リクエストヘッダーのパラメータを展開します。
リクエストヘッダーパラメータの追加を選択します。
**[名前]**に content-type と入力します。
マップ元に application/x-www-form-urlencoded と入力します。
マッピングテンプレートを展開します。
[マッピングテンプレートを追加] を選択します。
コンテンツタイプに、application/json と入力します。
テンプレートには、Action=SendMessage&MessageBody=$input.body と入力してから、保存を選択します。
REST API をデプロイします。
API Gateway に次のリクエストを送信して、セットアップをテストします。

curl --location --request POST 'https://example-api-id.execute-api.example-region.amazonaws.com/example-stage/example-resource' \  
   --header 'Content-Type: application/json' \  
   --data-raw '{  
    "message": "Hello World"  
  }'

注: お使いのものでそれぞれ、example-api-id を API ID に、example-region をリージョンに、example-stage をテストステージ名に、example-resource をリソース名に置き換えます。

統合が正常に完了すると、次のような応答が表示されます。

{  
  "SendMessageResponse": {  
    "ResponseMetadata": {  
      "RequestId": "f879fb11-e736-52c0-bd29-a0f2d09ad90d"  
    },  
      "SendMessageResult": {  
        "MD5OfMessageAttributes": null,  
        "MD5OfMessageBody": "3fc759ac1733366f98ec4270c788fcd1",  
        "MD5OfMessageSystemAttributes": null,  
        "MessageId": "4c360c3c-08f4-4392-bc14-8b0c88e314a2",  
        "SequenceNumber": null  
    }  
  }  
}

AWS JSON プロトコルを使用する

API Gateway REST API を Amazon SQS と統合するには、AWS JSON プロトコルを使用することができます。次の手順を実行します。

SQS キューを作成します。
AWS IAM ロールを作成し、SendMessage アクセス許可を持つ Amazon SQS ポリシーをアタッチします。このポリシーにより、API からのメッセージを Amazon SQS に発行できるようになります。

{  
  "Version": "2012-10-17",  
  "Statement": [  
    {  
      "Effect": "Allow",  
      "Resource": [  
        "arn:aws:sqs:example-region:example-account-id:example-sqs-queue-name"  
      ],  
      "Action": [  
        "sqs:SendMessage"  
      ]  
    }  
  ]  
}

API Gateway に REST API を作成します。
API Gateway コンソールで、REST API 用の Amazon SQS 統合を作成します。
REST API リソースまたは REST API メソッドを作成します。
リソース 画面で、メソッドを作成を選択します。
メソッドタイプで POST を選択します。
[統合タイプ] では、[AWS サービス] を選択します。
AWS リージョンで、ご利用のリージョンを選択します。
[AWS サービス] で Simple Queue Service (SQS) を選択します。
[AWS サブドメイン] は空欄のままにします。これは、AWS サービスが使用するサブドメインを入力するオプションのパラメータです。AWS のサービスドキュメントを確認し、サブドメインの可用性を確認します。
**[HTTP メソッド]**で POST を選択します。
[アクションの種類] で [パス上書きを使用する] を選択します。
[パスのオーバーライド] に、文字 / を入力します。
**[実行ロール]**に IAM ロールの ARN を入力します。
**[デフォルトタイムアウト]**でセットアップに応じたオプションを選択します。
HTTP リクエストヘッダーを展開します。
[ヘッダーを追加] を選択します。
[名前]に content-type と入力します。
[ヘッダーを追加] を選択します。
[名前] に X-Amz-Target と入力します。
[メソッドを作成] を選択します。
POST メソッドの統合リクエストを選択します。
[編集] を選択します。
[リクエスト本文のパススルー] は、デフォルトオプションである [テンプレートがリクエストの content-type ヘッダーと一致しない場合] から変更しないでください。
URL リクエストヘッダーのパラメータを展開します。
リクエストヘッダーパラメータの追加を選択します。
名前に、content-type と入力します。
[マッピング元] で method.request.header.Content-Type と入力します。
[リクエストヘッダーパラメータの追加] を選択します。
[名前] に X-Amz-Target と入力します。
[マッピング元] で method.request.header.X-Amz-Target と入力します。
[保存] を選択します。
REST API をデプロイします。
API Gateway に次のリクエストを送信して、セットアップをテストします。

curl --location --request POST 'https://example-api-id.execute-api.example-region.amazonaws.com/example-stage/example-resource' \
  --header 'Content-Type:application/x-amz-json-1.0' \
  --header 'X-Amz-Target:AmazonSQS.SendMessage' \
  --data-raw '{
    "QueueUrl": "https://sqs.<region>.<domain>/<awsAccountId>/<queueName>/",
    "MessageBody": "This is a test message"
}'

注: お使いのものでそれぞれ、example-api-id を API ID に、example-region をリージョンに、example-stage をテストステージ名に、example-resource をリソース名に置き換えます。QueueUrl の値は、Amazon SQS キューの詳細に記載されています。

統合が正常に完了した場合は、次のような応答が表示されます。

{"MD5OfMessageBody":"fafb00f5732ab283681e124bf8747ed1","MessageId":"b5aef1f3-af31-49f2-9973-6f802f7753e6"}

注: 同じ API コールでも、AWS JSON プロトコルからの想定応答は、AWS クエリプロトコルとは異なります。各プロトコルからの応答例については、SQS API のリファレンスを参照してください。

一般的なエラーを解決する

UnknownOperationException エラー

** UnknownOperationException** エラーは、AWS クエリプロトコルおよび AWS JSON プロトコルで発生する場合があります。

AWS クエリプロトコルを使用している場合、統合リクエストの HTTP ヘッダーで Content-Type を "application/x-www-form-urlencoded" に設定していないときに UnknownOperationException が発生します。このエラーは、統合リクエストのマッピングテンプレートに SendMessage アクションを追加していない場合にも発生します。このエラーを解決するには、Content-Type の形式が適切であることを確認し、SendMessage アクションをマッピングテンプレートに含めます。

AWS JSON プロトコルを使用している場合、Content-Type と X-Amz-Target ヘッダーを送信していないか、正しく設定していない場合に、UnknownOperationException エラーが発生します。このエラーを解決するには、Content-Type ヘッダーを "application/x-amz-json-1.0" に設定し、X-Amz-Target ヘッダーを AmazonSQS.{SQS-Action} に設定したうえで、両ヘッダーをリクエストに含めます。

AccessDenied エラー

AccessDenied エラーは、AWS クエリプロトコルおよび AWS JSON プロトコルで発生する可能性があります。

API 統合の実行ロールに、SQS キューにメッセージを送信するための sqs:SendMessage アクセス許可が設定されていない場合に、AccessDenied エラーが発生します。

このエラーは、AWS クエリプロトコルを使用しており、サポートされていない特殊文字をリクエスト本文のペイロード文字列に渡した場合にも発生します。このエラーを回避するには、特殊文字をエンコードする必要があります。マッピングテンプレートに $util.urlEncode() 関数を追加し、リクエスト本文を文字列からエンコードされた形式に変換します。マッピングテンプレートの例を次に示します。

Action=SendMessage&MessageBody=$util.urlEncode($input.body)

次の例には、SQS キューにメッセージを送信するために必要なアクセス許可が含まれています。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Resource": [
        "arn:aws:sqs:example-region:example-account-id:example-sqs-queue-name"
      ],
      "Action": [
        "sqs:SendMessage"
      ]
    }
  ]
}

注: お使いのものでそれぞれ、example-region をリージョンに、example-account-id をアカウント ID に、example-sqs-queue-name を SQS キュー名に置き換えます。

KMS.AccessDeniedException エラー

KMS.AccessDeniedException エラーは、AWS クエリプロトコルおよび AWS JSON プロトコルから発生する可能性があります。

KMS.AccessDeniedException エラーは、API 統合の実行ロールが AWS Key Management Service (AWS KMS) 経由で操作を実行できない場合に発生します。このエラーを解決するには、Amazon SQS サーバー側の暗号化キューにアタッチされている AWS KMS キーに対して操作を実行するためのアクセス許可を設定します。

次の例には、SQS キューにアタッチされている KMS キーを操作するために必要なアクセス許可が含まれています。

{
  "Sid": "Allow use of the key",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::example-account-id:role/example-api-gw-integration-execution-role"
  },
  "Action": [
    "kms:Encrypt",
    "kms:GenerateDataKey*",
    "kms:Decrypt"
  ],
  "Resource": "*"
}

注: お使いのものでそれぞれ、example-account-id をアカウント ID に、example-api-gw-integration-execution-role を実行ロール名に置き換えます。

SignatureDoesNotMatch エラー

AWS クエリプロトコルの使用時に、SignatureDoesNotMatch エラーが発生する場合があります。

SignatureDoesNotMatch エラーは、統合リクエストの HTTP メソッドが POST ではなく GET に設定されている場合に発生します。このエラーを解決するには、HTTP メソッドを POST に設定します。

InvalidAddress エラー

AWS JSON プロトコルの使用時に、InvalidAddress エラーが発生する場合があります。

本文ペイロードの SQS キュー URL が誤っている場合、InvalidAddress エラーが発生します。このエラーを解決するには、API コールの対象となる SQS キューのキュー URL を確認します。

SerializationException エラー

SerializationException エラーは、AWS JSON プロトコルの使用時に発生する場合があります。

本文のペイロードが無効な JSON の場合、SerializationException エラーが発生します。たとえば、JSON にカンマが抜けている、余分なカンマがある、中括弧が抜けている、余分な中括弧がある場合が該当します。このエラーを解決するには、JSON フォーマッターツールを使用して JSON の構文ミスを特定します。

MissingRequiredParameterException エラー

MissingRequiredParameterException エラーは、AWS JSON プロトコルの使用時に発生する場合があります。

本文ペイロードに 1 件以上の必要なパラメータが含まれていない場合、MissingRequiredParameterException エラーが発生します。必要なパラメータは API 呼び出しによって異なります。たとえば、このエラーは SendMessage API コールに MessageBody パラメータが指定されていない場合に発生します。必要なパラメータと構文については、「SQS API のリファレンス」を確認してください。

一般的なエラーを解決するために、API Gateway REST API を Amazon SQS と統合する方法を教えてください。

解決策

AWS クエリプロトコルを使用する

AWS JSON プロトコルを使用する

一般的なエラーを解決する

関連情報

関連ビデオ

関連するコンテンツ