Come posso integrare una REST API di Gateway API con Amazon SQS e risolvere gli errori più comuni?

Risoluzione

Per integrare una REST API di Gateway API con Amazon SQS, utilizza il protocollo di query AWS o il protocollo AWS JSON.

Utilizza il protocollo di query AWS per integrare una REST API di Gateway API con Amazon SQS

Completa i seguenti passaggi:

1. Crea una coda SQS.

2. Crea un ruolo AWS Identity and Access Management (AWS IAM) per un servizio AWS.
   Nota: per Servizio o caso d'uso, scegli Gateway API.

3. Per consentirti di pubblicare messaggi dall'API su Amazon SQS, collega la seguente policy per Amazon SQS con le autorizzazioni SendMessage:

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

   Nota: sostituisci example-region con la tua Regione AWS, example-account-id con l'ID del tuo account AWS e example-sqs-queue-name con il nome della tua coda SQS.

4. Crea una REST API in Gateway API.

5. Nella console Gateway API, crea un'integrazione di Amazon SQS per la REST API.

6. Crea una risorsa o un metodo per la REST API:
   Nella pagina Risorse scegli Crea metodo.
   Per Tipo di metodo, scegli POST.
   Per Tipo di integrazione, scegli Servizio AWS.
   Per Regione AWS, scegli la tua Regione.
   Per Servizio AWS, scegli Simple Queue Service (SQS).
   (Facoltativo) In Sottodominio AWS, inserisci il sottodominio utilizzato dal servizio AWS. Consulta la documentazione del servizio per verificare la disponibilità di un sottodominio. Per la configurazione di esempio di Amazon SQS, lascia il campo vuoto.
   Per Metodo HTTP, scegli POST.
   Per Tipo di operazione, scegli Utilizza sostituzione percorso.
   In Sostituzione percorso (facoltativo), inserisci l'ID dell'account e il nome della coda SQS nel seguente formato: example-account-id/example-sqs-queue-name. Per esempio: 1234567890/MySQSStandardQueue.
   In Ruolo di esecuzione, inserisci l'ARN del ruolo IAM.
   Per Timeout di integrazione, scegli un'opzione per la configurazione.
   Continua a inserire le informazioni per l'integrazione della REST API.
   Scegli Crea metodo.
   Scegli il metodo POST Richiesta di integrazione.
   Scegli Modifica.
   Per Richiedi passthrough corpo, scegli l'opzione più adatta alle necessità del caso d'uso.
   Espandi Parametri delle intestazioni delle richieste URL.
   Scegli Aggiungi parametro dell'intestazione della richiesta.
   In Nome, inserisci Content-Type.
   In Mappato da, inserisci 'application/x-www-form-urlencoded'.
   Espandi Modelli di mappatura.
   Scegli Aggiungi modello di mappatura.
   In Content-Type, inserisci application/json.
   Per il modello, inserisci Action=SendMessage&MessageBody=$input.body, quindi scegli Salva.

7. Distribuisci la REST API.

8. Per verificare la configurazione, invia la seguente richiesta a Gateway API:

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

   Nota: sostituisci example-api-id con l’ID della tua API, example-region con la tua Regione, example-stage con il nome della tua fase di test e example-resource con il nome della tua risorsa.
   Esempio di risposta per un'integrazione riuscita:

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

Per integrare una REST API di Gateway API con Amazon SQS, puoi utilizzare il protocollo AWS JSON

Completa i seguenti passaggi:

1. Crea una coda SQS.

2. Crea un ruolo IAM per un servizio AWS.
   Nota: per Servizio o caso d'uso, scegli Gateway API.

3. Per consentirti di pubblicare messaggi dall'API su Amazon SQS, collega la seguente policy per Amazon SQS con le autorizzazioni SendMessage:

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

   Nota: sostituisci example-region con la tua Regione AWS, example-account-id con l'ID del tuo account AWS e example-sqs-queue-name con il nome della tua coda SQS.

4. Crea una REST API in Gateway API.

