Wie integriere ich eine API Gateway REST-API in Amazon SQS und behebe häufig auftretende Fehler?

Lösung

Um eine API Gateway-REST-API in Amazon SQS zu integrieren, verwende entweder das AWS-Abfrageprotokoll oder das AWS-JSON-Protokoll.

Verwende das AWS-Abfrageprotokoll, um eine API Gateway-REST-API in Amazon SQS zu integrieren.

Führe die folgenden Schritte aus:

1. Erstelle eine SQS-Warteschlange.

2. Erstelle eine AWS Identity and Access Management (IAM, Identitäts- und Zugriffsmanagement)-Rolle für einen AWS-Service.
   **Hinweis:**Wähle für Service oder Anwendungsfall die Option API-Gateway aus.

3. Damit du Nachrichten von der API in Amazon SQS veröffentlichen kannst, füge die folgende Amazon SQS-Richtlinie mit SendMessage-Berechtigungen an:

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

   Hinweis: Ersetze example-region durch deine AWS-Region, example-account-id durch deine AWS-Konto-ID und example-sqs-queue-name durch deinen SQS-Warteschlangennamen.

4. Erstelle eine REST-API in API Gateway.

5. Erstelle in der API-Gateway-Konsole eine Amazon-SQS-Integration für die REST-API.

6. Erstelle eine REST-API-Ressource oder eine REST-API-Methode:
   Wähle auf der Seite Ressourcen die Option Methode erstellen aus.
   Wähle als Methodentyp POST aus.
   Wähle für Integrationstyp AWS Service aus.
   Wähle für AWS-Region deine Region aus.
   Wähle für AWS Service Simple Queue Service (SQS) aus.
   (Optional) Gib für AWS Subdomain die vom AWS Service verwendete Subdomain ein. Überprüfe die Verfügbarkeit einer Subdomain in der Dokumentation des Dienstes. Lasse dieses Feld für das Amazon-SQS-Beispiel-Setup leer.
   Wähle als HTTP-Methode POST aus.
   Wähle als Aktionstyp die Option Pfadüberschreibung verwenden aus.
   Gib für Pfadüberschreibung (optional) deine Konto-ID und den SQS-Warteschlangennamen im folgenden Format ein: example-account-id/example-sqs-queue-name. Zum Beispiel: 1234567890/MySQSStandardQueue.
   Gib für die Ausführungsrolle den ARN der IAM-Rolle ein.
   Wähle für das Integrations-Timeout eine Option für dein Setup.
   Gib weiterhin deine REST-API-Integrationsinformationen ein.
   Wähle Methode erstellen.
   Wähle die POST-Methode Integration Request.
   Wähle Bearbeiten aus.
   Wähle für Request Body Passthrough die Option aus, die deinen Anforderungen entspricht.
   Erweitere die Parameter für URL-Anforderungsheader.
   Wähle Request Header Parameter hinzufügen aus.
   Gib als Name Content-Type ein.
   Gib für ** Mapped from** „application/x-www-form-urlencoded“ ein.
   Erweitere dann Mapping-Vorlagen.
   Wähle Mapping-Vorlage hinzufügen aus.
   Gib als Content-Type application/json ein.
   Gib für die Vorlage **Action=SendMessage&MessageBody=$input.body ** ein, und wähle dann Speichern aus.

7. Stelle die REST-API bereit.

8. Um das Setup zu testen, sende die folgende Anfrage an 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"  
     }'
   

   Hinweis: Ersetze example-api-id durch deine API-ID, example-region durch deine Region, example-stage durch den Namen deiner Testphase und example-resource durch den Namen deiner Ressource.
   Beispiel für eine erfolgreiche Integrations-Antwort:

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

Verwende das AWS-JSON-Protokoll, um eine API Gateway-REST-API in Amazon SQS zu integrieren.

Führe die folgenden Schritte aus:

1. Erstelle eine SQS-Warteschlange.

2. Erstelle eine IAM-Rolle für einen AWS-Service.
   **Hinweis:**Wähle für Service oder Anwendungsfall die Option API-Gateway aus.

3. Damit du Nachrichten von der API in Amazon SQS veröffentlichen kannst, füge die folgende Amazon SQS-Richtlinie mit SendMessage-Berechtigungen an:

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

   Hinweis: Ersetze example-region durch deine AWS-Region, example-account-id durch deine AWS-Konto-ID und example-sqs-queue-name durch deinen SQS-Warteschlangennamen.

4. Erstelle eine REST-API in API Gateway.

5. Erstelle in der API-Gateway-Konsole eine Amazon-SQS-Integration für die REST-API.

