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 コマンドラインインターフェイス (AWS CLI) コマンドの実行中にエラーが発生した場合は、最新バージョンの AWS CLI を使用していることを確認してください

必要なツールとリソースを設定する

環境を設定し、ユースケースに必要なすべての AWS リソースを作成します。Amazon SNS のセットアップ例では、以下を実行します。

  1. 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 リファレンスをご参照ください。

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 コンソールAPIs ペインで、作成した API の名前を選択します。
  2. Resources ペインで、リソースを選択します。Amazon SNS サンプル設定では、作成したテストリソースを選択します。
  3. [アクション]、[メソッドを作成] の順に選択します。
  4. ドロップダウンリストで、HTTPS リクエストの例でサービス API で使用されているメソッドを選択します。(Amazon SNS の設定例として、 POST を選択します。) チェックマークアイコンを選択します。
  5. セットアップ ペインで、以下の操作を行います。
    [統合タイプ]で、 AWS のサービスを選択します。
    AWS リージョンで、統合するサービス API に関連付けられたリソースの AWS リージョンを選択します。Amazon SNS の設定例として、SNS トピックのリージョンを選択します。
    AWS Service で、 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 の設定例では、 公開 を入力します。
    または、 アクションタイプ で、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 HeadersMapping Templatesの下の 統合リクエスト ペインでそれらを作成します。

詳細については、「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 のメソッドの メソッドを実行 ペインに戻り、 テストを選択します。
  2. メソッドテスト ペインで、以下の操作を行います。
    Query Strings に、リクエストパラメータとその値を含むクエリ文字列を入力します。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 メソッドをテストする」をご参照ください。
  3. REST API をデプロイする
  4. 任意のツールを使用して API をテストします。