チュートリアル: API Gateway で REST API を Amazon Kinesis のプロキシとして作成する
ここでは、AWS
との統合のタイプで REST API を作成および設定して、Kinesis にアクセスする方法について説明します。
API Gateway の API を Kinesis と統合するには、API Gateway と Kinesis の両方のサービスが利用できるリージョンを選択する必要があります。利用できるリージョンについては、「サービスエンドポイントとクォータ」を参照してください。
この図では、サンプル API を作成して、クライアントが次の操作を行うことができるようにします。
-
ユーザーが Kinesis にあるストリームを一覧表示する
-
指定されたストリームを作成、説明、または削除する
-
指定されたストリームからデータレコードを読み取る、または書き込む
前述のタスクを完了するため、API はさまざまなリソースでメソッドを公開し、それぞれ次のものを呼び出します。
-
Kinesis の
ListStreams
アクション -
CreateStream
、DescribeStream
、またはDeleteStream
アクション -
Kinesis の
GetRecords
またはPutRecords
(PutRecord
を含む) アクション
具体的には、次のように API を作成します。
-
API の
/streams
リソースに対する HTTP GET メソッドを公開し、そのメソッドを Kinesis の ListStreams アクションと統合して、呼び出し元のアカウントでストリームを一覧表示します。 -
API の
/streams/{stream-name}
リソースに対する HTTP POST メソッドを公開し、そのメソッドを Kinesis の CreateStream アクションと統合して、呼び出し元のアカウントで指定したストリームを作成します。 -
API の
/streams/{stream-name}
リソースに対する HTTP GET メソッドを公開し、そのメソッドを Kinesis の DescribeStream アクションと統合して、呼び出し元のアカウントで指定したストリームを表示します。 -
API の
/streams/{stream-name}
リソースに対する HTTP DELETE メソッドを公開し、そのメソッドを Kinesis の DeleteStream アクションと統合して、呼び出し元のアカウントでストリームを削除します。 -
API の
/streams/{stream-name}/record
リソースに対する HTTP PUT メソッドを公開し、そのメソッドを Kinesis の PutRecord アクションと統合します。これにより、クライアントは名前付きストリームに 1 つのデータレコードを追加できます。 -
API の
/streams/{stream-name}/records
リソースに対する HTTP PUT メソッドを公開し、そのメソッドを Kinesis の PutRecords アクションと統合します。これにより、クライアントは名前付きストリームにデータレコードのリストを追加できます。 -
API の
/streams/{stream-name}/records
リソースに対する HTTP GET メソッドを公開し、そのメソッドを Kinesis の GetRecords アクションと統合します。これにより、クライアントは名前付きストリームで指定されたシャードイテレーターとともにデータレコードを一覧表示できます。シャードイテレーターは、データレコードの逐次読み取りを開始する、シャードの位置を指定します。 -
API の
/streams/{stream-name}/sharditerator
リソースに対する HTTP GET メソッドを公開し、そのメソッドを Kinesis の GetShardIterator アクションと統合します。このヘルパーメソッドは、Kinesis のListStreams
アクションに提供する必要があります。
ここに示す手順は、Kinesis の他のアクションにも適用できます。Kinesis のアクションの一覧については、Amazon Kinesis API Reference を参照してください。
API Gateway コンソールを使用してサンプルの API を作成する代わりに、API Gateway のインポート API を使用してサンプルの API を API Gateway にインポートできます。API のインポート機能の使用方法の詳細については、「OpenAPI を使用した REST API の設定」を参照してください。
API が Kinesis にアクセスするための IAM ロールと IAM ポリシーを作成する
API で Kinesis のアクションを呼び出せるようにするには、IAM ロールに適切な IAM ポリシーをアタッチする必要があります。このセクションでは、必要な IAM ロールと IAM ポリシーを確認し、必要に応じてそれらを作成する方法について説明します。
Kinesis への読み取り専用アクセスを有効にするには、Kinesis での Get*
アクション、List*
アクション、Describe*
アクションの呼び出しを許可する AmazonKinesisReadOnlyAccess ポリシーを使用できます。
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kinesis:Get*", "kinesis:List*", "kinesis:Describe*" ], "Resource": "*" } ] }
このポリシーは、IAM で提供されているマネージドポリシーであり、その ARN は arn:aws:iam::aws:policy/AmazonKinesisReadOnlyAccess
です。
Kinesis で読み取りと書き込みのアクションを有効にするには、AmazonKinesisFullAccess policy ポリシーを使用できます。
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "kinesis:*", "Resource": "*" } ] }
このポリシーも、IAM で提供されているマネージドポリシーです。その ARN は arn:aws:iam::aws:policy/AmazonKinesisFullAccess
です。
使用する IAM ポリシーを決定したら、新しい IAM ロールまたは既存の IAM ロールにアタッチします。API Gateway 管理サービス (apigateway.amazonaws.com
) がロールの信頼できるエンティティであり、実行ロール (sts:AssumeRole
) の引き受けが許可されていることを確認してください。
{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
IAM コンソールで実行ロールを作成して Amazon API Gateway ロールタイプを選択すると、この信頼ポリシーは自動的にアタッチされます。
実行ロールの ARN をメモしておきます。これは API メソッドを作成し、その統合リクエストを設定するときに必要になります。
API を Kinesis のプロキシとして作成する
以下の手順に従って、API Gateway コンソールで API を作成します。
API を Kinesis の AWS サービスプロキシとして作成するには
-
https://console.aws.amazon.com/apigateway
で API Gateway コンソールにサインインします。 -
API Gateway を初めて使用する場合は、サービスの特徴を紹介するページが表示されます。[REST API] で、[構築] を選択します。[Create Example API (サンプル API の作成)] がポップアップ表示されたら、[OK] を選択します。
API Gateway を使用するのが初めてではない場合、[Create API] (API を作成)を選択します。[REST API] で、[構築] を選択します。
-
[新しい API] を選択します。
-
[API name (API 名)] に「
KinesisProxy
」と入力します。その他のフィールドはデフォルト値のままにしておきます。 -
必要に応じて、[説明] に説明を入力します。
-
[Create API] を選択します。
API が作成されると、API Gateway コンソールに API のルート (/
) リソースのみを含む [Resources (リソース)] ページが表示されます。
Kinesis のストリームを一覧表示する
Kinesis では、次の REST API コールによる ListStreams
アクションがサポートされています。
POST /?Action=ListStreams HTTP/1.1 Host: kinesis.<region>.<domain> Content-Length: <PayloadSizeBytes> User-Agent: <UserAgentString> Content-Type: application/x-amz-json-1.1 Authorization: <AuthParams> X-Amz-Date: <Date> { ... }
上記の REST API リクエストでは、このアクションは、Action
クエリパラメータで指定されます。または、代わりに、X-Amz-Target
ヘッダーでこのアクションを指定することもできます。
POST / HTTP/1.1 Host: kinesis.<region>.<domain> Content-Length: <PayloadSizeBytes> User-Agent: <UserAgentString> Content-Type: application/x-amz-json-1.1 Authorization: <AuthParams> X-Amz-Date: <Date> X-Amz-Target: Kinesis_20131202.ListStreams { ... }
このチュートリアルでは、クエリパラメータを使用してアクションを指定します。
API で Kinesis のアクションを公開するには、API のルートに /streams
リソースを追加します。次に、そのリソースに対する GET
メソッドを設定し、そのメソッドを Kinesis の ListStreams
アクションと統合します。
以下の手順では、API Gateway コンソールを使用して Kinesis のストリームを一覧表示する方法について説明します。
API Gateway コンソールを使用して Kinesis のストリームを一覧表示するには
-
API のルートリソースを選択します。[アクション] で、[リソースの作成] を選択します。
[リソース名] に「
Streams
」と入力し、[リソースパス] および他のフィールドをデフォルトのままにして、[リソースの作成] を選択します。 -
/Streams
リソースを選択します。[アクション] から [メソッドの作成] を選択し、一覧から [GET] を選択します。次に、チェックマークアイコンを選択してメソッドの作成を終了します。注記 クライアントによって呼び出されるメソッドの HTTP 動詞は、バックエンド統合が必要な場合の HTTP 動詞とは異なる場合があります。直感的に、ストリームのリスト表示は読み取りオペレーションであるため、ここでは
GET
を選択します。 -
メソッドの [Setup] (設定) ペインで、[AWS Service] (AWS のサービス) を選択します。
-
[AWS Region] (AWS リージョン) で、リージョン (例: us-east-1) を選択します。
-
[AWS Service] (AWS のサービス) で、[Kinesis] を選択します。
-
[AWS Subdomain] (AWS サブドメイン) は空白のままにします。
-
[HTTP メソッド] で、[POST] を選択します。
注記 ここで
POST
を選択したのは、Kinesis では POST を使用してListStreams
アクションを実行する必要があるためです。 -
[Action Type] で、[Use action name] を選択します。
-
[Action] に
ListStreams
と入力します。 -
[実行ロール] に、実行ロールの ARN を入力します。
-
[コンテンツの処理] の [パススルー] はデフォルトのままにします。
-
[保存] を選択して、メソッドの初期設定を終了します。
-
-
引き続き [統合リクエスト] ペインで、[HTTP ヘッダー] セクションを展開します。
-
[ヘッダーの追加] を選択します。
-
[名前] ボックスに、「
Content-Type
」と入力します。 -
[マッピング元] 列に「
'application/x-amz-json-1.1'
」と入力します。 -
チェックマークアイコンを選択して、設定を保存します。
ここでは、リクエストのパラメータのマッピングを使用して
Content-Type
ヘッダーに静的な値の'application/x-amz-json-1.1'
を設定することで、Kinesis に入力が特定のバージョンの JSON であることを知らせるようにしています。 -
-
次のように、[マッピングテンプレート] セクションを展開します。
-
[マッピングテンプレートの追加] を選択します。
-
[Content-Type] に「
application/json
」と入力します。 -
チェックマークアイコンを選択して [Content-Type] の設定を保存します。[パススルー動作の変更] の [はい、この統合を保護します] を選択します。
-
Template Editor に「
{}
」と入力します。 -
[保存] ボタンを選択して、マッピングテンプレートを保存します。
ListStreams のリクエストのペイロードは、次の形式の JSON です。
{ "ExclusiveStartStreamName": "string", "Limit": number }
ただし、プロパティはオプションです。デフォルト値を使用するため、ここでは空の JSON ペイロードを選択しました。
-
-
/streams リソースに対する GET メソッドをテストして、Kinesis で
ListStreams
アクションを呼び出します。API Gateway コンソールで、[Resources (リソース)] ペインの /streams/GET エントリを選択し、[Test (テスト)] 呼び出しオプションを選択して、[Test (テスト)] を選択します。
既に Kinesis で「myStream」と「yourStream」という 2 つのストリームが作成されている場合、テストが成功すると次のペイロードが含まれる 200 OK レスポンスが返されます。
{ "HasMoreStreams": false, "StreamNames": [ "myStream", "yourStream" ] }
Kinesis でストリームを作成、表示、削除する
Kinesis でストリームを作成、表示、削除するには、それぞれ次の Kinesis の REST API へのリクエストを作成する必要があります。
POST /?Action=CreateStream HTTP/1.1 Host: kinesis.
region
.domain
... Content-Type: application/x-amz-json-1.1 Content-Length:PayloadSizeBytes
{ "ShardCount": number, "StreamName": "string" }
POST /?Action=DescribeStream HTTP/1.1 Host: kinesis.
region
.domain
... Content-Type: application/x-amz-json-1.1 Content-Length:PayloadSizeBytes
{ "StreamName": "string" }
POST /?Action=DeleteStream HTTP/1.1 Host: kinesis.
region
.domain
... Content-Type: application/x-amz-json-1.1 Content-Length:PayloadSizeBytes
{ "StreamName":"string" }
API を作成して、必要な入力をメソッドリクエストの JSON ペイロードとして受け取り、ペイロードを統合リクエストに渡すことができます。ただし、メソッドリクエストと統合リクエスト、およびメソッドレスポンスと統合レスポンスの間のデータマッピングの例を詳細に示すため、API は少し異なる方法で作成します。
これから名前を付ける GET
リソースの HTTP メソッド (POST
、Delete
、Stream
) を公開します。{stream-name}
パス変数をこのストリームリソースのプレースホルダーとして使用して、これらの API のメソッドを Kinesis の DescribeStream
、CreateStream
、DeleteStream
アクションとそれぞれ統合します。クライアントは、他の入力データをメソッドリクエストのヘッダー、クエリパラメータ、またはペイロードとして渡す必要があります。必要な統合リクエストペイロードにデータを変換するためのマッピングテンプレートが用意されています。
ストリームリソースで GET メソッドを設定し、テストするには
-
以前に作成した
{stream-name}
リソースの下の/streams
パス変数を使用して、子リソースを作成します。 -
HTTP 動詞 (
POST
、GET
、DELETE
) をこのリソースに追加します。リソースでメソッドを作成すると、API の構造は次のようになります。
-
GET /streams/{stream-name}
メソッドを設定するには、以下のように Kinesis でPOST /?Action=DescribeStream
アクションを呼び出します。 -
次のヘッダーマッピング (
Content-Type
) を統合リクエストに追加します。Content-Type: 'x-amz-json-1.1'
このタスクでは、同じ手順を使用して
GET /streams
メソッドのリクエストパラメータマッピングを設定します。 -
次の本文マッピングテンプレートを追加して、
GET /streams/{stream-name}
メソッドリクエストからPOST /?Action=DescribeStream
統合リクエストにデータをマッピングします。{ "StreamName": "$input.params('stream-name')" }
このマッピングテンプレートでは、Kinesis の
DescribeStream
アクションに必要な統合リクエストのペイロードをメソッドリクエストのstream-name
パスパラメータ値から生成します。 -
GET /stream/{stream-name}
メソッドをテストして、Kinesis でDescribeStream
アクションを呼び出します。API Gateway コンソールで、[Resources (リソース)] ペインの /streams/{stream-name}/GET を選択し、テストを開始するために [Test (テスト)] を選択し、
stream-name
の [Path (パス)] フィールドに Kinesis の既存のストリームの名前を入力して、[Test (テスト)] を選択します。テストに成功すると、200 OK レスポンスが、次のようなペイロードとともに返されます。{ "StreamDescription": { "HasMoreShards": false, "RetentionPeriodHours": 24, "Shards": [ { "HashKeyRange": { "EndingHashKey": "68056473384187692692674921486353642290", "StartingHashKey": "0" }, "SequenceNumberRange": { "StartingSequenceNumber": "49559266461454070523309915164834022007924120923395850242" }, "ShardId": "shardId-000000000000" }, ... { "HashKeyRange": { "EndingHashKey": "340282366920938463463374607431768211455", "StartingHashKey": "272225893536750770770699685945414569164" }, "SequenceNumberRange": { "StartingSequenceNumber": "49559266461543273504104037657400164881014714369419771970" }, "ShardId": "shardId-000000000004" } ], "StreamARN": "arn:aws:kinesis:us-east-1:12345678901:stream/myStream", "StreamName": "myStream", "StreamStatus": "ACTIVE" } }
API をデプロイした後は、この API メソッドに対して REST リクエストを行うことができます。
GET https://
your-api-id
.execute-api.region
.amazonaws.com/stage
/streams/myStream
HTTP/1.1 Host:your-api-id
.execute-api.region
.amazonaws.com Content-Type: application/json Authorization: ... X-Amz-Date: 20160323T194451Z
ストリームリソースで POST メソッドを設定し、テストするには
-
Kinesis で
POST /streams/{stream-name}
アクションを呼び出すようにPOST /?Action=CreateStream
メソッドを設定します。GET /streams/{stream-name}
アクションをDescribeStream
に置き換える場合、タスクは、同じ手順を使用して、CreateStream
メソッドを設定します。 -
次のヘッダーマッピング (
Content-Type
) を統合リクエストに追加します。Content-Type: 'x-amz-json-1.1'
このタスクでは、同じ手順を使用して
GET /streams
メソッドのリクエストパラメータマッピングを設定します。 -
次の本文マッピングテンプレートを追加して、
POST /streams/{stream-name}
メソッドリクエストからPOST /?Action=CreateStream
統合リクエストにデータをマッピングします。{ "ShardCount": #if($input.path('$.ShardCount') == '') 5 #else $input.path('$.ShardCount') #end, "StreamName": "$input.params('stream-name')" }
前述のマッピングテンプレートで、クライアントがメソッドリクエストペイロードで値を指定しなかった場合は、
ShardCount
を固定値 5 に設定します。 -
POST /streams/{stream-name}
メソッドをテストして、Kinesis で指定したストリームを作成します。API Gateway コンソールで、[Resources] (リソース) ペインの /streams/{stream-name}/POST を選択し、テストを開始するために [Test] (テスト) を選択し、
stream-name
の [Path] (パス) に新しい Kinesis ストリームの名前を入力して、[Test] (テスト) を選択します。テストが完了すると、データなしで 200 OK レスポンスが返されます。API をデプロイしたら、ストリームリソースの POST メソッドに対する REST API リクエストを行って、Kinesis で
CreateStream
アクションを呼び出すこともできます。POST https://
your-api-id
.execute-api.region
.amazonaws.com/stage
/streams/yourStream
HTTP/1.1 Host:your-api-id
.execute-api.region
.amazonaws.com Content-Type: application/json Authorization: ... X-Amz-Date: 20160323T194451Z { "ShardCount": 5 }
ストリームリソースで DELETE メソッドを設定し、テストする
-
Kinesis の
DELETE /streams/{stream-name}
アクションと統合するようにPOST /?Action=DeleteStream
メソッドを設定します。GET /streams/{stream-name}
アクションをDescribeStream
に置き換える場合、タスクは、同じ手順を使用して、DeleteStream
メソッドを設定します。 -
次のヘッダーマッピング (
Content-Type
) を統合リクエストに追加します。Content-Type: 'x-amz-json-1.1'
このタスクでは、同じ手順を使用して
GET /streams
メソッドのリクエストパラメータマッピングを設定します。 -
次の本文マッピングテンプレートを追加して、
DELETE /streams/{stream-name}
メソッドリクエストからPOST /?Action=DeleteStream
の該当する統合リクエストにデータをマッピングします。{ "StreamName": "$input.params('stream-name')" }
このマッピングテンプレートでは、
DELETE /streams/{stream-name}
のクライアントが指定した URL パス名値からstream-name
アクションに必要な入力が生成されます。 -
DELETE メソッドをテストして、Kinesis で指定したストリームを削除します。
API Gateway コンソールで、[Resources (リソース)] ペインの /streams/{stream-name}/DELETE メソッドノードを選択し、テストを開始するために [Test (テスト)] を選択し、
stream-name
の [Path (パス)] に Kinesis の既存のストリームの名前を入力して、[Test (テスト)] を選択します。テストが完了すると、データなしで 200 OK レスポンスが返されます。API をデプロイしたら、ストリームリソースの DELETE メソッドに対する以下の REST API リクエストを行って、Kinesis で
DeleteStream
アクションを呼び出すこともできます。DELETE https://
your-api-id
.execute-api.region
.amazonaws.com/stage
/streams/yourStream
HTTP/1.1 Host:your-api-id
.execute-api.region
.amazonaws.com Content-Type: application/json Authorization: ... X-Amz-Date: 20160323T194451Z {}
Kinesis のストリームに対してレコードの取得や追加を行う
Kinesis でストリームを作成すると、ストリームにデータレコードを追加したり、ストリームからデータを読み取ったりすることができます。データレコードを追加するには、Kinesis で PutRecords アクションまたは PutRecord アクションを呼び出す必要があります。前者は複数のレコードを追加し、後者は 1 つのレコードをストリームに追加します。
POST /?Action=PutRecords HTTP/1.1 Host: kinesis.
region
.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ... ... Content-Type: application/x-amz-json-1.1 Content-Length:PayloadSizeBytes
{ "Records": [ { "Data": blob, "ExplicitHashKey": "string", "PartitionKey": "string" } ], "StreamName": "string" }
または
POST /?Action=PutRecord HTTP/1.1 Host: kinesis.
region
.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ... ... Content-Type: application/x-amz-json-1.1 Content-Length:PayloadSizeBytes
{ "Data":blob
, "ExplicitHashKey":"string"
, "PartitionKey":"string"
, "SequenceNumberForOrdering":"string"
, "StreamName": "string" }
ここで、StreamName
はレコードを追加するターゲットストリームを識別します。StreamName
、Data
、および PartitionKey
は必須の入力データです。この例では、すべてのオプション入力データにデフォルト値を使用し、メソッドリクエストへの入力ではそれらの値を明示的に指定しません。
Kinesis のデータを読み取るには、GetRecords アクションを呼び出します。
POST /?Action=GetRecords HTTP/1.1 Host: kinesis.
region
.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ... ... Content-Type: application/x-amz-json-1.1 Content-Length:PayloadSizeBytes
{ "ShardIterator":"string"
, "Limit":number
}
レコードを取得するソースのストリームは、必須の ShardIterator
の値で指定します。シャードイテレーターは、次の Kinesis のアクションで取得します。
POST /?Action=GetShardIterator HTTP/1.1 Host: kinesis.
region
.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ... ... Content-Type: application/x-amz-json-1.1 Content-Length:PayloadSizeBytes
{ "ShardId":"string"
, "ShardIteratorType":"string"
, "StartingSequenceNumber":"string"
, "StreamName":"string"
}
GetRecords
および PutRecords
アクションでは、それぞれ GET
および PUT
メソッドを、名前付きストリームリソース (/records
) に追加される /{stream-name}
リソースで公開します。同様に、PutRecord
アクションは PUT
リソースで /record
メソッドとして公開します。
GetRecords
アクションは、ShardIterator
ヘルパーアクションを呼び出して取得される GetShardIterator
値を入力として受け取るため、GET
リソース (ShardIterator
) で /sharditerator
ヘルパーメソッドを公開します。
次の図は、メソッド作成後のリソースの API 構造を示しています。

次の 4 つの手順では、各メソッドの設定方法、メソッドリクエストから統合リクエストにデータをマッピングする方法、およびメソッドをテストする方法について説明します。
Kinesis で PutRecord
を呼び出すように PUT /streams/{stream-name}/record
メソッドを設定してテストするには
-
次に示すように PUT メソッドを設定します。
-
次のリクエストパラメータマッピングを追加して、
Content-Type
ヘッダーを、統合リクエストの AWS 準拠の JSON に設定します。Content-Type: 'x-amz-json-1.1'
このタスクでは、同じ手順を使用して
GET /streams
メソッドのリクエストパラメータマッピングを設定します。 -
次の本文マッピングテンプレートを追加して、
PUT /streams/{stream-name}/record
メソッドリクエストからPOST /?Action=PutRecord
の該当する統合リクエストにデータをマッピングします。{ "StreamName": "$input.params('stream-name')", "Data": "$util.base64Encode($input.json('$.Data'))", "PartitionKey": "$input.path('$.PartitionKey')" }
このマッピングテンプレートでは、メソッドリクエストのペイロードが次の形式であることを想定しています。
{ "Data": "some data", "PartitionKey": "some key" }
このデータは、次の JSON スキーマでモデル化することができます。
{ "$schema": "http://json-schema.org/draft-04/schema#", "title": "PutRecord proxy single-record payload", "type": "object", "properties": { "Data": { "type": "string" }, "PartitionKey": { "type": "string" } } }
モデルを作成してこのスキーマを含め、このモデルを使用してマッピングテンプレートを生成を容易にすることができます。ただし、モデルを使用せずにマッピングテンプレートを生成することができます。
-
PUT /streams/{stream-name}/record
メソッドをテストするには、stream-name
パス変数を既存のストリームの名前に設定し、必要な形式のペイロードを指定して、メソッドリクエストを送信します。成功した場合の結果は200 OK
レスポンスと、次の形式のペイロードとなります。{ "SequenceNumber": "49559409944537880850133345460169886593573102115167928386", "ShardId": "shardId-000000000004" }
Kinesis で PUT /streams/{stream-name}/records
を呼び出すように PutRecords
メソッドを設定してテストするには
-
次に示すように
PUT /streams/{stream-name}/records
メソッドを設定します。 -
次のリクエストパラメータマッピングを追加して、
Content-Type
ヘッダーを、統合リクエストの AWS 準拠の JSON に設定します。Content-Type: 'x-amz-json-1.1'
このタスクでは、同じ手順を使用して
GET /streams
メソッドのリクエストパラメータマッピングを設定します。 -
次の本文マッピングテンプレートを追加して、
PUT /streams/{stream-name}/records
メソッドリクエストからPOST /?Action=PutRecords
の該当する統合リクエストにデータをマッピングします。{ "StreamName": "$input.params('stream-name')", "Records": [ #foreach($elem in $input.path('$.records')) { "Data": "$util.base64Encode($elem.data)", "PartitionKey": "$elem.partition-key" }#if($foreach.hasNext),#end #end ] }
このマッピングテンプレートでは、メソッドリクエストのペイロードが次の JSON スキーマでモデル化できることを想定しています。
{ "$schema": "http://json-schema.org/draft-04/schema#", "title": "PutRecords proxy payload data", "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "data": { "type": "string" }, "partition-key": { "type": "string" } } } } } }
モデルを作成してこのスキーマを含め、このモデルを使用してマッピングテンプレートを生成を容易にすることができます。ただし、モデルを使用せずにマッピングテンプレートを生成することができます。
このチュートリアルでは、API デベロッパーがバックエンドデータ形式をクライアントに開示するか、クライアントから見えないようにするかを選択できることを示すため、わずかに異なる 2 つのペイロード形式を使用しました。1 つは
PUT /streams/{stream-name}/records
メソッド (上記) 用の形式、もう 1 つはPUT /streams/{stream-name}/record
メソッド (前の手順) 用の形式です。実稼働環境では、両方の形式の一貫性を保ってください。 -
PUT /streams/{stream-name}/records
メソッドをテストするには、stream-name
パス変数を既存のストリームに設定し、前に示したように次のペイロードを指定して、メソッドリクエストを送信します。{ "records": [ { "data": "some data", "partition-key": "some key" }, { "data": "some other data", "partition-key": "some key" } ] }
成功した場合の結果は 200 OK レスポンスと、以下の出力例のようになります。
{ "FailedRecordCount": 0, "Records": [ { "SequenceNumber": "49559409944537880850133345460167468741933742152373764162", "ShardId": "shardId-000000000004" }, { "SequenceNumber": "49559409944537880850133345460168677667753356781548470338", "ShardId": "shardId-000000000004" } ] }
Kinesis で GET /streams/{stream-name}/sharditerator
を呼び出すように GetShardIterator
メソッドを設定してテストするには
GET /streams/{stream-name}/sharditerator
メソッドは、GET
/streams/{stream-name}/records
メソッドを呼び出す前に必須のシャードイテレーターを取得するためのヘルパーメソッドです。
-
次に示すように
GET /streams/{stream-name}/sharditerator
メソッドを設定します。 -
GetShardIterator
アクションでは、ShardId 値を入力する必要があります。クライアントで指定されたShardId
値を渡すため、次に示すように、shard-id
クエリパラメータをメソッドリクエストに追加します。次の本文マッピングテンプレートでは、Kinesis の
shard-id
アクションの入力として、ShardId
クエリパラメータ値を JSON ペイロードのGetShardIterator
プロパティ値に設定します。 -
本文マッピングテンプレートを設定して、必要な入力 (
ShardId
およびStreamName
) を、メソッドリクエストのGetShardIterator
およびshard-id
パラメータのstream-name
アクションに生成します。また、マッピングテンプレートでも、ShardIteratorType
は、デフォルトとしてTRIM_HORIZON
に設定されます。{ "ShardId": "$input.params('shard-id')", "ShardIteratorType": "TRIM_HORIZON", "StreamName": "$input.params('stream-name')" }
-
API Gateway コンソールの [Test (テスト)] オプションを使用して、既存のストリームの名前を
stream-name
の [Path (パス)] 変数値に入力し、shard-id
の [Query string (クエリ文字列)] を既存のShardId
値 (例:shard-000000000004
) に設定して、[Test (テスト)] を選択します。成功のレスポンスペイロードは以下の出力例のようになります。
{ "ShardIterator": "AAAAAAAAAAFYVN3VlFy..." }
ShardIterator
の値をメモしておきます。これは、ストリームからレコードを取得するために必要です。
Kinesis で GET /streams/{stream-name}/records
アクションを呼び出すように GetRecords
メソッドを設定してテストするには
-
次に示すように
GET /streams/{stream-name}/records
メソッドを設定します。 -
GetRecords
オペレーションでは、ShardIterator
の値の入力が必要です。クライアントで指定されたShardIterator
値を渡すため、次に示すように、Shard-Iterator
ヘッダーパラメータをメソッドリクエストに追加します。 -
次のマッピングテンプレートを設定して、
Shard-Iterator
ヘッダーパラメータ値を Kinesis のShardIterator
アクションの JSON ペイロードのGetRecords
プロパティ値にマッピングします。{ "ShardIterator": "$input.params('Shard-Iterator')" }
-
API Gateway コンソールの [Test (テスト)] オプションを使用して、既存のストリームの名前を
stream-name
の [Path (パス)] 変数値に入力し、Shard-Iterator
の [Header (ヘッダー)] をShardIterator
メソッド (上記) のテストの実行で取得したGET /streams/{stream-name}/sharditerator
値に設定して、[Test (テスト)] を選択します。成功のレスポンスペイロードは以下の出力例のようになります。
{ "MillisBehindLatest": 0, "NextShardIterator": "AAAAAAAAAAF...", "Records": [ ... ] }