5. Nella console Gateway API, crea un'integrazione di Amazon SQS per la REST API.

6. Crea una risorsa o un metodo per la REST API:
   Nella pagina Risorse scegli Crea metodo.
   Per Tipo di metodo, scegli POST.
   Per Tipo di integrazione, scegli Servizio AWS.
   Per Regione AWS, scegli la tua Regione.
   Per Servizio AWS, scegli Simple Queue Service (SQS).
   Per Sottodominio AWS, lascia il campo vuoto. È un parametro facoltativo in cui inserire il sottodominio utilizzato da un servizio AWS. Consulta la documentazione del servizio per verificare la disponibilità di un sottodominio.
   Per Metodo HTTP, scegli POST.
   Per Tipo di operazione, scegli Utilizza sostituzione percorso.
   In Sostituzione percorso, inserisci il carattere /.
   In Ruolo di esecuzione, inserisci l'ARN del ruolo IAM.
   Per Timeout predefinito, scegli un'opzione per la configurazione.
   Espandi Intestazioni di richiesta HTTP.
   Scegli Aggiungi intestazione.
   In Nome, inserisci Content-Type.
   Scegli Aggiungi intestazione.
   In ** Nome**, inserisci X-Amz-Target.
   Seleziona Crea metodo.
   Scegli il metodo POST Richiesta di integrazione.
   Scegli Modifica.
   Per Richiedi passthrough corpo, lascia come opzione predefinita When no template matches the request content-type header (Quando nessun modello corrisponde all'intestazione Content-Type della richiesta).
   Espandi Parametri delle intestazioni delle richieste URL.
   Scegli Aggiungi parametro dell'intestazione della richiesta.
   In Nome, inserisci Content-Type.
   In Mappato da, inserisci method.request.header.Content-Type .
   Scegli Aggiungi parametro dell'intestazione della richiesta.
   In ** Nome**, inserisci X-Amz-Target.
   In Mappato da, inserisci method.request.header.X-Amz-Target.
   Scegli Salva.

7. Distribuisci la REST API.

8. Per verificare la configurazione, invia la seguente richiesta a Gateway API:

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

   Nota: sostituisci example-api-id con l’ID della tua API, example-region con la tua Regione, example-stage con il nome della tua fase di test e example-resource con il nome della tua risorsa. Per trovare il valore QueueUrl, controlla i dettagli della coda Amazon SQS.

Esempio di risposta per un'integrazione riuscita:

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

Nota: la risposta prevista dal protocollo AWS JSON è diversa da quella del protocollo AWS Query, anche per la stessa chiamata API.

Risolvi gli errori SQS più comuni

Per risolvere gli errori più comuni di Amazon SQS, segui questi passaggi di risoluzione a seconda del messaggio di errore che hai ricevuto.

Errore "UnknownOperationException"

Puoi ricevere un errore "UnknownOperationException" sia dal protocollo AWS Query che dal protocollo AWS JSON.

Se utilizzi il protocollo di query AWS, questo errore si verifica quando non configuri Content-Type come "application/x-www-form-urlencoded" nell'intestazione HTTP della richiesta di integrazione. L’errore viene visualizzato anche quando non aggiungi l'azione SendMessage al modello di mappatura della richiesta di integrazione. Per risolverlo, assicurati di formattare correttamente Content-Type e di includere l'azione SendMessage nel modello di mappatura.

Se utilizzi il protocollo AWS JSON, ricevi questo errore quando non invii o non configuri correttamente le intestazioni Content-Type e X-Amz-Target. Per risolverlo, configura l'intestazione Content-Type come "application/x-amz-json-1.0" e l'intestazione X-Amz-Target come AmazonSQS.{SQS-Action} e includi entrambe le intestazioni nella richiesta.

Errore "AccessDenied"

Puoi ricevere un errore "AccessDenied" sia dal protocollo AWS Query che dal protocollo AWS JSON.

L'errore si verifica quando il ruolo di esecuzione dell'integrazione dell'API non ha l'autorizzazione sqs:SendMessage impostata per inviare messaggi alla coda SQS.

L’errore si verifica anche quando utilizzi il protocollo AWS Query e passi caratteri speciali non supportati nella stringa di payload del corpo della richiesta. Devi codificare i caratteri speciali per evitare l’errore. Aggiungi la funzione $util.urlEncode() nel modello di mappatura per convertire il corpo della richiesta da una stringa a un formato codificato. Di seguito è riportato un esempio di modello di mappatura:

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

Se utilizzi una coda FIFO (First-In-First-Out) di Amazon SQS, assicurati di includere l'attributo MessageGroupId o MessageDeduplicationId. Di seguito è riportato un esempio di modello di mappatura FIFO:

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

Nota: sostituisci your-msg-group-id con l'ID del tuo gruppo di messaggi e your-msg-dedup-id con il tuo ID di deduplicazione dei messaggi.

L'esempio seguente include le autorizzazioni necessarie per inviare messaggi alla coda SQS:

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

Nota: sostituisci example-region con la tua Regione, example-account-id con l’ID del tuo account e example-sqs-queue-name il nome della tua coda SQS.

Errore "KMS.AccessDeniedException"

Puoi ricevere un errore "KMS.AccessDeniedException" sia dal protocollo AWS Query che dal protocollo AWS JSON.

L'errore si verifica quando il ruolo di esecuzione dell'integrazione dell'API non è in grado di eseguire operazioni tramite il Servizio AWS di gestione delle chiavi (AWS KMS). Per risolverlo, configura le autorizzazioni per eseguire operazioni sulle chiavi AWS KMS collegate alla coda crittografata lato server di Amazon SQS.

Nell'esempio seguente sono mostrate le autorizzazioni necessarie per eseguire operazioni sulle chiavi KMS collegate alla coda 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": "*"
}

