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

Risoluzione

Per integrare un'API REST di API Gateway con Amazon SQS, scegli uno dei seguenti metodi:

• Utilizza il protocollo AWS Query
• Utilizza il protocollo AWS JSON

Utilizza il protocollo AWS Query

Per integrare un'API REST di API Gateway con Amazon SQS, puoi utilizzare il protocollo AWS Query. A tale scopo, completa i seguenti passaggi:

1. Crea una coda SQS.
2. Crea un ruolo AWS Identity and Access Management (IAM), quindi collega una policy Amazon SQS con un'autorizzazione SendMessage. La policy consente di pubblicare messaggi dall'API su 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"
      ]
    }
  ]
}

Nota: sostituisci a example-region la tua regione AWS, a example-account-id il tuo ID account AWS e a example-sqs-queue-name il nome coda SQS.

1. Crea un’API REST in API Gateway.
2. Nella console di API Gateway, crea un'integrazione Amazon SQS per l’API REST.
3. Crea una risorsa API REST o un metodo API REST:
   Nella schermata 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) Per Sottodominio AWS, inserisci il sottodominio utilizzato dal servizio AWS. Consulta la documentazione del servizio AWS per verificare la disponibilità di un sottodominio. Per la configurazione di esempio di Amazon SQS, lascia il campo vuoto.
   Per Metodo HTTP, scegli PUT.
   Per Tipo di operazione, scegli Utilizza sostituzione percorso.
   Per Sostituzione percorso (opzionale), inserisci l'ID dell'account e il nome coda SQS nel seguente formato: example-account-id/example-sqs-queue-name. Per esempio: 1234567890/MySQSStandardQueue.
   Per Ruolo di esecuzione, inserisci l'ARN del ruolo IAM.
   Per Timeout predefinito, scegli un'opzione per la configurazione.
   Continua a inserire le informazioni per l'integrazione dell’API REST.
   Scegli il metodo POST Richiesta di integrazione.
   Scegli Modifica.
   Per Richiedi passthrough corpo, scegli l'opzione più adatta alle tue necessità.
   Espandi Parametri delle intestazioni delle richieste URL.
   Scegli Aggiungi parametro dell'intestazione della richiesta.
   Per Nome, inserisci Content-Type.
   Per Mappato da, inserisci 'application/x-www-form-urlencoded'.
   Espandi Modelli di mappatura.
   Scegli Aggiungi modello di mappatura.
   Per Content-Type, inserisci application/json.
   Per il modello, inserisci Action=SendMessage&MessageBody=$input.body, quindi scegli Salva.
4. Distribuisci l’API REST.
5. Per testare la configurazione, invia la seguente richiesta ad 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"  
  }'

Nota: sostituisci a example-api-id l’ID della tua API, a example-region la tua regione, a example-stage il nome della fase di test e a example-resource il nome della risorsa.

Quando l'integrazione si conclude correttamente, la risposta è simile alla seguente:

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

Utilizza il protocollo AWS JSON

Per integrare un'API REST di API Gateway con Amazon SQS, puoi utilizzare il protocollo AWS JSON. A tale scopo, completa i seguenti passaggi:

1. Crea una coda SQS.
2. Crea un ruolo AWS IAM, quindi allega una policy Amazon SQS con un'autorizzazione SendMessage. La policy consente di pubblicare messaggi dall'API su 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"  
      ]  
    }  
  ]  
}

Nota: sostituisci a example-region la tua regione AWS, a example-account-id il tuo ID account AWS e a example-sqs-queue-name il nome coda SQS.

