Amazon DynamoDB
開発者ガイド (API バージョン 2012-08-10)

DynamoDB 低レベル API

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

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

低レベル DynamoDB API の詳細については、「Amazon DynamoDB API Reference」を参照してください。

注記

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

詳細については、「DynamoDB ストリーム を使用したテーブルアクティビティのキャプチャ」を参照してください。低レベルの DynamoDB ストリーム API については、「DynamoDB ストリーム API リファレンス」を参照してください。

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

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

注記

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

リクエストの形式

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

ペットという名のテーブルに、AnimalType (パーティションキー)、Name (ソートキー) によって構成されるキースキーマがあるとします。これらの属性は両方とも文字列型になります。ペットからある項目を取り出すために、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 がリクエストを認証するのに必要な情報が含まれています。詳細については、アマゾン ウェブ サービス全般のリファレンスの「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 API のプロトコルは、各属性がデータ型記述子に伴われる必要があります。データ型記述子は、各属性を解釈する方法を DynamoDB に伝えるトークンです。

リクエストの形式レスポンスの形式には、データ型記述子が使用されている例が示されています。GetItem リクエストは、ペットキースキーマ属性 (AnimalTypeName) のための S を文字列で指定します。GetItem レスポンスには、文字列 (S)、数値 (N)、マップ (M)、リスト (L) の属性のあるペット項目が含まれます。

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

  • S – 文字列

  • N – 数値

  • B – バイナリ

  • BOOL – ブール

  • NULL – Null

  • M – マップ

  • L – リスト

  • SS – 文字列セット

  • NS – 数値セット

  • BS – バイナリセット

注記

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

数値データ

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

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

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

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

バイナリデータ

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

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