Como faço para integrar uma API REST do API Gateway com o Amazon SQS e resolver erros comuns?

Resolução

Para criar uma solução integrada, configure as APIs REST do API Gateway para trabalhar com o Amazon SQS.

Configure a API REST e uma integração com o Amazon SQS

Conclua as seguintes etapas:

1. Crie uma fila do SQS.
2. Crie um perfil do AWS Identity and Access Management (IAM) e, em seguida, anexe uma política do Amazon SQS com uma permissão ** SendMessage**. A política permite que você publique mensagens da API no 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"
         ]
       }
     ]
   }

   Observação: substitua example-region pela sua região da AWS, example-account-id pelo ID da sua conta da AWS e example-sqs-queue-name pelo nome da sua fila SQS.
3. Crie uma API REST no API Gateway.
4. No console do API Gateway, crie uma integração do Amazon SQS para sua API REST.
5. (Opcional) Crie um recurso de API REST ou um Método de API REST:
   Na tela Recursos, selecione Criar método.
   Em Tipo de método, escolha POST.
   Em Tipo de integração, selecione AWS Service.
   Em Região da AWS, escolha sua região.
   Em Serviço da AWS, escolha Simple Queue Service (SQS).
   (Opcional) Em Subdomínio da AWS, insira o subdomínio usado pelo serviço da AWS. Verifique a documentação do serviço da AWS para confirmar a disponibilidade de um subdomínio. Para a configuração de exemplo do Amazon SQS, mantenha isso em branco.
   Em Método HTTP, escolha POST.
   Em Tipo de ação, escolha Usar substituição de caminho.
   Em Substituição de caminho (opcional), digite o ID da sua conta e o nome da fila do SQS no seguinte formato: exemplo-id-conta/exemplo-nome-fila-sqs. Por exemplo: 1234567890/MySQSStandardQueue.
   Em Perfil de execução, insira o ARN do perfil do IAM.
   Em Tempo limite padrão, escolha uma opção para sua configuração.
   Continue a inserir suas informações de integração da API REST.
   Escolha o método POST Solicitação de integração.
   Escolha Editar.
   Em Solicitar passagem do corpo, selecione a opção de acordo com suas necessidades.
   Expanda Parâmetros de cabeçalhos de solicitações de URL.
   Escolha Adicionar parâmetro de cabeçalho de solicitação.
   Em Nome, insira Content-Type.
   Em Mapeado de, insira 'application/x-www-form-urlencoded'.
   Expanda Modelos de mapeamento.
   Escolha Adicionar modelo de mapeamento.
   Em Content-Type, insira application/json.
   Para o modelo, insira Action=SendMessage&MessageBody=$input.body e escolha Salvar.
6. Implante a API REST.
7. Para testar a configuração, envie a seguinte solicitação ao 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"
     }'

   Observação: substitua example-api-id pela ID da API, example-region pela sua região, example-stage pelo nome do estágio de teste e example-resource pelo nome do recurso.
   Quando a integração for bem-sucedida, sua resposta será semelhante à seguinte:

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

Resolver erros comuns

Para solucionar erros comuns, conclua as tarefas com base na mensagem de erro que você receber.

Erro UnknownOperationException

Ocorre um erro UnknownOperationException quando você não configura Content-Type como "application/x-www-form-urlencoded" no cabeçalho HTTP da solicitação de integração. O erro UnknownOperationException também ocorre quando você não adiciona a ação SendMessage ao modelo de mapeamento da solicitação de integração. Para resolver esse erro, certifique-se de que Content-Type esteja formatado corretamente e inclua a ação SendMessage no modelo de mapeamento.

Erro AccessDenied

Veja a seguir um exemplo de erro AccessDenied:

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

Ocorre um erro AccessDenied quando a função de execução da integração da API não tem a permissão sqs:SendMessage definida para enviar mensagens à fila do SQS. O erro AccessDenied também pode ocorrer quando você transmite caracteres especiais, como "&" e "%", na carga útil do corpo da solicitação. Você deve codificar os caracteres especiais a serem transmitidos. Adicione a função $util.urlEncode() no modelo de mapeamento para converter o corpo da solicitação de uma string em um formato codificado. Veja a seguir um exemplo de modelo de mapeamento:

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

O exemplo a seguir inclui as permissões necessárias para enviar mensagens à fila do SQS:

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

Observação: substitua example-region pela sua região, example-account-id pelo ID da sua conta e example-sqs-queue-name pelo nome da sua fila SQS.

Erro KMS.AccessDeniedException

Veja a seguir dois exemplos de erros 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"
}

Ocorre um erro KMS.AccessDeniedException quando o perfil de execução de integração da API não pode realizar operações por meio do AWS Key Management Service (AWS KMS). Você deve configurar as permissões para executar operações nas chaves do AWS KMS que estão anexadas à fila criptografada no lado do servidor do Amazon SQS.

O exemplo a seguir inclui as permissões necessárias para realizar operações nas chaves do KMS que estão anexadas à fila do 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": "*"
}

Observação: substitua example-account-id pela ID da sua conta e example-api-gw-integration-execution-role pelo nome do seu perfil de execução.

Informações relacionadas

Criar uma API com integração personalizada de HTTP