Comment puis-je intégrer une API REST API Gateway à Amazon SQS et corriger les erreurs courantes ?

Résolution

Pour intégrer une API REST API Gateway à Amazon SQS, utilisez le protocole de requête AWS ou le protocole AWS JSON.

Utilisez le protocole de requête AWS pour intégrer une API REST API Gateway à Amazon SQS.

Procédez comme suit :

1. Créez une file d'attente SQS.

2. Créez un rôle Gestion des identités et des accès AWS (AWS IAM) pour un service AWS.
   Remarque : Pour Service ou cas d'utilisation, choisissez API Gateway.

3. Pour vous permettre de publier des messages depuis l'API vers Amazon SQS, associez la politique Amazon SQS suivante aux autorisations SendMessage :

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

   Remarque : Remplacez exemple-region par votre région AWS, exemple-account-id par l’ID de votre compte AWS et example-sqs-queue-name par le nom de votre file d'attente SQS.

4. Créez une API REST dans API Gateway.

5. Dans la console API Gateway, créez une intégration Amazon SQS pour votre API REST.

6. Créez une ressource API REST ou une méthode API REST :
   Sur la page Ressources, sélectionnez Créer une méthode.
   Pour Type de méthode, sélectionnez POST.
   Pour Type d’intégration, choisissez Service AWS.
   Pour Région AWS, choisissez votre région.
   Pour Service AWS, sélectionnez Simple Queue Service (SQS).
   (Facultatif) Pour Sous-domaine AWS, saisissez le sous-domaine utilisé par le service AWS. Consultez la documentation du service pour confirmer la disponibilité d’un sous-domaine. Pour l'exemple de configuration d'Amazon SQS, laissez ce champ vide.
   Pour Méthode HTTP, choisissez POST.
   Pour Type d'action, choisissez Utiliser un remplacement de chemin d’accès.
   Pour Remplacement du chemin d’accès (facultatif), saisissez votre numéro de compte et le nom de la file d’attente SQS au format suivant : example-account-id/example-sqs-queue-name. Par exemple : 1234567890/MySQSStandardQueue.
   Pour Rôle d'exécution, saisissez l'ARN du rôle IAM.
   Pour Délai d’intégration, choisissez une option pour votre configuration.
   Continuez à saisir les informations d'intégration de votre API REST.
   Sélectionnez Créer une méthode.
   Choisissez la demande d'intégration de la méthode POST.
   Choisissez Modifier.
   Pour Transmission du corps de requête, sélectionnez l’option correspondant à vos exigences.
   Développez les paramètres des en-têtes de demande d'URL.
   Choisissez Ajouter un paramètre d'en-tête de demande.
   Pour Nom, saisissez Content-Type.
   Pour Mappage à partir de, saisissez 'application/x-www-form-urlencoded'.
   Développez les Modèles de mappage.
   Choisissez Ajouter un modèle de mappage.
   Pour Content-Type, saisissez application/json.
   Pour le modèle, saisissez Action=SendMessage&MessageBody=$input.body, puis choisissez Enregistrer.

7. Déployez l'API REST.

8. Pour tester la configuration, envoyez la requête suivante à 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"  
     }'
   

   Remarque : Remplacez exemple-api-id par l’ID de votre API, exemple-region par votre région, exemple-stage par le nom de l’étape de test et exemple-resource par le nom de votre ressource.
   Exemple de réponse d'intégration réussie :

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

Utilisez le protocole AWS JSON pour intégrer une API REST API Gateway à Amazon SQS.

Procédez comme suit :

1. Créez une file d'attente SQS.

2. Créez un rôle IAM pour un service AWS.
   Remarque : Pour Service ou cas d'utilisation, choisissez API Gateway.

3. Pour vous permettre de publier des messages depuis l'API vers Amazon SQS, associez la politique Amazon SQS suivante aux autorisations SendMessage :

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

   Remarque : Remplacez exemple-region par votre région AWS, exemple-account-id par l’ID de votre compte AWS et example-sqs-queue-name par le nom de votre file d'attente SQS.

4. Créez une API REST dans API Gateway.

5. Dans la console API Gateway, créez une intégration Amazon SQS pour votre API REST.

