AWS re:Post Knowledge Center Feedback Survey

Help us improve the AWS re:Post Knowledge Center by sharing your feedback in a brief survey. Your input can influence how we create and update our content to better support your AWS journey.

API Gateway REST API를 Amazon SQS와 통합하고 일반적인 오류를 해결하려면 어떻게 해야 합니까?

7분 분량

Amazon API Gateway REST API를 Amazon Simple Queue Service(Amazon SQS)와 통합하려고 하는데 통합 오류를 해결하고 싶습니다.

해결 방법

API Gateway REST API를 Amazon SQS와 통합하려면 AWS 쿼리 프로토콜 또는 AWS JSON 프로토콜을 사용하십시오.

AWS 쿼리 프로토콜을 사용하여 API Gateway REST API를 Amazon SQS와 통합

다음 단계를 완료하십시오.

SQS 대기열을 만듭니다.
AWS 서비스에 대한 AWS Identity and Access Management(IAM) 역할을 만듭니다.
참고: 서비스 또는 사용 사례에서 API Gateway를 선택합니다.

API에서 Amazon SQS로 메시지를 게시할 수 있도록 하려면 SendMessage 권한과 함께 다음 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"
      ]
    }
  ]
}

참고: example-region을 AWS 리전으로, example-account-id를 AWS 계정 ID로, example-sqs-queue-name을 SQS 대기열 이름으로 바꾸십시오.

API Gateway에서 REST API를 만듭니다.
API Gateway 콘솔에서 REST API용 Amazon SQS 통합을 만듭니다.
REST API 리소스 또는 REST API 메서드를 만듭니다.
리소스 페이지에서 메서드 생성을 선택합니다.
메서드 유형에서 POST를 선택합니다.
통합 유형에서 AWS 서비스를 선택합니다.
AWS 리전에서 해당 리전을 선택합니다.
AWS 서비스에서 **Simple Queue Service(SQS)**를 선택합니다.
(선택 사항) AWS 하위 도메인에 AWS 서비스에서 사용하는 하위 도메인을 입력합니다. 서비스 문서를 참조하여 하위 도메인의 가용성을 확인합니다. Amazon SQS 예제 설정 필드는 비워 둡니다.
HTTP 메서드에서 POST를 선택합니다.
작업 유형에서 경로 재정의 사용을 선택합니다.
**경로 재정의(선택 사항)**에 계정 ID와 SQS 대기열 이름을 example-account-id/example-sqs-queue-name 형식으로 입력합니다. 예: 1234567890/MySQSStandardQueue.
실행 역할에 IAM 역할의 ARN을 입력합니다.
통합 시간 초과에서 설정 옵션을 선택합니다.
계속해서 REST API 통합 정보를 입력합니다.
메서드 생성을 선택합니다.
POST 메서드 통합 요청을 선택합니다.
편집을 선택합니다.
요청 본문 패스스루에서 요구 사항에 맞는 옵션을 선택합니다.
URL 요청 헤더 파라미터를 확장합니다.
요청 헤더 파라미터 추가를 선택합니다.
이름에 Content-Type을 입력합니다.
다음에서 매핑됨에 **'application/x-www-form-urlencoded'**를 입력합니다.
매핑 템플릿을 확장합니다.
매핑 템플릿 추가를 선택합니다.
Content-Type에 application/json을 입력합니다.
템플릿에 Action=SendMessage&MessageBody=$input.body를 입력하고 저장을 선택합니다.
REST API를 배포합니다.

설정을 테스트하려면 다음 요청을 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"  
  }'

참고: example-api-id를 API ID로, example-region을 해당 리전으로, example-stage를 테스트 스테이지 이름으로, example-resource를 리소스 이름으로 바꾸십시오.
성공적인 통합 응답의 예:

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

AWS JSON 프로토콜을 사용하여 API Gateway REST API를 Amazon SQS와 통합

다음 단계를 완료하십시오.

SQS 대기열을 만듭니다.
AWS 서비스에 대한 IAM 역할을 만듭니다.
참고: 서비스 또는 사용 사례에서 API Gateway를 선택합니다.

API에서 Amazon SQS로 메시지를 게시할 수 있도록 하려면 SendMessage 권한과 함께 다음 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"  
      ]  
    }  
  ]  
}

참고: example-region을 AWS 리전으로, example-account-id를 AWS 계정 ID로, example-sqs-queue-name을 SQS 대기열 이름으로 바꾸십시오.

