API Gateway を他の AWS サービスのプロキシとして使用するにはどうすればよいですか?
Amazon API Gateway を他の AWS サービスのプロキシとして使用することで、それら他の AWS サービスを API Gateway と統合したいと考えています。
簡単な説明
AWS サービス API とは、HTTPS リクエストの送信先にすることができる REST API です。API Gateway には多くの AWS サービスを統合できますが、設定とマッピングは各サービス 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 の設定例では、以下を実行します。
- AWS CLI をインストールします。
- Amazon SNS トピックを作成します。トピックの Amazon リソースネーム (ARN) を書き留めておきます。この情報は次のステップで、またこの設定の後の段階で使用します。
- トピックへのサブスクリプションを作成します。
- AWS Identity and Access Management (IAM) コンソールを開き、AWS サービスプロキシ実行ロールを作成します。設定の後の段階で使用できるように、ロールの ARN を書き留めておきます。この IAM ロールは、信頼されたエンティティとしての API Gateway に対し、サービスを引き受け、統合対象の API アクションを実行するための権限を付与します。この 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 に置き換えます。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 リクエストの例を取得するには、次のいずれかを実行します。
例を 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 コマンドを特定するには、「AW 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 サービスによって使用されるサブドメインを入力します。サブドメインが使用可能かどうかを確認するには、AWS サービスのドキュメントを参照してください。この Amazon SNS の設定例では、このフィールドを空白のままにしておきます。
[HTTP メソッド] では、統合対象の AWS サービス API に対応するメソッドを選択します。この Amazon SNS の設定例では、[POST] を選択します。
[アクションの種類] では、統合対象のサービス API がサポートされているアクションの場合に [アクション名の使用] を選択します。サポートされているアクションのリストについては、「サービスの API リファレンス」を参照してください。Amazon SNS については、「アクション」を参照してください。
[アクション] にサービス API の名前を入力します。この Amazon SNS の設定例では、「Publish」と入力します。
- または -
[アクションの種類] では、リクエストにリソースパスを含めることが AWS サービス API で要求される場合、[パス上書きの使用] を選択します。例えば、Amazon Polly ListLexicons API の場合、[パス上書き (省略可能)] に「/v1/lexicons」と入力します。
[実行ロール] に、作成した IAM ロールの ARN を入力します。
(オプション) [コンテンツの処理] と [デフォルトタイムアウトの使用] については、ユースケースに合わせて変更してください。この Amazon SNS の設定例では、これらの設定を変更しないでください。 - [保存] を選択します。
メソッドリクエストのパラメータを作成する
統合対象のサービス API の必須およびオプションのリクエストパラメータを設定します。これらのパラメータについては、先ほど挙げた HTTPS リクエストの例を参照するか、サービス API の「API リファレンス」を参照してください。例えば、「Publish」を参照します。
- 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 を使用してリクエスト本文をマッピングします(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}}
統合リクエストのパラメータを作成する
メソッドリクエスト用に作成したパラメータを統合リクエストのパラメータにマップします。
- 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 をテストします。
関連情報
チュートリアル: AWS 統合で API Gateway REST API を構築する
関連するコンテンツ
AWS公式更新しました 2年前- AWS公式更新しました 2年前