6. Erstelle eine REST-API-Ressource oder eine REST-API-Methode:
   Wähle auf der Seite Ressourcen die Option Methode erstellen aus.
   Wähle als Methodentyp POST aus.
   Wähle für Integrationstyp AWS Service aus.
   Wähle für AWS-Region deine Region aus.
   Wähle für AWS Service Simple Queue Service (SQS) aus.
   Lasse AWS-Subdomain leer. Dies ist ein optionaler Parameter, in den du die Subdomain eingibst, die ein AWS-Service verwendet. Überprüfe die Verfügbarkeit einer Subdomain in der Dokumentation des Dienstes.
   Wähle als HTTP-Methode POST aus.
   Wähle als Aktionstyp die Option Pfadüberschreibung verwenden aus.
   Gib für Pfadüberschreibung das Zeichen / ein.
   Gib für die Ausführungsrolle den ARN der IAM-Rolle ein.
   Wähle für Standard-Timeout eine Option für dein Setup.
   Erweitere HTTP-Anforderungsheader.
   Wähle Header hinzufügen aus.
   Gib als Name Content-Type ein.
   Wähle Header hinzufügen aus.
   Gib als Name X-Amz-Target ein.
   Wähle Methode erstellen aus.
   Wähle die POST-Methode Integration Request.
   Wähle Bearbeiten aus.
   Belasse für Pass-Through des Anforderungstexts die Standardoption Wenn keine Vorlage dem Header des Anforderungsinhaltstyps entspricht.
   Erweitere die Parameter für URL-Anforderungsheader.
   Wähle Request Header Parameter hinzufügen aus.
   Gib als Name Content-Type ein.
   Gib für Zugewiesen von method.request.header.Content-Type ein.
   Wähle Request Header Parameter hinzufügen aus.
   Gib als Name X-Amz-Target ein.
   Gib für Zugewiesen von method.request.header.X-Amz-Target ein.
   Wähle Speichern aus.

7. Stelle die REST-API bereit.

8. Um das Setup zu testen, sende die folgende Anfrage an 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"
   }'

   Hinweis: Ersetze example-api-id durch deine API-ID, example-region durch deine Region, example-stage durch den Namen deiner Testphase und example-resource durch den Namen deiner Ressource. Überprüfe die Amazon SQS-Warteschlangendetails, um den QueueUrl-Wert zu ermitteln.

Beispiel für eine erfolgreiche Integrations-Antwort:

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

Hinweis: Die erwartete Antwort des AWS-JSON-Protokolls unterscheidet sich vom AWS-Abfrageprotokoll, selbst für denselben API-Aufruf.

Häufig auftretende SQS-Fehler beheben

Um häufig auftretende Amazon-SQS-Fehler zu lösen, befolgen diese Schritten zur Fehlerbehebung für die Fehlermeldung, die du erhalten hast.

„UnknownOperationException“-Fehler

Du kannst sowohl vom AWS-Abfrageprotokoll als auch vom AWS-JSON-Protokoll einen „UnknownOperationException“-Fehler erhalten.

Wenn du das AWS-Abfrageprotokoll verwendest, erhältst du diesen Fehler, wenn du den Inhaltstyp nicht als „application/x-www-form-urlencoded“ im HTTP-Header der Integrationsanforderung konfigurierst. Dieser Fehler wird auch angezeigt, wenn du die SendMessage-Aktion nicht zur Zuweisungsvorlage der Integrationsanforderung hinzufügst. Um diesen Fehler zu beheben, stelle sicher, dass der Inhaltstyp korrekt formatiert ist, und nimm die SendMessage-Aktion in die Zuweisungsvorlage auf.

Wenn du das AWS-JSON-Protokoll verwendest, erhältst du diesen Fehler, wenn du die Header Inhaltstyp und X-Amz-Target nicht sendest oder nicht richtig konfigurierst. Um diesen Fehler zu beheben, konfiguriere den Inhaltstyp-Header als „application/x-amz-json-1.0“ und den X-Amz-Target-Header als AmazonSQS.{SQS-Action} und nimm beide Header in die Anforderung auf.

„AccessDenied“-Fehler

Du kannst sowohl vom AWS-Abfrageprotokoll als auch vom AWS-JSON-Protokoll einen „AccessDenied“-Fehler erhalten.

Dieser Fehler tritt auf, wenn für die Ausführungsrolle der API-Integration nicht die sqs:SendMessage-Berechtigung zum Senden von Nachrichten an die SQS-Warteschlange festgelegt ist.

Du erhältst diesen Fehler auch, wenn du das AWS-Abfrageprotokoll verwendest und nicht unterstützte Sonderzeichen in der Nutzdatenzeichenfolge des Anforderungstexts übergibst. Du musst Sonderzeichen codieren, um diesen Fehler zu vermeiden. Füge der Zuweisungsvorlage die Funktion $util.urlEncode() hinzu, um den Anforderungstext von einer Zeichenfolge in ein codiertes Format zu konvertieren. Im Folgenden findest du ein Beispiel für eine Zuordnungsvorlage:

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