API Gateway에서 REST API를 만듭니다.
API Gateway 콘솔에서 REST API용 Amazon SQS 통합을 만듭니다.
REST API 리소스 또는 REST API 메서드를 만듭니다.
리소스 페이지에서 메서드 생성을 선택합니다.
메서드 유형에서 POST를 선택합니다.
통합 유형에서 AWS 서비스를 선택합니다.
AWS 리전에서 해당 리전을 선택합니다.
AWS 서비스에서 **Simple Queue Service(SQS)**를 선택합니다.
AWS 하위 도메인의 경우 필드를 비워 둡니다. 이 파라미터는 AWS 서비스가 사용하는 하위 도메인을 입력할 수 있는 선택적 파라미터입니다. 서비스 문서를 참조하여 하위 도메인의 가용성을 확인합니다.
HTTP 메서드에서 POST를 선택합니다.
작업 유형에서 경로 재정의 사용을 선택합니다.
경로 재정의에 / 문자를 입력합니다.
실행 역할에 IAM 역할의 ARN을 입력합니다.
기본 시간 초과에서 설정 옵션을 선택합니다.
HTTP 요청 헤더를 확장합니다.
헤더 추가를 선택합니다.
이름에 Content-Type을 입력합니다.
헤더 추가를 선택합니다.
이름에 X-Amz-Target을 입력합니다.
메서드 생성을 선택합니다.
POST 메서드 통합 요청을 선택합니다.
편집을 선택합니다.
요청 본문 패스스루의 경우 기본 옵션인 When no template matches the request content-type header(요청 content-type 헤더와 일치하는 템플릿이 없는 경우)로 둡니다.
URL 요청 헤더 파라미터를 확장합니다.
요청 헤더 파라미터 추가를 선택합니다.
이름에 Content-Type을 입력합니다.
다음에서 매핑됨에 method.request.header.Content-Type을 입력합니다.
요청 헤더 파라미터 추가를 선택합니다.
이름에 X-Amz-Target을 입력합니다.
다음에서 매핑됨에 method.request.header.X-Amz-Target을 입력합니다.
저장을 선택합니다.
REST API를 배포합니다.

설정을 테스트하려면 다음 요청을 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"
}'

참고: example-api-id를 API ID로, example-region을 해당 리전으로, example-stage를 테스트 스테이지 이름으로, example-resource를 리소스 이름으로 바꾸십시오. QueueUrl 값을 찾으려면 Amazon SQS 대기열 세부 정보를 확인하십시오.

성공적인 통합 응답의 예:

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

참고: AWS JSON 프로토콜의 예상 응답은 동일한 API 호출이라도 AWS 쿼리 프로토콜과 다릅니다.

일반적인 SQS 오류 해결

일반적인 Amazon SQS 오류를 해결하려면 수신한 오류 메시지에 대한 다음 문제 해결 단계를 따르십시오.

‘UnknownOperationException’ 오류

AWS 쿼리 프로토콜과 AWS JSON 프로토콜에서 모두 ‘UnknownOperationException’ 오류가 발생할 수 있습니다.

AWS 쿼리 프로토콜을 사용하는 경우 통합 요청 HTTP 헤더에서 Content-Type을 **‘application/x-www-form-urlencoded’**로 구성하지 않으면 이 오류가 발생합니다. 통합 요청의 매핑 템플릿에 SendMessage 작업을 추가하지 않은 경우에도 이 오류가 발생합니다. 이 오류를 해결하려면 Content-Type 형식이 올바른지 확인하고 매핑 템플릿에 SendMessage 작업을 포함해야 합니다.

AWS JSON 프로토콜을 사용하는 경우 Content-Type 및 X-Amz-Target 헤더를 전송하지 않거나 올바르게 구성하지 않으면 이 오류가 발생합니다. 이 오류를 해결하려면 Content-Type 헤더를 **‘application/x-amz-json-1.0’**으로 구성하고 X-Amz-Target 헤더를 **AmazonSQS.{SQS-Action}**으로 구성한 후 요청에 두 헤더를 모두 포함합니다.

‘AccessDenied’ 오류

AWS 쿼리 프로토콜과 AWS JSON 프로토콜에서 모두 ‘AccessDenied’ 오류가 발생할 수 있습니다.

이 오류는 API 통합 실행 역할에 SQS 대기열에 메시지를 전송할 수 있는 sqs:SendMessage 권한이 설정되어 있지 않으면 발생합니다.

AWS 쿼리 프로토콜을 사용하고 지원되지 않는 특수 문자를 요청 본문 페이로드 문자열에 전달하는 경우에도 이 오류가 발생합니다. 이 오류를 방지하려면 특수 문자를 인코딩해야 합니다. 매핑 템플릿에 $util.urlEncode() 함수를 추가하여 요청 본문을 문자열에서 인코딩된 형식으로 변환합니다. 다음은 매핑 템플릿 예제입니다.

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

