API Gateway를 다른 AWS 서비스의 프록시로 사용하려면 어떻게 해야 하나요?

8분 분량

Amazon API Gateway를 다른 AWS 서비스의 프록시로 사용하고 다른 서비스를 API Gateway와 통합하고 싶습니다.

간략한 설명

AWS 서비스 API는 기본적으로 HTTPS 요청을 할 수 있는 REST API입니다. 많은 AWS 서비스를 API Gateway와 통합할 수 있지만 설정 및 매핑은 특정 서비스 API에 따라 다릅니다.

다른 서비스를 API Gateway와 통합하려면 API Gateway에서 서비스 API로 HTTPS 요청을 작성하세요. 이렇게 하면 모든 요청 매개변수가 올바르게 매핑됩니다.

이 문서에서는 Amazon Simple Notification Service(Amazon SNS) Publish API를 API Gateway와 통합하기 위한 설정의 예제를 설명합니다. 이 예제를 다른 서비스를 통합하기 위한 개요로 사용하세요.

해결 방법

참고: AWS Command Line Interface(AWS CLI) 명령을 실행할 때 오류가 발생하는 경우, 최신 AWS CLI 버전을 사용하고 있는지 확인하세요.

필수 도구 및 리소스 설정

환경을 구성하고 사용 사례에 필요한 모든 AWS 리소스를 생성하세요. Amazon SNS 예제 설정의 경우 다음을 수행하세요.

AWS CLI를 설치합니다.
Amazon SNS 주제를 생성합니다. 주제의 아마존 리소스 이름(ARN)을 기록해 둡니다. 다음 단계에서 이 정보를 사용하고 나중에 이 설정에서 사용하세요.
주제에 대한 구독을 생성하세요.
AWS Identity and Access Management(IAM) 콘솔을 연 다음 AWS 서비스 프록시 실행 역할을 생성합니다. 나중에 설정할 수 있도록 역할의 ARN을 기록해 둡니다. 이 IAM 역할은 서비스를 가정하고 통합하려는 API 작업을 수행할 수 있는 신뢰할 수 있는 엔티티로서 API Gateway 권한을 부여합니다. Amazon SNS 예제 설정의 경우 작업 sns:Publish를 허용하세요. 자세한 내용은 API 호출을 위한 API Gateway 권한 모델을 참조하세요.
테스트 리소스를 사용하여 API Gateway REST API를 생성하세요. 자세한 내용과 예제는 Amazon API Gateway 튜토리얼 및 워크숍을 참조하세요.
참고: 선택 사항으로, 다음 샘플 OpenAPI 2.0(Swagger) 정의를 사용하여 REST API를 가져올 수 있습니다. 이 옵션은 Amazon SNS 예제 설정을 위한 설정을 사전 구성합니다. arn:aws:iam::account-id:role/apigateway-sns-role을 IAM 역할의 ARN으로 교체해야 합니다. 지역을 REST API를 생성하려는 AWS 리전으로 교체합니다.

{
  "swagger": "2.0",
  "info": {
    "version": "2019-10-09T14:10:24Z",
    "title": "aws-service-integration"
  },
  "basePath": "/dev",
  "schemes": [
    "https"
  ],
  "paths": {
    "/test": {
      "post": {
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "Message",
            "in": "query",
            "required": true,
            "type": "string"
          },
          {
            "name": "TopicArn",
            "in": "query",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "schema": {
              "$ref": "#/definitions/Empty"
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "credentials": "arn:aws:iam::account-id:role/apigateway-sns-role",
          "uri": "arn:aws:apigateway:region:sns:action/Publish",
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "requestParameters": {
            "integration.request.querystring.TopicArn": "method.request.querystring.TopicArn",
            "integration.request.querystring.Message": "method.request.querystring.Message"
          },
          "passthroughBehavior": "when_no_match",
          "httpMethod": "POST",
          "type": "aws"
        }
      }
    }
  },
  "definitions": {
    "Empty": {
      "type": "object",
      "title": "Empty Schema"
    }
  }
}

예제 HTTPS 요청 받기

통합하려는 서비스 API의 HTTPS 요청 예제를 통해 API 게이트웨이에서 요청 매개변수를 올바르게 매핑하는 데 도움을 받을 수 있습니다. HTTPS 요청 예제를 받으려면 다음 중 하나를 수행하세요.

API 문서에서 예제를 확인하세요. Amazon SNS Publish API의 경우 해당 서비스의 API 레퍼런스에서 요청 예제를 참조할 수 있습니다.

