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

DynamoDB 低レベル API

Amazon DynamoDB の低レベル API は、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 は、JSON を使用して DynamoDB にデータを送信し、DynamoDB は JSON で応答します。DynamoDB では JSON 形式でデータを永続的に保存していません。

注記

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

リクエストの形式

DynamoDB 低レベル API は、HTTP 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 がリクエストを認証するのに必要な情報が含まれています。詳細については、アマゾン ウェブ サービス全般のリファレンスの「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 リクエストでは、Pets キースキーマ属性 (AnimalTypeName) に Sstring 型で指定します。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」に記載されています。