1. Crea un’API REST in API Gateway.
2. Nella console di API Gateway, crea un'integrazione Amazon SQS per l’API REST.
3. Crea una risorsa API REST o un metodo API REST:
   Nella schermata 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 il sottodominio ** AWS**, lascia il campo vuoto. Si tratta di un parametro opzionale in cui si inserisce il sottodominio utilizzato da un servizio AWS. Consulta la documentazione del servizio AWS per verificare la disponibilità di un sottodominio.
   Per Metodo HTTP, scegli PUT.
   Per Tipo di operazione, scegli Utilizza sostituzione percorso.
   Per Sostituzione percorso, inserisci il carattere /.
   Per Ruolo di esecuzione, inserisci l'ARN del ruolo IAM.
   Per Timeout predefinito, scegli un'opzione per la configurazione.
   Espandi le intestazioni delle richieste HTTP.
   Scegli Aggiungi intestazione.
   Per Nome, inserisci Content-Type.
   Scegli Aggiungi intestazione.
   Per ** Nome**, inserisci **X-Amz-Target .
   Seleziona il metodo di creazione.
   Scegli il metodo POST Richiesta di integrazione.
   Scegli Modifica.
   Per Richiedi passthrough corpo, lascia come opzione predefinita Quando nessun modello corrisponde all'intestazione Content-Type della richiesta.
   Espandi Parametri delle intestazioni delle richieste URL.
   Scegli Aggiungi parametro dell'intestazione della richiesta.
   Per Nome, inserisci Content-Type.
   Per Mappato da, inserisci method.request.header.Content-Type .
   Scegli Aggiungi parametro dell'intestazione della richiesta.
   Per ** Nome, inserisci **X-Amz-Target **.
   Per Mappato da, inserisci method.request.header.X-Amz-Target.
   Scegli Salva.
4. Distribuisci l’API REST.
5. Per testare la configurazione, invia la seguente richiesta ad 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"
}'

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

Quando l'integrazione si conclude correttamente, la risposta è simile alla seguente:

{"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. Consulta le informazioni sulle API di SQS per esempi di risposte di ciascun protocollo.

Risolvi gli errori più comuni

Errore UnknownOperationException

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

Se utilizzi il protocollo AWS Query, ricevi un errore UnknownOperationException 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 risolvere l’errore, assicurati di formattare correttamente Content-Type e includere l'azione SendMessage nel modello di mappatura.

Se utilizzi il protocollo AWS JSON, ricevi un errore UnknownOperationException quando non invii o non configuri correttamente le intestazioni Content-Type e X-Amz-Target. Per risolvere l’errore, configura l'intestazione Content-Type come “application/x-amz-json-1.0” e configura 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.

Si verifica un errore AccessDenied quando il ruolo di esecuzione dell'integrazione 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. È necessario 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)

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 a example-region la tua regione, a example-account-id l’ID del tuo account e a example-sqs-queue-name il nome coda SQS.

Errore KMS.AccessDeniedException

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

Si verifica un errore KMS.AccessDeniedException quando il ruolo di esecuzione dell'integrazione API non può eseguire operazioni tramite il servizio AWS di gestione delle chiavi (AWS KMS). Per risolvere l’errore, configura le autorizzazioni per eseguire operazioni sulle chiavi AWS KMS collegate alla coda crittografata lato server di Amazon SQS.

Nel seguente esempio 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 a example-account-id l'ID del tuo account e a example-api-gw-integration-execution-role il nome del tuo ruolo di esecuzione.

**Errore SignatureDoesNotMatch **

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

Si verifica un errore SignatureDoesNotMatch quando il metodo HTTP della **richiesta di integrazione ** è impostato su GET anziché su POST. Per risolvere l’errore, imposta il metodo ** HTTP ** su POST.

Errore InvalidAddress

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

Si verifica un errore InvalidAddress quando l'URL della coda SQS nel payload body non è corretto. Per risolvere l’errore, 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.

Si verifica un errore SerializationException quando il payload del corpo non è valido per JSON. Per esempio, il tuo JSON potrebbe avere una virgola in meno o in più oppure una parentesi graffa in meno o in più. Per risolvere l’errore, utilizza uno strumento di formattazione JSON per trovare gli errori di sintassi del tuo JSON.

Errore MissingRequiredParameterException

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

Si verifica un errore MissingRequiredParameterException quando non si includono 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 Amazon API Gateway con Amazon SQS per gestire le API REST asincrone

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