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

최종 업데이트 날짜: 2020년 4월 16일

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 리소스를 생성합니다. Amazon SNS 예제 설정의 경우 다음을 수행합니다.

  1. AWS 명령줄 인터페이스(AWS CLI)를 설치합니다.
  2. Amazon SNS 주제를 생성합니다. 주제의 Amazon 리소스 이름(ARN)을 기록합니다. 이 정보는 다음 단계와 설정 뒷부분에서 필요합니다.
  3. 주제에 대한 구독을 생성합니다.
  4. AWS 서비스 프록시 실행 역할을 생성합니다. 나중에 설정에서 사용할 수 있도록 역할의 ARN을 기록합니다. 이 AWS Identity and Access Management(IAM) 역할은 서비스를 위임하고 통합 중인 API 작업을 수행하도록 신뢰할 수 있는 엔터티로서 API Gateway 권한을 부여합니다. Amazon SNS 예제 설정의 경우 sns: Publish 작업을 허용합니다. 자세한 내용은 API 호출을 위한 API Gateway 권한 모델을 참조하십시오.
  5. 테스트 리소스를 사용하여 API Gateway REST API를 생성합니다. 자세한 내용과 예제는 Amazon API Gateway 자습서를 참조하십시오.
    참고: 선택적으로 다음 샘플 OpenAPI 2.0(Swagger) 정의를 사용하여 REST API를 가져올 수 있습니다. 이 옵션은 Amazon SNS 예제 설정에 대한 설정을 사전 구성하므로 나중에 대부분의 API Gateway 콘솔 구성 단계를 건너뛸 수 있습니다. arn:aws:iam::account-id:role/apigateway-sns-role을 IAM 역할의 ARN으로 바꿔야 합니다. region을 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 Gateway에서 요청 파라미터를 올바르게 매핑하는 데 도움이 될 수 있습니다. 예제 HTTPS 요청을 가져오려면 다음 중 하나를 수행합니다.

  • AWS 설명서에서 찾기

API 설명서에서 예제를 확인합니다. Amazon SNS Publish API의 경우 서비스의 API Reference에서 예제 요청을 참조할 수 있습니다.

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에 대한 메서드 생성

  1. API Gateway 콘솔의 [API] 창에서 API 이름을 선택합니다.
  2. [리소스] 창에서 리소스를 선택합니다. Amazon SNS 예제 설정에서 생성한 테스트 리소스를 선택합니다.
  3. [작업]을 선택한 다음 [메서드 생성]을 선택합니다.
  4. 드롭다운 목록의 HTTPS 요청 예제에서 서비스 API가 사용하는 메서드를 선택합니다. (Amazon SNS 예제 설정의 경우 POST를 선택합니다.) 그런 다음 확인 표시 아이콘을 선택합니다.
  5. [설정] 창에서 다음을 수행합니다.
    [통합 유형]에서 AWS 서비스를 선택합니다.
    AWS 리전에서 통합하려는 서비스 API와 연결된 리소스의 AWS 리전을 선택합니다. Amazon SNS 예제 설정에서 SNS 주제의 리전을 선택합니다.
    AWS 서비스에서 API Gateway와 통합하려는 서비스를 선택합니다. 예: Simple Notification Service(SNS).
    (선택 사항) AWS Subdomain에 AWS 서비스가 사용하는 하위 도메인을 입력합니다. 서비스 설명서를 확인하여 하위 도메인의 가용성을 확인합니다. Amazon SNS 예제 설정의 경우 비워둡니다.
    HTTP 메서드에서 통합하려는 AWS 서비스 API에 해당하는 메서드를 선택합니다. Amazon SNS 예제 설정에서 POST를 선택합니다.
    통합하려는 서비스 API가 지원되는 작업인 경우 [작업 유형]에서 [작업 이름 사용]을 선택합니다. (지원되는 작업 목록은 서비스의 API 참조를 확인하십시오. Amazon SNS의 경우 API 참조의 작업을 참조하십시오.) [작업]에 서비스 API의 이름을 입력합니다. Amazon SNS 예제 설정에 Publish를 입력합니다.
    또는 AWS 서비스 API가 요청에 리소스 경로를 필요로 하는 경우 [작업 유형]에서 [경로 재정의 사용]을 선택합니다. 예를 들어 Amazon Polly ListLexicons API의 경우 [경로 재정의(선택 사항)]에 /v1/lexicons를 입력합니다.
    [실행 역할]에 생성한 IAM 역할의 ARN을 입력합니다.
    (선택 사항) [콘텐츠 처리] 및 [기본 제한 시간 사용]에서 사용 사례에 따라 필요한 만큼 변경합니다. Amazon SNS 예제 설정의 경우 해당 설정을 변경하지 마십시오.
  6. [저장]을 선택합니다.