Wenn du eine Amazon-SQS-First-In-First-Out (FIFO)-Warteschlange verwendest, stelle sicher, dass du entweder das MessageGroupID- oder das MessageDeduplicationID-Attribut angeben. Im Folgenden findest du ein Beispiel für eine FIFO-Zuordnungsvorlage:

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

**Hinweis:**Ersetze your-msg-group-id durch deine Nachrichtengruppen-ID und your-msg-dedup-id durch deine Nachrichtendeduplizierungs-ID.

Das folgende Beispiel enthält die erforderlichen Berechtigungen zum Senden von Nachrichten an die SQS-Warteschlange:

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

Hinweis: Ersetze example-region durch deine Region, example-account-id durch deine Konto-ID und example-sqs-queue-name durch deinen SQS-Warteschlangennamen.

„KMS.AccessDeniedException“-Fehler

Du kannst sowohl vom AWS-Abfrageprotokoll als auch vom AWS-JSON-Protokoll einen „KMS.AccessDeniedException“-Fehler erhalten.

Dieser Fehler tritt auf, wenn die Ausführungsrolle der API-Integration keine Operationen über den AWS Key Management Service (AWS KMS) ausführen kann. Konfiguriere Berechtigungen für die Ausführung von Operationen mit den AWS-KMS-Schlüsseln, die an die serverseitige verschlüsselte Amazon SQS-Warteschlange angefűgt sind, um diesen Fehler zu beheben.

Das folgende Beispiel enthält die erforderlichen Berechtigungen zum Ausführen von Operationen mit den KMS-Schlüsseln, die an die SQS-Warteschlange angefügt sind:

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

Hinweis: Ersetze example-account-id durch deine Konto-ID und example-api-gw-integration-execution-role durch den Namen deiner Ausführungsrolle.

„MalformedQueryString“-Fehler

Du kannst sowohl vom AWS-Abfrageprotokoll als auch vom AWS-JSON-Protokoll den „malformedQueryString“-Fehler erhalten.

Dieser Fehler tritt auf, wenn Sonderzeichen in der Nutzdatenzeichenfolge des Anforderungstextes enthalten sind. Füge der Zuweisungsvorlage die Funktion $util.urlEncode() hinzu, um den Anforderungstext von einer Zeichenfolge in ein codiertes Format zu konvertieren. Im Folgenden findest du ein Beispiel für eine Zuordnungsvorlage:

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

„SignatureDoesNotMatch“-Fehler

Du kannst einen „SignatureDoesNotMatch“-Fehler erhalten, wenn du das AWS-Abfrageprotokoll verwendest.

Dieser Fehler tritt auf, wenn die HTTP-Methode der Integrationsanfrage auf GET statt auf POST gesetzt ist. Setze die HTTP-Methode auf POST, um diesen Fehler zu beheben.

„InvalidAddress“-Fehler

Du kannst einen „InvalidAddress“-Fehler erhalten, wenn du das AWS-JSON-Protokoll verwendest.

Dieser Fehler tritt auf, wenn die SQS-Warteschlangen-URL in den Textnutzdaten falsch ist. Um diesen Fehler zu beheben, überprüfe die Warteschlangen-URL der SQS-Warteschlange, auf die der API-Aufruf abzielt.

„SerializationException“-Fehler

Du kannst einen „SerializationException“-Fehler erhalten, wenn du das AWS-JSON-Protokoll verwendest.

Dieser Fehler tritt auf, wenn die Textnutzdaten kein gültiges JSON sind. Beispielsweise könnte deine JSON ein fehlendes oder zusätzliches Komma oder eine fehlende oder zusätzliche geschweifte Klammer enthalten. Um diesen Fehler zu beheben, überarbeite deine JSON-Datei in ein gültiges Format.

„MissingRequiredParameterException“-Fehler

Du kannst einen „MissingRequiredParameterException“-Fehler erhalten, wenn du das AWS-JSON-Protokoll verwendest.

Dieser Fehler tritt auf, wenn du einen oder mehrere der erforderlichen Parameter nicht in die Textnutzdaten aufnimmst. Die erforderlichen Parameter hängen vom API-Aufruf ab. Beispielsweise erhältst du diesen Fehler bei einem SendMessage-API-Aufruf, wenn der Parameter MessageBody fehlt. Die erforderlichen Parameter und Syntax findest du in der SQS-API-Referenz.

Ähnliche Informationen

Integrieren des Amazon API Gateway mit Amazon SQS, um asynchrone REST-APIs zu verarbeiten

Wie verwende ich API Gateway als Proxy für einen anderen AWS-Service?