REST API를 Amazon SQS와 통합하고 일반적인 오류를 해결하려면 어떻게 해야 하나요?
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와 통합하려면 AWS 쿼리 프로토콜을 사용할 수 있습니다. 그러려면 다음 단계를 완료합니다.
- SQS 대기열을 생성합니다.
- AWS Identity and Access Management(AWS IAM) 역할을 생성하고 SendMessage 권한과 함께 Amazon SQS 정책을 연결합니다. 정책을 통해 API에서 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 서비스에서 사용하는 하위 도메인을 입력합니다. 하위 도메인의 가용성을 확인하려면 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와 통합하려면 AWS JSON 프로토콜을 사용할 수 있습니다. 그러려면 다음 단계를 완료합니다.
- SQS 대기열을 생성합니다.
- AWS IAM 역할을 생성한 다음, SendMessage 권한과 Amazon SQS 정책을 연결합니다. 정책을 통해 API에서 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 서비스가 사용하는 하위 도메인을 입력할 수 있는 선택적 파라미터입니다. 하위 도메인의 가용성을 확인하려면 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 API 참조를 참조하십시오.
일반적인 오류 해결
UnknownOperationException 오류
AWS 쿼리 프로토콜과 AWS JSON 프로토콜 모두에서 UnknownOperationException 오류가 발생할 수 있습니다.
AWS 쿼리 프로토콜을 사용하는 경우 통합 요청 HTTP 헤더에서 Content-Type을 **"application/x-www-form-urlencoded"**로 구성하지 않으면 UnknownOperationException이 발생합니다. 또한 통합 요청의 매핑 템플릿에 SendMessage 작업을 추가하지 않은 경우에도 이 오류가 발생합니다. 이 오류를 해결하려면 Content-Type 형식이 올바른지 확인하고 매핑 템플릿에 SendMessage 작업을 포함해야 합니다.
AWS JSON 프로토콜을 사용하는 경우 Content-Type 및 X-Amz-Target 헤더를 전송하지 않거나 올바르게 구성하지 않으면 UnknownOperationException 오류가 발생합니다. 이 오류를 해결하려면 Content-Type 헤더를 **"application/x-amz-json-1.0"**으로 구성하고 X-Amz-Target 헤더를 **AmazonSQS.{SQS-Action}**으로 구성한 후 요청에 두 헤더를 모두 포함시킵니다.
AccessDenied 오류
AWS 쿼리 프로토콜과 AWS JSON 프로토콜 모두에서 AccessDenied 오류가 발생할 수 있습니다.
SQS 대기열에 메시지를 전송할 수 있는 sqs:SendMessage 권한이 API 통합 실행 역할에 설정되어 있지 않으면 AccessDenied 오류가 발생합니다.
AWS 쿼리 프로토콜을 사용하고 지원되지 않는 특수 문자를 요청 본문 페이로드 문자열에 전달하는 경우에도 이 오류가 발생합니다. 이 오류를 방지하려면 특수 문자를 인코딩해야 합니다. 매핑 템플릿에 $util.urlEncode() 함수를 추가하여 요청 본문을 문자열에서 인코딩된 형식으로 변환합니다. 다음은 매핑 템플릿 예제입니다.
Action=SendMessage&MessageBody=$util.urlEncode($input.body)
다음 예시에 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)를 통해 작업을 수행할 수 없을 때 KMS.AccessDeniedException 오류가 발생합니다. 이 오류를 해결하려면 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을 해당 실행 역할 이름으로 바꾸십시오.
SignatureDoesNotMatch 오류
AWS 쿼리 프로토콜을 사용할 때 SignatureDoesNotMatch 오류가 발생할 수 있습니다.
통합 요청의 HTTP 메서드가 POST 대신 GET으로 설정된 경우 SignatureDoesNotMatch 오류가 발생합니다. 이 오류를 해결하려면 HTTP 메서드를 POST로 설정합니다.
InvalidAddress 오류
AWS JSON 프로토콜을 사용할 때 InvalidAddress 오류가 발생할 수 있습니다.
본문 페이로드의 SQS 대기열 URL이 올바르지 않으면 InvalidAddress 오류가 발생합니다. 이 오류를 해결하려면 API 호출이 대상으로 하는 SQS 대기열의 대기열 URL을 확인하십시오.
SerializationException 오류
AWS JSON 프로토콜을 사용할 때 SerializationException 오류가 발생할 수 있습니다.
본문 페이로드가 잘못된 JSON인 경우 SerializationException 오류가 발생합니다. 예를 들어 JSON에 누락된 쉼표 또는 추가적인 쉼표가 있거나, 누락된 중괄호 또는 추가적인 중괄호가 있을 수 있습니다. 이 오류를 해결하려면 JSON 포매터 도구를 사용하여 JSON에서 구문 오류를 찾으십시오.
MissingRequiredParameterException 오류
AWS JSON 프로토콜을 사용할 때 MissingRequiredParameterException 오류가 발생할 수 있습니다.
본문 페이로드에 필수 파라미터 중 하나 이상이 포함되어 있지 않으면 MissingRequiredParameterException 오류가 발생합니다. 필수 파라미터는 API 호출에 따라 달라집니다. 예를 들어 MessageBody 파라미터가 없으면 SendMessage API 호출에서 이 오류가 발생합니다. SQS API 참조에서 필수 파라미터와 구문을 확인하십시오.
관련 정보
관련 콘텐츠
AWS 공식업데이트됨 3년 전