6. Créez une ressource API REST ou une méthode API REST :
   Sur la page Ressources, sélectionnez Créer une méthode.
   Pour Type de méthode, sélectionnez POST.
   Pour Type d’intégration, sélectionnez Service AWS.
   Pour Région AWS, choisissez votre région.
   Pour Service AWS, sélectionnez Simple Queue Service (SQS).
   Pour Sous-domaine AWS, laissez ce champ vide. Il s'agit d'un paramètre facultatif dans lequel vous saisissez le sous-domaine utilisé par un service AWS. Consultez la documentation du service pour confirmer la disponibilité d’un sous-domaine.
   Pour Méthode HTTP, choisissez POST.
   Pour Type d'action, choisissez Utiliser un remplacement de chemin d’accès.
   Pour Remplacement de chemin, saisissez le caractère /.
   Pour Rôle d'exécution, saisissez l'ARN du rôle IAM.
   Pour Délai d’expiration par défaut, choisissez une option pour votre configuration.
   Développez les en-têtes de requête HTTP.
   Sélectionnez Ajouter un en-tête.
   Pour Nom, saisissez Content-Type.
   Sélectionnez Ajouter un en-tête.
   Pour Nom, saisissez X-Amz-Target.
   Sélectionnez Créer une méthode.
   Choisissez la demande d'intégration de la méthode POST.
   Choisissez Modifier.
   Pour Transmission du corps de requête, laissez l'option par défaut Lorsqu'aucun modèle ne correspond à l'en-tête content-type de la requête.
   Développez les paramètres des en-têtes de demande d'URL.
   Choisissez Ajouter un paramètre d'en-tête de demande.
   Pour Nom, saisissez Content-Type.
   Pour Mappage à partir de, saisissez method.request.header.Content-Type.
   Choisissez Ajouter un paramètre d'en-tête de demande.
   Pour Nom, saisissez X-Amz-Target.
   Pour Mappage à partir de, saisissez method.request.header.X-Amz-Target.
   Sélectionnez Enregistrer.

7. Déployez l'API REST.

8. Pour tester la configuration, envoyez la requête suivante à 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"
   }'

   Remarque : Remplacez exemple-api-id par l’ID de votre API, exemple-region par votre région, exemple-stage par le nom de l’étape de test et exemple-resource par le nom de votre ressource. Pour trouver la valeur de QueueUrl, vérifiez les détails de votre file d'attente Amazon SQS.

Exemple de réponse d'intégration réussie :

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

Remarque : La réponse attendue du protocole JSON AWS est différente de celle du protocole de requête AWS, même pour le même appel d'API.

Résoudre les erreurs SQS courantes

Pour résoudre les erreurs Amazon SQS courantes, suivez ces étapes de dépannage pour le message d'erreur que vous avez reçu.

Erreur « UnknownOperationException »

Vous pouvez obtenir une erreur « UnknownOperationException » à partir du protocole de requête AWS et du protocole AWS JSON.

Si vous utilisez le protocole de requête AWS, cette erreur se produit lorsque vous ne configurez pas Content-Type en tant que « application/x-www-form-urlencoded » dans l'en-tête HTTP de la requête d'intégration. Cette erreur s'affiche également lorsque vous n'ajoutez pas l'action SendMessage au modèle de mappage de la requête d'intégration. Pour corriger cette erreur, assurez-vous de formater correctement Content-Type et incluez l’action SendMessage dans le modèle de mappage.

Si vous utilisez le protocole AWS JSON, cette erreur s’affiche lorsque vous n'envoyez ou ne configurez pas correctement les en-têtes Content-Type et X-Amz-Target. Pour résoudre cette erreur, configurez l'en-tête Content-Type en tant que « application/x-amz-json-1.0 » et configurez l'en-tête X-Amz-Target en tant que AmazonSQS.{SQS-Action}, et incluez les deux en-têtes dans la requête.

Erreur « AccessDenied »

Vous pouvez obtenir une erreur « AccessDenied » à la fois à partir du protocole de requête AWS et du protocole AWS JSON.

Cette erreur se produit lorsque le rôle d’exécution d’intégration API n’a pas la permission sqs:SendMessage définie pour envoyer des messages à la file d’attente SQS.