메서드 요청에 대한 파라미터 생성

통합하려는 서비스 API에 대한 필수 및 선택적 요청 파라미터를 결정합니다. 이러한 파라미터를 식별하려면 앞서 받은 HTTPS 요청 예제를 참조하거나 서비스 API에 대한 API 참조를 참조하십시오. 예를 들어 게시를 참조하십시오.

  1. API Gateway 콘솔의 경우 API Gateway API의 메서드에 대한 [메서드 실행] 창에서 [메서드 요청]을 선택합니다.
  2. (선택 사항) 요청 검사기의 경우 [메서드 요청] 창에서 쿼리 문자열 파라미터(요청 본문 및 헤더)를 검증하려면 [요청 검사기]를 선택합니다.
  3. [URL 쿼리 문자열 파라미터]를 확장합니다.
  4. [쿼리 문자열 추가]를 선택합니다.
  5. [이름]에 통합하려는 서비스 API에 대한 요청 파라미터의 이름을 입력합니다.
  6. 확인 표시 아이콘(새 쿼리 문자열 생성)을 선택합니다.
  7. 파라미터가 필요한 경우 [필수] 아래의 확인란을 선택합니다.
  8. 포함할 모든 요청 파라미터에 대해 4~7단계를 반복합니다. Amazon SNS 예제 설정의 경우 [TopicArn]이라는 파라미터와 [Message]라는 다른 파라미터를 생성합니다.

자세한 내용은 API Gateway 콘솔을 사용하여 메서드 설정을 참조하십시오.

참고: 일부 서비스 API의 경우 필수 파라미터 외에도 통합 요청의 필수 헤더와 본문을 전송해야 합니다. 통합하려는 서비스 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을 사용하여 요청 본문을 매핑할 수 있습니다. (JSONPath_EXPRESSION을 요청 본문의 JSON 필드에 대한 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}}

통합 요청에 대한 파라미터 생성

메서드 요청에 대해 생성한 파라미터를 통합 요청에 대한 파라미터에 매핑합니다.

  1. API Gateway 콘솔에서 API Gateway API의 메서드에 대한 [메서드 실행] 창으로 돌아간 다음 [통합 요청]을 선택합니다.
  2. [통합 요청] 창에서 [URL 쿼리 문자열 파라미터]를 확장합니다.
  3. [쿼리 문자열 추가]를 선택합니다.
  4. [이름]에 통합하려는 서비스 API에 대한 요청 파라미터의 이름을 입력합니다.
    참고: 이름은 대/소문자를 구분하며 서비스 API에서 예상한 대로 정확하게 표시되어야 합니다.
  5. 매핑 시작method.request.querystring.param_name을 입력하고 param_name을 메서드 요청에 대해 생성한 해당 파라미터의 이름으로 바꿉니다. 예: method.request.querystring.TopicArn.
  6. 확인 표시 아이콘(생성)을 선택합니다.
  7. 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": []
}

설정 테스트

  1. API Gateway 콘솔에서 API Gateway API의 메서드에 대한 [메서드 실행] 창으로 돌아간 다음 [TEST]를 선택합니다.
  2. [메서드 테스트] 창에서 다음을 수행합니다.
    [쿼리 문자열]에 요청 파라미터와 이에 대한 값이 포함된 쿼리 문자열을 입력합니다. 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을 입력합니다.
    [테스트]를 선택합니다. [메서드 테스트] 창에 응답이 표시됩니다. 응답이 성공하면 상태: 200이 표시됩니다. Amazon SNS 예제 설정의 경우 성공적인 응답에는 응답 본문에 MessageId가 포함됩니다.
    자세한 내용은 API Gateway 콘솔을 사용하여 REST API 메서드 테스트를 참조하십시오.
  3. REST API를 배포합니다.
  4. 원하는 도구를 사용하여 API를 테스트합니다.