DynamoDB 低レベル API - Amazon DynamoDB

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

DynamoDB 低レベル API

Amazon DynamoDB の低レベル API は、DynamoDB 用のプロトコルレベルのインターフェイスです。このレベルでは、すべての HTTP リクエストは、適切な形式で有効なデジタル署名がある必要があります。

AWS SDK は、低レベル DynamoDB API リクエストをユーザーに代わって作成し、DynamoDB からのレスポンスを処理します。これにより、低レベルの詳細ではなく、アプリケーションロジックに専念することができます。ただし、低レベル DynamoDB API の動作方法についての基本的な知識も役立ちます。

低レベル DynamoDB API の詳細については、Amazon DynamoDB API リファレンスを参照してください。

注記

DynamoDB Streams には、DynamoDB とは別に独自の低レベル API があり、AWS SDK で完全にサポートされています。

詳細については、「DynamoDB Streams の変更データキャプチャ」を参照してください。低レベル DynamoDB Streams API については、Amazon DynamoDB Streams API リファレンスを参照してください。

低レベル DynamoDB API は、ワイヤプロトコル形式として JavaScript Object Notation (JSON) を使用します。JSON では、データ値とデータ構造が両方同時にわかるように、データが階層で示されます。名前と値のペアは、name:value の形式で定義されます。データ階層は、名前と値のペアをブラケットで囲み、ネストする形で定義します。

DynamoDB は、ストレージ形式としてではなく、トランスポートプロトコルとしてのみ、JSON を使用しています。JSON を使用して AWS SDK が DynamoDB にデータを送信し、DynamoDB が JSON で応答します。DynamoDB は、JSON 形式でデータを永続的に保存しません。

注記

JSON の詳細については、JSON.org ウェブサイトで「JSON の入門」を参照してください。

リクエストの形式

DynamoDB 低レベル API は、HTTP(S) POST リクエストを入力として受け付けます。AWS SDK はこれらのリクエストを作成します。

Pets という名のテーブルに、AnimalType (パーティションキー)、Name (ソートキー) によって構成されるキースキーマがあるとします。これらの属性はいずれも、string 型になります。Pets から項目を取得するために、AWS SDK は次のリクエストを作成します。

POST / HTTP/1.1 Host: dynamodb.<region>.<domain>; Accept-Encoding: identity Content-Length: <PayloadSizeBytes> User-Agent: <UserAgentString> Content-Type: application/x-amz-json-1.0 Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=<Headers>, Signature=<Signature> X-Amz-Date: <Date> X-Amz-Target: DynamoDB_20120810.GetItem { "TableName": "Pets", "Key": { "AnimalType": {"S": "Dog"}, "Name": {"S": "Fido"} } }

このリクエストに関して以下の点に注意してください。

  • Authorization ヘッダーには、DynamoDB がリクエストを認証するのに必要な情報が含まれています。詳細は、「Amazon Web Services 全般のリファレンス」の「AWS API リクエストへの署名」と「署名バージョン 4 の署名プロセス」を参照してください。

  • X-Amz-Target ヘッダーには、DynamoDB オペレーションの名前である GetItem が含まれます 。(これは、低レベル API バージョンと共に示されます。この場合は 20120810 となります。)

  • リクエストのペイロード (本文) には、JSON 形式で、オペレーションのパラメーターが含まれます。GetItem オペレーションでは、パラメーターは TableNameKey です。

レスポンスの形式

リクエストを受け取ったら、DynamoDB が処理しレスポンスを返します。前の例に示したように、HTTP レスポンスペイロードには、オペレーションからの結果が含まれます。

HTTP/1.1 200 OK x-amzn-RequestId: <RequestId> x-amz-crc32: <Checksum> Content-Type: application/x-amz-json-1.0 Content-Length: <PayloadSizeBytes> Date: <Date> { "Item": { "Age": {"N": "8"}, "Colors": { "L": [ {"S": "White"}, {"S": "Brown"}, {"S": "Black"} ] }, "Name": {"S": "Fido"}, "Vaccinations": { "M": { "Rabies": { "L": [ {"S": "2009-03-17"}, {"S": "2011-09-21"}, {"S": "2014-07-08"} ] }, "Distemper": {"S": "2015-10-13"} } }, "Breed": {"S": "Beagle"}, "AnimalType": {"S": "Dog"} } }

この時点で、AWS SDK は、さらに処理するためにアプリケーションに応答データを返します。

注記

リクエストを処理できない場合は、DynamoDB より HTTP エラーコードとメッセージが返ります。AWS SDK は、これらを例外形式でアプリケーションに伝達します。詳細については、「DynamoDB でのエラー処理」を参照してください。

データ型記述子

低レベル DynamoDB API のプロトコルは、各属性がデータ型記述子に伴われる必要があります。データ型記述子は、各属性を解釈する方法を DynamoDB に伝えるトークンです。

リクエストの形式レスポンスの形式には、データ型記述子が使用されている例が示されています。GetItem リクエストでは、S キースキーマ属性 (PetsAnimalType) に Namestring 型で指定します。GetItem レスポンスには、string (S)、number (N)、map (M)、list (L) 型の属性を持つ、Pets 項目が含まれます。

DynamoDB データ型記述子の一覧を次に示します。

  • S — 文字列

  • N — 数値

  • B — バイナリ

  • BOOL — ブール

  • NULL — Null

  • M — マップ

  • L — リスト

  • SS — 文字列セット

  • NS — 数値セット

  • BS — バイナリセット

注記

DynamoDB データ型の詳細な説明については、「データ型」を参照してください。

数値データ

プログラミング言語により、提供される JSON のサポートのレベルが異なります。場合によっては、JSONドキュメントを検証し解析するにあたり、サードパーティーのライブラリを使用することもできます。

JSON Number 型に基づいて構築されたサードパーティーライブラリもあり、intlongdouble など独自の型を提供しています。ただし、他のデータ型に正確にマッピングされない DynamoDB のネイティブ数値データ型が使用されるため、このようなデータ型の区別が競合の原因になる可能性があります。加えて、多くの JSON ライブラリでは固定精度の数値は処理されず、小数点を含む数字列は自動的に倍精度浮動小数点データ型であると推定されます。

これらの問題を解決するために、DynamoDB ではデータ損失のない単一の数値型が用意されています。誤って倍精度の値に暗黙的変換が行われないように、DynamoDB では数値のデータ転送には文字列が使用されます。この方法によって、01、2、03 などの値を適切な順序で配置するなど、適切な並べ替えセマンティクスを維持しながら、柔軟に属性値を更新することが可能になります。

数値の精度がアプリケーションにとって重要な場合は、数値を文字列に変換してから、DynamoDB に渡します。

バイナリデータ

DynamoDB ではバイナリ属性がサポートされています。ただし JSON では、ネイティブではバイナリデータのエンコードがサポートされていません。リクエストでバイナリデータを送信するには、base64 形式でエンコードする必要があります。DynamoDB はリクエストを受け取ると、base64 データをバイナリに復号します。

DynamoDB で使用される base64 エンコーディングスキームは、Internet Engineering Task Force (IETF) ウェブサイトの「RFC 4648」に記載されています。