Cette erreur s'affiche également lorsque vous utilisez le protocole de requête AWS et que vous transmettez des caractères spéciaux non pris en charge dans la chaîne de charge utile du corps de requête. Vous devez encoder des caractères spéciaux pour éviter cette erreur. Ajoutez la fonction $util.urlEncode() dans le modèle de mappage pour convertir le corps de requête d’une chaîne à un format codé. Voici un exemple de modèle de mappage :

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

Si vous utilisez une file d'attente FIFO (First-In-First-Out) Amazon SQS, assurez-vous d'inclure l'attribut MessageGroupId ou MessageDeduplicationId. Voici un exemple de modèle de mappage FIFO :

Action=SendMessage&MessageBody=$util.urlEncode($input.body)&MessageGroupId=$your-msg-group-id&MessageDeduplicationId=$your-msg-dedup-id

Remarque : Remplacez your-msg-group-id par l’ID de votre groupe de messages et your-msg-dedup-id par l’ID de votre déduplication de messages.

L'exemple suivant inclut les autorisations requises pour envoyer des messages à la file d'attente SQS :

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

Remarque : Remplacez exemple-region par votre région, exemple-account-id par votre numéro de compte, et exemple-sqs-queue-name par le nom de votre file d’attente SQS.

Erreur « KMS.AccessDeniedException »

Vous pouvez obtenir une erreur « KMS.AccessDeniedException » à partir du protocole de requête AWS et du protocole AWS JSON.

Cette erreur se produit lorsque le rôle d’exécution de l’intégration API ne peut pas effectuer d’opérations via AWS Key Management Service (AWS KMS). Pour résoudre cette erreur, vous devez configurer les autorisations pour effectuer les opérations sur les clés AWS KMS associées à la file d’attente chiffrée côté serveur d’Amazon SQS.

L'exemple suivant inclut les autorisations requises pour effectuer des opérations sur les clés KMS associées à la file d'attente SQS :

{  "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": "*"
}

Remarque : Remplacez exemple-account-id par votre numéro de compte et exemple-api-gw-integration-execution-role par le nom de votre rôle d’exécution.

Erreur « MalformedQueryString »

Vous pouvez obtenir une erreur « MalformedQueryString » à partir du protocole de requête AWS et du protocole AWS JSON.

Cette erreur se produit lorsque des caractères spéciaux figurent dans la chaîne de données utiles du corps de requête. Ajoutez la fonction $util.urlEncode() dans le modèle de mappage pour convertir le corps de requête d’une chaîne à un format codé. Voici un exemple de modèle de mappage :

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

Erreur « SignatureDoesNotMatch »

Vous pouvez obtenir une erreur « SignatureDoesNotMatch » lorsque vous utilisez le protocole de requête AWS.

Cette erreur se produit lorsque la méthode HTTP de la requête d'intégration est définie sur GET au lieu de POST. Pour résoudre cette erreur, définissez la méthode HTTP sur POST.

Erreur « InvalidAddress »

Vous pouvez obtenir une erreur « InvalidAddress » lorsque vous utilisez le protocole AWS JSON.

Cette erreur se produit lorsque l'URL de la file d'attente SQS dans les données utiles du corps est incorrecte. Pour résoudre cette erreur, vérifiez l'URL de la file d'attente SQS ciblée par l'appel d'API.

Erreur « SerializationException »

Vous pouvez obtenir une erreur « SerializationException » lorsque vous utilisez le protocole AWS JSON.

Cette erreur se produit lorsque les données utiles du corps ne forment pas un fichier JSON valide. Par exemple, votre fichier JSON peut comporter une virgule manquante ou supplémentaire, ou une accolade manquante ou supplémentaire. Pour résoudre cette erreur, modifiez votre fichier JSON à un format valide.

Erreur « MissingRequiredParameterException »

Une erreur « MissingRequiredParameterException » peut s’afficher lorsque vous utilisez le protocole AWS JSON.

Cette erreur se produit lorsque vous n'incluez pas un ou plusieurs des paramètres requis dans les données utiles du corps. Les paramètres requis dépendent de votre appel d'API. Par exemple, cette erreur provient d'un appel d'API SendMessage lorsque le paramètre MessageBody est manquant. Consultez la référence d'API SQS pour connaître les paramètres et la syntaxe requis.

Informations connexes

Intégrer Amazon API Gateway à Amazon SQS pour gérer les API REST asynchrones

Comment utiliser API Gateway comme proxy pour un autre service AWS ?