https://sns.us-west-2.amazonaws.com/?Action=Publish
&TargetArn=arn%3Aaws%3Asns%3Aus-west-2%3A803981987763%3Aendpoint%2FAPNS_SANDBOX%2Fpushapp%2F98e9ced9-f136-3893-9d60-776547eafebb
&Message=%7B%22default%22%3A%22This+is+the+default+Message%22%2C%22APNS_SANDBOX%22%3A%22%7B+%5C%22aps%5C%22+%3A+%7B+%5C%22alert%5C%22+%3A+%5C%22You+have+got+email.%5C%22%2C+%5C%22badge%5C%22+%3A+9%2C%5C%22sound%5C%22+%3A%5C%22default%5C%22%7D%7D%22%7D
&Version=2010-03-31
&AUTHPARAMS

- 또는 -

이를 API 호출에서 생성합니다. AWS CLI를 사용하여 서비스 API를 호출한 다음 출력을 분석합니다. 통합하려는 서비스 API에 해당하는 AWS CLI 명령어를 확인한 다음 --debug 옵션을 사용하여 테스트 요청을 실행합니다.

팁:AWS CLI 명령어 참조에서 해당 AWS CLI 명령을 찾으세요.

Amazon SNS 예제 설정의 경우 다음 명령어를 실행합니다.

참고: arn:aws:sns:us-east-1:123456789012:test를 Amazon SNS 주제의 ARN으로 교체합니다.

$ aws sns publish --topic-arn arn:aws:sns:us-east-1:123456789012:test --message "hi" --debug

명령어 출력에는 HTTPS 요청과 전달된 헤더가 포함됩니다. 살펴봐야 할 항목의 예는 다음과 같습니다.

2018-11-22 11:56:39,647 - MainThread - botocore.client - DEBUG - Registering retry handlers for service: sns
2018-11-22 11:56:39,648 - MainThread - botocore.hooks - DEBUG - Event before-parameter-build.sns.Publish: calling handler <function generate_idempotent_uuid at 0x11093d320>
2018-11-22 11:56:39,649 - MainThread - botocore.endpoint - DEBUG - Making request for OperationModel(name=Publish) (verify_ssl=True) with params: {'body': {'Action': u'Publish', u'Message': u'hello', 'Version': u'2010-03-31', u'TopicArn': u'arn:aws:sns:us-east-1:123456789012:test'}, 'url': u'https://sns.us-east-1.amazonaws.com/', 'headers': {'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8', 'User-Agent': 'aws-cli/1.15.74 Python/2.7.14 Darwin/16.7.0 botocore/1.9.23'}, 'context': {'auth_type': None, 'client_region': 'us-east-1', 'has_streaming_input': False, 'client_config': <botocore.config.Config object at 0x1118437d0>}, 'query_string': '', 'url_path': '/', 'method': u'POST'}
2018-11-22 11:56:39,650 - MainThread - botocore.hooks - DEBUG - Event request-created.sns.Publish: calling handler <bound method RequestSigner.handler of <botocore.signers.RequestSigner object at 0x111843750>>
2018-11-22 11:56:39,650 - MainThread - botocore.hooks - DEBUG - Event choose-signer.sns.Publish: calling handler <function set_operation_specific_signer at 0x11093d230>
2018-11-22 11:56:39,650 - MainThread - botocore.auth - DEBUG - Calculating signature using v4 auth.
2018-11-22 11:56:39,651 - MainThread - botocore.auth - DEBUG - CanonicalRequest:
POST
/

content-type:application/x-www-form-urlencoded; charset=utf-8
host:sns.us-east-1.amazonaws.com
x-amz-date:20181122T062639Z

content-type;host;x-amz-date

이 예에서는 요청이 POST HTTP 방법으로 전송됩니다.

API Gateway API용 방법 생성