Nota: sostituisci example-account-id con l'ID del tuo account e example-api-gw-integration-execution-role con il nome del tuo ruolo di esecuzione.

Errore "MalformedQueryString"

Puoi ricevere un errore "MalformedQueryString" sia dal protocollo di query AWS che dal protocollo AWS JSON.

L'errore si verifica quando nella stringa di payload del corpo della richiesta sono presenti caratteri speciali. Aggiungi la funzione $util.urlEncode() nel modello di mappatura per convertire il corpo della richiesta da una stringa a un formato codificato. Di seguito è riportato un esempio di modello di mappatura:

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

Errore "SignatureDoesNotMatch"

Puoi ricevere un errore "SignatureDoesNotMatch" quando utilizzi il protocollo AWS Query.

L'errore si verifica quando il metodo HTTP della richiesta di integrazione è impostato su GET anziché su POST. Per risolverlo, imposta il metodo HTTP su POST.

Errore "InvalidAddress"

Puoi ricevere un errore "InvalidAddress" quando utilizzi il protocollo AWS JSON.

L'errore si verifica quando l'URL della coda SQS nel payload del corpo non è corretto. Per risolverlo, controlla l'URL della coda SQS a cui è destinata la chiamata API.

Errore "SerializationException"

Puoi ricevere un errore "SerializationException" quando utilizzi il protocollo AWS JSON.

L'errore si verifica quando il payload del corpo non è un JSON valido. Per esempio, il JSON potrebbe avere una virgola in meno o in più oppure una parentesi graffa in meno o in più. Per risolverlo, modifica il JSON in un formato valido.

Errore "MissingRequiredParameterException"

Puoi ricevere un errore "MissingRequiredParameterException" quando utilizzi il protocollo AWS JSON.

L'errore si verifica quando non includi uno o più parametri richiesti nel payload del corpo. I parametri richiesti dipendono dalla chiamata API. Per esempio, ricevi questo errore da una chiamata API SendMessage quando manca il parametro MessageBody. Consulta le informazioni sulle API di SQS per i parametri e la sintassi richiesti.

Informazioni correlate

Integra Gateway Amazon API con Amazon SQS per gestire le REST API asincrone

Come posso usare Gateway API come proxy per un altro servizio AWS?