Amazon SQS FIFO(선입선출) 대기열을 사용하는 경우 MessageGroupId 또는 MessageDeduplicationId 속성 중 하나를 포함해야 합니다. 다음은 FIFO 매핑 템플릿 예제입니다.

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

참고: your-msg-group-id를 메시지 그룹 ID로 바꾸고, your-msg-dedup-id를 메시지 중복 제거 ID로 바꾸십시오.

다음 예에는 SQS 대기열에 메시지를 보내는 데 필요한 권한이 포함되어 있습니다.

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

참고: example-region을 해당 리전으로, example-account-id를 계정 ID로, example-sqs-queue-name을 SQS 대기열 이름으로 바꾸십시오.

‘KMS.AccessDeniedException’ 오류

AWS 쿼리 프로토콜과 AWS JSON 프로토콜에서 모두 ‘KMS.AccessDeniedException’ 오류가 발생할 수 있습니다.

이 오류는 API 통합 실행 역할이 AWS Key Management Service(AWS KMS)를 통해 작업을 수행할 수 없을 때 발생합니다. 이 오류를 해결하려면 Amazon SQS 서버 측 암호화된 대기열에 연결된 AWS KMS 키에서 작업을 수행할 수 있는 권한을 구성합니다.

다음 예에는 SQS 대기열에 연결된 KMS 키에서 작업을 수행하는 데 필요한 권한이 포함되어 있습니다.

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

참고: example-account-id를 계정 ID로 바꾸고, example-api-gw-integration-execution-role을 실행 역할 이름으로 바꾸십시오.

‘MalformedQueryString’ 오류

AWS 쿼리 프로토콜과 AWS JSON 프로토콜에서 모두 ‘MalformedQueryString’ 오류가 발생할 수 있습니다.

이 오류는 요청 본문 페이로드 문자열에 특수 문자가 있을 때 발생합니다. 매핑 템플릿에 $util.urlEncode() 함수를 추가하여 요청 본문을 문자열에서 인코딩된 형식으로 변환합니다. 다음은 매핑 템플릿 예제입니다.

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

‘SignatureDoesNotMatch’ 오류

AWS 쿼리 프로토콜을 사용할 때 ‘SignatureDoesNotMatch’ 오류가 발생할 수 있습니다.

이 오류는 통합 요청의 HTTP 메서드가 POST 대신 GET으로 설정된 경우 발생합니다. 이 오류를 해결하려면 HTTP 메서드를 POST로 설정합니다.

‘InvalidAddress’ 오류

AWS JSON 프로토콜을 사용할 때 ‘InvalidAddress’ 오류가 발생할 수 있습니다.

이 오류는 본문 페이로드의 SQS 대기열 URL이 올바르지 않을 때 발생합니다. 이 오류를 해결하려면 API 호출이 대상으로 하는 SQS 대기열의 대기열 URL을 확인하십시오.

‘SerializationException’ 오류

AWS JSON 프로토콜을 사용할 때 ‘SerializationException’ 오류가 발생할 수 있습니다.

이 오류는 본문 페이로드가 유효한 JSON이 아닐 때 발생합니다. 예를 들어 JSON에 누락된 쉼표 또는 추가적인 쉼표가 있거나, 누락된 중괄호 또는 추가적인 중괄호가 있을 수 있습니다. 이 오류를 해결하려면 JSON을 유효한 형식으로 수정하십시오.

‘MissingRequiredParameterException’ 오류

AWS JSON 프로토콜을 사용할 때 ‘MissingRequiredParameterException’ 오류가 발생할 수 있습니다.

이 오류는 본문 페이로드에 필수 파라미터 중 하나 이상을 포함하지 않을 때 발생합니다. 필수 파라미터는 API 호출에 따라 달라집니다. 예를 들어 MessageBody 파라미터가 없으면 SendMessage API 호출에서 이 오류가 발생합니다. SQS API 참조에서 필수 파라미터 및 구문을 확인하십시오.

API Gateway REST API를 Amazon SQS와 통합하고 일반적인 오류를 해결하려면 어떻게 해야 합니까?

해결 방법

AWS 쿼리 프로토콜을 사용하여 API Gateway REST API를 Amazon SQS와 통합

AWS JSON 프로토콜을 사용하여 API Gateway REST API를 Amazon SQS와 통합

일반적인 SQS 오류 해결

관련 정보

관련 비디오

관련 콘텐츠