API Gateway 콘솔의 API 창에서 API의 이름을 선택합니다.
리소스 창에서 리소스를 선택합니다. Amazon SNS 예제 설정의 경우 생성한 테스트 리소스를 선택합니다.
작업을 선택한 다음 방법 생성을 선택합니다.
드롭다운 목록에서 예제 HTTPS 요청의 서비스 API에서 사용하는 방법을 선택합니다. (Amazon SNS 예제 설정의 경우 POST를 선택하세요.) 그런 다음 체크 마크 아이콘을 선택합니다.
설정 창에서 다음을 수행하세요.
통합 ** 유형에서 ** AWS 서비스를 선택합니다.
AWS 리전의 경우, 통합하려는 서비스 API와 연결된 리소스의 AWS 리전을 선택합니다. Amazon SNS 예제 설정의 경우 SNS 주제의 지역을 선택하세요.
**AWS 서비스의 ** 경우 API Gateway와 통합하려는 서비스를 선택합니다. 예를 들어, **Simple Notification Service(SNS)**가 있을 수 있습니다.
(선택 사항) AWS 하위 도메인의 경우 AWS 서비스에서 사용하는 하위 도메인을 입력합니다. 서비스 문서를 참조하여 하위 도메인의 가용성을 확인하세요. Amazon SNS 예제 설정의 경우 비워 두세요.
HTTP 방법의 경우 통합하고자 하는 AWS 서비스 API에 해당하는 방법을 선택합니다. Amazon SNS 예제 설정의 경우 POST를 선택하세요.
작업 유형에 대해서는, 통합하려는 서비스 API가 지원되는 작업인 경우 작업 이름 사용을 선택합니다. 서비스의 API 참조에서 지원되는 작업 목록을 확인하세요. Amazon SNS의 경우 작업을 참조하세요.
작업에 서비스 API의 이름을 입력합니다. Amazon SNS 예제 설정을 수행하려면 게시를 입력하세요.
-또는-
작업 유형의 경우 AWS 서비스 API가 요청에 리소스 경로를 예상하는 경우 경로 재정의 사용을 선택합니다. 예를 들어, Amazon Polly ListLexicons API의 경우 **경로 재정의(선택 사항)**에 /v1/lexicons를 입력합니다.
실행 역할의 경우 생성한 IAM 역할의 ARN을 입력합니다.
(선택 사항) 콘텐츠 처리 및 기본 시간 제한 사용의 경우 사용 사례에 맞게 필요에 따라 변경하세요. Amazon SNS 예제 설정의 경우 이러한 설정을 변경하지 마세요.
저장을 선택합니다.

방법 요청을 위한 매개변수 생성

통합하려는 서비스 API에 대한 필수 및 선택적 요청 매개변수를 결정하세요. 이러한 매개변수를 식별하려면 앞서 받은 HTTPS 요청 예제를 참조하거나 서비스 API에 대한 API 참조를 참조하세요. 예를 들어, 게시를 참조하세요.

API Gateway 콘솔에서, API Gateway API의 방법에 대한 방법 실행에서 방법 요청을 선택합니다.
(선택 사항) 쿼리 문자열 매개변수의 유효성을 검사하려면 방법 요청 창에서 요청 유효성 검사기, 요청 유효성 검사기, 본문, 헤더를 선택합니다.
URL 쿼리 문자열 매개변수를 펼칩니다.
쿼리 문자열 추가를 선택합니다.
이름의 경우 이름에 통합하려는 서비스 API의 요청 매개변수 이름을 입력합니다.
체크 마크 아이콘(새 쿼리 문자열 생성)을 선택합니다.
매개변수가 필요한 경우 필수 아래의 체크 박스를 선택합니다.
포함하려는 모든 요청 매개변수에 대해 4~7단계를 반복합니다. Amazon SNS 예제 설정의 경우, T****opicArn이라는 매개변수와 Message라는 이름의 매개변수를 생성합니다.

자세한 내용은 API Gateway 콘솔을 사용하여 방법 설정하기를 참조하세요.

참고: 일부 서비스 API의 경우 통합 요청에 필수 매개변수 외에 필수 헤더와 본문을 전송해야 합니다. 통합 요청 창의 HTTP 요청 헤더 및 요청 본문 아래에서 헤더와 본문을 생성할 수 있습니다.

예를 들어, Amazon Rekognition ListCollections API를 통합하는 경우 헤더 X-Amz-Target을 생성하세요. RekognitionService.ListCollections. 요청은 다음과 같습니다.

POST https://rekognition.us-west-2.amazonaws.com/ HTTP/1.1
    Host: rekognition.us-west-2.amazonaws.com
    Accept-Encoding: identity
    Content-Length: 2
    X-Amz-Target: RekognitionService.ListCollections
    X-Amz-Date: 20170105T155800Z
    User-Agent: aws-cli/1.11.25 Python/2.7.9 Windows/8 botocore/1.4.82
    Content-Type: application/x-amz-json-1.1
    Authorization: AWS4-HMAC-SHA256 Credential=XXXXXXXX/20170105/us-west-2/rekognition/aws4_request,
      SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=XXXXXXXX

    {}

Amazon Simple Queue Service(Amazon SQS) SendMessage API를 통합하는 경우 매핑 표현식 method.request.body.JSONPath_EXPRESSION을 사용하여 요청 본문을 매핑합니다. (요청 본문의 JSON 필드에 대한 JSONPath_EXPRESSION을 JSONPath 표현식으로 교체합니다.) 이 예제의 경우 요청은 다음과 유사합니다.

