Comment intégrer une API REST d'API Gateway dans Amazon SQS et résoudre les erreurs courantes ?

Résolution

Vous pouvez configurer les API REST d'API Gateway de manière à travailler avec Amazon SQS sur la création d'une solution intégrée.

Configurer une API REST et l'intégrer à Amazon SQS

Pour intégrer une API REST de API Gateway à Amazon SQS, procédez comme suit :

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

2.    Créez un rôle AWS Identity and Access Management (IAM), et associez ensuite une politique Amazon SQS avec une autorisation SendMessage. Cette politique autorise la publication de messages provenant de l'API sur Amazon SQS. Dans la politique, remplacez example-region par votre région AWS, example-account-id par votre identifiant de compte AWS et example-sqs-queue-name par le nom de votre 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"
      ]
    }
  ]
}

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

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

• Vous pouvez éventuellement créer une ressource d'API REST ou une méthode d'API REST.
• Créez une méthode de PUBLICATION.
  Pour Type d'intégration, sélectionnez Service AWS Service.
  Pour Région, choisissez votre Région AWS.
  Pour AWS Service (Service AWS), sélectionnez Simple Queue Service (SQS).
  (Facultatif) Pour AWS Subdomain (Sous-domaine AWS), entrez le sous-domaine utilisé par le service AWS. Consultez la documentation du service AWS pour vérifier la disponibilité d'un sous-domaine. Dans le cadre de cet exemple de configuration Amazon SQS, laissez ce champ vide.
  Pour HTTP method (Méthode HTTP), sélectionnez POST (PUBLIER).
  Pour Action Type (Type d'action), sélectionnez Use path override (Utiliser un remplacement de chemin).
  Pour Path override (optional) (Remplacement de chemin [facultatif]), saisissez votre ID 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 Execution role (Rôle d'exécution), saisissez l'ARN du rôle IAM que vous avez créé à l'étape 2.
  Pour Content Handling (Gestion du contenu), sélectionnez l'option correspondant à votre configuration.
  Effacez ou sélectionnez délai d'expiration par défaut. Choisissez l'option correspondant à votre configuration.
  Enregistrez la nouvelle méthode de PUBLICATION.
• Continuez la saisie des informations d'intégration de votre API REST.
  Choisissez la méthode de PUBLICATION requête d'intégration.
  Développez les en-têtes HTTP.
  Choisissez Ajouter un en-tête.
  Dans le champ Name (Nom), saisissez Content-Type.
  Dans le champ Mapped from (Mappé depuis), saisissez 'application/x-www-form-urlencoded' et sélectionnez Create (Créer).
  Développez Mapping Templates (Modèles de mappage).
  Dans le champ Request body passthrough, sélectionnez l'option correspondant à vos besoins.
  Sélectionnez Add mapping template (Ajouter un modèle de mappage).
  Pour Content-Type, saisissez application/json puis sélectionnez Create (Créer).
  Pour le modèle, saisissez Action=SendMessage&MessageBody=$input.body

4.    Déployez l'API REST configurée.

5.    Testez la configuration en envoyant la demande suivante à API Gateway. Remplacez example-api-id par votre identifiant d'API, example-region par votre région AWS, example-stage par le nom de votre étape de test et example-resource par le nom de votre ressource.

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"
  }'

Une fois votre intégration terminée avec succès, votre réponse ressemble à la suivante :

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

Résolution des erreurs courantes

Erreur UnknownOperationException

Une erreur UnknownOperationException se produit lorsqu'un utilisateur ne parvient pas à configurer le Content-Type en tant que « application/x-www-form-urlencoded » dans l'en-tête HTTP de la demande d'intégration. L'erreur UnknownOperationException se produit également lorsque l'action SendMessage n'est pas ajoutée au modèle de mappage de la demande d'intégration.

Erreur AccessDenied

Voici un exemple d'erreur AccessDenied (Accès refusé) :

{
  "Error": {
    "Code": "AccessDenied",
    "Message": "Access to the resource https://sqs.example-region.amazonaws.com/example-account-id/example-sqs-queue-name is denied.",
    "Type": "Sender"
  },
  "RequestId": "92aea8b7-47f1-5bd4-b3c4-f3d0688d3809"
}

Une erreur AccessDenied se produit lorsque le rôle d'exécution de l'intégration d'API ne dispose pas de l'autorisation sqs:SendMessage définie pour envoyer des messages à la file d'attente SQS. L'erreur AccessDenied peut également se produire lorsque des caractères spéciaux tels que « & » et « % » sont transmis dans la charge utile du corps de la requête. Les caractères spéciaux doivent être encodés pour être transmis. Ajoutez la fonction $util.urlEncode() dans le modèle de mappage pour passer le corps de la requête d'une chaîne en un format codé. Voici un exemple de modèle de mappage :

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

L'exemple suivant inclut les autorisations nécessaires pour l'envoi des messages à la file d'attente SQS. Remplacez example-region par votre région AWS, example-account-id par votre identifiant de compte AWS et example-sqs-queue-name par le nom de votre 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"
      ]
    }
  ]
}

Erreur KMS.AccessDeniedException

Voici deux exemples d'erreurs KMS.AccessDeniedException :

{
  "Error": {
    "Code": "KMS.AccessDeniedException",
    "Message": "User: arn:aws:sts::example-account-number:assumed-role/example-sqs-queue-name/BackplaneAssumeRoleSession is not authorized to perform: kms:GenerateDataKey on resource: arn:aws:kms:example-region:example-account-number:key/example-keyId because no identity-based policy allows the kms:GenerateDataKey action (Service: AWSKMS; Status Code: 400; Error Code: AccessDeniedException; Request ID: c58f1eec-6b18-4029-826b-d05d6a715716; Proxy: null)",
    "Type": "Sender"
  },
  "RequestId": "99976a6a-3311-57e9-86e9-310d0654ff80"
}

{
  "Error": {
    "Code": "KMS.AccessDeniedException",
    "Message": "The ciphertext refers to a customer master key that does not exist, does not exist in this region, or you are not allowed to access. (Service: AWSKMS; Status Code: 400; Error Code: AccessDeniedException; Request ID: a8adea02-c246-49d9-8b3d-ff6b6a43b40f; Proxy: null)",
    "Type": "Sender"
  },
  "RequestId": "9565c451-742c-55f3-a1eb-9f3641fd30aa"
}

Une erreur KMS.AccessDeniedException se produit lorsque le rôle d'exécution de l'intégration de l'API ne peut pas effectuer d'opérations via AWS Key Management Service (AWS KMS). Des autorisations doivent être configurées de manière à effectuer des opérations sur les clés AWS KMS associées à la file d'attente cryptée côté serveur Amazon SQS.

L'exemple suivant inclut les autorisations nécessaires pour effectuer des opérations sur les clés KMS associées à la file d'attente SQS. Remplacez example-account-id par votre identifiant de compte AWS et example-api-gw-integration-execution-role par le nom de votre rôle d'exécution.

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

---