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

Lecture de 9 minute(s)
0

Je souhaite intégrer une API REST Amazon API Gateway à Amazon Simple Queue Service (Amazon SQS) et corriger les erreurs d’intégration.

Résolution

Pour intégrer une API REST API Gateway à Amazon SQS, choisissez l'une des méthodes suivantes :

Utiliser le protocole de requête AWS

Pour intégrer une API REST API Gateway à Amazon SQS, vous pouvez utiliser le protocole de requête AWS. Procédez comme suit :

  1. Créez une file d'attente SQS.
  2. Créez un rôle AWS Identity and Access Management (IAM), puis associez une politique Amazon SQS avec une autorisation SendMessage. La politique vous permet de publier des messages depuis l'API vers 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"
      ]
    }
  ]
}

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

  1. Créer une API REST dans la passerelle d’API.
  2. Dans la console API Gateway, créez une intégration Amazon SQS pour votre API REST.
  3. Créez une ressource API REST ou une méthode API REST :
    Sur l'écran Ressources, sélectionnez Créer une méthode.
    Pour Type de méthode, sélectionnez POST.
    Pour le type d’intégration, choisissez AWS Service.
    Pour Région AWS, choisissez votre région.
    Pour Service AWS, sélectionnez Simple Queue Service (SQS).
    (Facultatif) Dans le champ Sous-domaine AWS, entrez le sous-domaine utilisé par le service AWS. Consultez la documentation du service AWS pour confirmer la disponibilité d'un sous-domaine. Pour l'exemple de configuration d'Amazon SQS, laissez ce champ vide.
    Dans le champ méthode HTTP, choisissez POST.
    Dans le champ Type d'action, choisissez Utiliser un remplacement de chemin d’accès.
    Pour le remplacement du chemin d’accès (facultatif), entrez votre numéro de compte et le nom de la file d’attente SQS dans le format suivant : example-account-id/example-sqs-queue-name. Par exemple : 1234567890/MySQSStandardQueue.
    Pour Rôle d'exécution, entrez l'ARN du rôle IAM.
    Pour Délai d’expiration par défaut, choisissez une option pour votre configuration.
    Continuez à saisir les informations d'intégration de votre API REST.
    Choisissez la demande d'intégration de la méthode POST.
    Choisissez Modifier.
    Pour Demander la clé de passe corps, 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 le type de contenu.
    Pour Mappé à partir de, entrez 'application/x-www-form-urlencoded'.
    Développez les Modèles de mappage.
    Choisissez Ajouter un modèle de mappage.
    Pour Type de contenu, entrez application/json.
    Pour le modèle, entrez Action=SendMessage&MessageBody=$input.body, puis choisissez Enregistrer.
  4. Déployez l'API REST.
  5. Pour tester la configuration, envoyez la demande 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 la phase de test et exemple-resource par le nom de votre ressource.

Lorsque votre intégration est réussie, votre réponse ressemble à ce qui suit :

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

Utiliser le protocole AWS JSON

Pour intégrer une API REST API Gateway à Amazon SQS, vous pouvez utiliser le protocole AWS JSON. Procédez comme suit :

  1. Créez une file d'attente SQS.
  2. Créez un rôle AWS IAM, puis associez une stratégie Amazon SQS avec une autorisation SendMessage. La stratégie vous permet de publier des messages depuis l'API vers 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"  
      ]  
    }  
  ]  
}

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

  1. Créer une API REST dans la passerelle d’API.
  2. Dans la console API Gateway, créez une intégration Amazon SQS pour votre API REST.
  3. Créez une ressource API REST ou une méthode API REST :
    Sur l'écran Ressources, sélectionnez Créer une méthode.
    Pour Type de méthode, sélectionnez POST.
    Pour le type d’intégration, choisissez AWS Service.
    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 AWS pour confirmer la disponibilité d'un sous-domaine.
    Dans le champ méthode HTTP, choisissez POST.
    Dans le champ 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, entrez 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 le type de contenu.
    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 le type de contenu.
    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.
  4. Déployez l'API REST.
  5. Pour tester la configuration, envoyez la demande 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 la phase 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.

Si votre intégration est réussie, votre réponse ressemble à ce qui suit :

{"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. Reportez-vous à la référence d'API SQS pour obtenir des exemples de réponses de chaque protocole.

Résoudre les erreurs courantes

Erreur UnknownOperationException

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

Si vous utilisez le protocole de requête AWS, vous obtenez une exception UnknownOperationException 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, une erreur UnknownOperationException s'affiche lorsque vous n'envoyez pas 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.

Une erreur AccessDenied s’affiche 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 la requête d’une chaîne à un format codé. Voici un exemple de modèle de mappage :

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

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 à la fois à partir du protocole de requête AWS et du protocole AWS JSON.

Une erreur KMS.AccessDeniedException s’affiche 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 qui sont lié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 SignatureDoesNotMatch

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

Une erreur SignatureDoesNotMatch 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.

Vous obtenez une erreur InvalidAddress 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.

Vous obtenez une erreur SerializationException lorsque les données utiles du corps se traduisent par un fichier JSON non 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, utilisez un formateur JSON pour détecter les erreurs de syntaxe dans votre fichier JSON.

Erreur MissingRequiredParameterException

Vous pouvez obtenir une erreur MissingRequiredParameterException lorsque vous utilisez le protocole AWS JSON.

Une erreur MissingRequiredParameterException s’affiche 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 ?