{'url_path': '/', 'query_string': '', 'method': 'POST',
'headers': {'Content-Type': 'application/x-www-form-urlencoded;
charset=utf-8', 'User-Agent': 'aws-cli/1.16.81 Python/3.6.5 Darwin/18.7.0 botocore/1.12.183'},
'body': {'Action': 'SendMessage', 'Version': '2012-11-05', 'QueueUrl': 'https://sqs.ap-southeast-2.amazonaws.com/123456789012/test01', 'MessageBody': 'Hello'},
'url': 'https://ap-southeast-2.queue.amazonaws.com/', 'context': {'client_region': 'ap-southeast-2', 'client_config': <botocore.config.Config object at 0x106862da0>, 'has_streaming_input': False, 'auth_type': None}}

통합 요청을 위한 매개변수 생성

방법 요청을 위해 생성한 매개변수를 통합 요청에 대한 매개변수에 매핑합니다.

API Gateway 콘솔에서 API Gateway API의 방법에 대한 방법 실행 창으로 돌아가서 통합 요청을 선택합니다.
통합 요청 창에서 URL 쿼리 문자열 매개변수를 펼칩니다.
쿼리 문자열 추가를 선택합니다.
이름의 경우 이름에 통합하려는 서비스 API의 요청 매개변수 이름을 입력합니다.
참고: 이름은 대소문자를 구분하며 서비스 API의 요구 사항을 충족하여 정확하게 표시되어야 합니다.
매핑 출처에 method.request.querystring.param_name을 입력합니다. param_name을 방법 요청에 대해 생성한 해당 매개변수의 이름으로 교체합니다. 예를 들어, method.request.querystring.TopicArn이 있을 수 있습니다.
체크 표시 아이콘(생성)을 선택합니다.
3~6단계를 반복하여 방법 요청에 대해 생성한 각 매개변수에 해당하는 연동 요청에 대한 매개변수를 생성합니다.

참고: 방법 요청에 필요한 헤더와 본문을 생성한 경우 이를 통합 요청에도 매핑하세요. 통합 요청 창에서 HTTP 헤더 및 매핑 템플릿 아래에 이를 생성하세요.

자세한 내용은 API Gateway 콘솔을 사용하여 API 통합 요청 설정하기를 참조하세요.

(선택 사항) 통합 구성을 확인하세요

통합 설정이 원하는 대로 표시되는지 확인하려면 AWS CLI get-integration 명령어를 실행하여 다음과 유사하게 구성을 확인할 수 있습니다.

$ aws apigateway get-integration --rest-api-id 1234123412 --resource-id y9h6rt --http-method POST

Amazon SNS 예제 설정의 경우 출력은 다음과 유사합니다.

{
    "integrationResponses": {
        "200": {
            "responseTemplates": {
                "application/json": null
            },
            "statusCode": "200"
        }
    },
    "passthroughBehavior": "WHEN_NO_MATCH",
    "timeoutInMillis": 29000,
    "uri": "arn:aws:apigateway:us-east-2:sns:action/Publish",
    "httpMethod": "POST",
    "cacheNamespace": "y9h6rt",
    "credentials": "arn:aws:iam::1234567890:role/apigateway-sns-role",
    "type": "AWS",
    "requestParameters": {
        "integration.request.querystring.TopicArn": "method.request.querystring.TopicArn",
        "integration.request.querystring.Message": "method.request.querystring.Message"
    },
    "cacheKeyParameters": []
}

API Gateway 콘솔에서 API Gateway API의 방법에 대한 방법 실행 창으로 돌아가서 테스트를 선택합니다.

방법 테스트 창에서 다음을 수행합니다.
쿼리 문자열에 요청 매개변수와 해당 매개변수 값이 포함된 쿼리 문자열을 입력합니다. Amazon SNS 예제 설정의 경우 **TopicArn= arn:aws:sns:us-east-1:123456789012:test&Message="Hello"**를 입력하세요. arn:aws:sns:us-east-1:123456789012:test를 Amazon SNS 주제의 ARN으로 교체합니다.
설정을 위해 생성한 경우 헤더 및 요청 본문에 헤더 이름과 요청 본문 JSON을 입력합니다.
테스트를 선택합니다. 방법 테스트 창에 응답이 표시됩니다. 응답이 성공적이면 Status: 200이 표시됩니다. Amazon SNS 예제 설정의 경우 성공적인 응답에는 응답 본문에 MessageId가 포함됩니다.
자세한 내용은 API Gateway 콘솔을 사용하여 REST API 방법 테스트하기를 참조하세요.
REST API를 배포하세요.
원하는 도구를 사용하여 API를 테스트하세요.