# DynamoDB 低レベル API
Amazon DynamoDB の*低レベル API* は、DynamoDB 用のプロトコルレベルのインターフェイスです。このレベルでは、すべての HTTP リクエストは、適切な形式で有効なデジタル署名がある必要があります。
AWS SDK は、低レベル DynamoDB API リクエストをユーザーに代わって作成し、DynamoDB からのレスポンスを処理します。これにより、低レベルの詳細ではなく、アプリケーションロジックに専念することができます。ただし、低レベル DynamoDB API の動作方法についての基本的な知識も役立ちます。
低レベル DynamoDB API の詳細については、[Amazon DynamoDB API リファレンス](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)を参照してください。
**注記**
DynamoDB Streams には、DynamoDB とは別に独自の低レベル API があり、AWS SDK で完全にサポートされています。
詳細については、「[DynamoDB Streams の変更データキャプチャ](Streams.md)」を参照してください。低レベル DynamoDB Streams API については、[Amazon DynamoDB Streams API リファレンス](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Operations_Amazon_DynamoDB_Streams.html)を参照してください。
低レベル DynamoDB API は、ワイヤプロトコル形式として、JavaScript Object Notation (JSON) を使用しています。JSON では、データ値とデータ構造が両方同時にわかるように、データが階層で示されます。名前と値のペアは、`name:value` の形式で定義されます。データ階層は、名前と値のペアをブラケットで囲み、ネストする形で定義します。
DynamoDB は、ストレージ形式としてではなく、トランスポートプロトコルとしてのみ、JSON を使用しています。JSON を使用して AWS SDK が DynamoDB にデータを送信し、DynamoDB が JSON で応答します。DynamoDB は、JSON 形式でデータを永続的に保存しません。
**注記**
JSON の詳細については、`JSON.org` ウェブサイトで「[JSON の入門](http://json.org)」を参照してください。
**Topics**
+ [リクエストの形式](#Programming.LowLevelAPI.RequestFormat)
+ [レスポンスの形式](#Programming.LowLevelAPI.ResponseFormat)
+ [データ型記述子](#Programming.LowLevelAPI.DataTypeDescriptors)
+ [数値データ](#Programming.LowLevelAPI.Numbers)
+ [バイナリデータ](#Programming.LowLevelAPI.Binary)
![\[DynamoDB の低レベル API、および AWS SDK によるプロトコルレベルのリクエストとレスポンスの処理方法。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/SDKSupport.DDBLowLevelAPI.png)
## リクエストの形式
DynamoDB 低レベル API は、HTTP(S) `POST` リクエストを入力として受け付けます。AWS SDK はこれらのリクエストを作成します。
`Pets` という名のテーブルに、`AnimalType` (パーティションキー)、`Name` (ソートキー) によって構成されるキースキーマがあるとします。これらの属性はいずれも、`string` 型になります。`Pets` から項目を取得するために、AWS SDK は次のリクエストを作成します。
```
POST / HTTP/1.1
Host: dynamodb..;
Accept-Encoding: identity
Content-Length:
User-Agent:
Content-Type: application/x-amz-json-1.0
Authorization: AWS4-HMAC-SHA256 Credential=, SignedHeaders=, Signature=
X-Amz-Date:
X-Amz-Target: DynamoDB_20120810.GetItem
{
"TableName": "Pets",
"Key": {
"AnimalType": {"S": "Dog"},
"Name": {"S": "Fido"}
}
}
```
このリクエストに関して以下の点に注意してください。
+ `Authorization` ヘッダーには、DynamoDB がリクエストを認証するのに必要な情報が含まれています。詳細は、「*Amazon Web Services 全般のリファレンス*」の「[AWS API リクエストへの署名](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html)」と「[署名バージョン 4 の署名プロセス](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)」を参照してください。
+ `X-Amz-Target` ヘッダーには、DynamoDB オペレーションの名前である `GetItem` が含まれます 。(これは、低レベル API バージョンと共に示されます。この場合は `20120810` となります。)
+ リクエストのペイロード (本文) には、JSON 形式で、オペレーションのパラメーターが含まれます。`GetItem` オペレーションでは、パラメーターは `TableName` と `Key` です。
## レスポンスの形式
リクエストを受け取ったら、DynamoDB が処理しレスポンスを返します。前の例に示したように、HTTP レスポンスペイロードには、オペレーションからの結果が含まれます。
```
HTTP/1.1 200 OK
x-amzn-RequestId:
x-amz-crc32:
Content-Type: application/x-amz-json-1.0
Content-Length:
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 でのエラー処理](Programming.Errors.md)」を参照してください。
## データ型記述子
低レベル DynamoDB API のプロトコルは、各属性がデータ型記述子に伴われる必要があります。*データ型記述子*は、各属性を解釈する方法を DynamoDB に伝えるトークンです。
[リクエストの形式](#Programming.LowLevelAPI.RequestFormat)と[レスポンスの形式](#Programming.LowLevelAPI.ResponseFormat)には、データ型記述子が使用されている例が示されています。`GetItem` リクエストでは、`S` キースキーマ属性 (`Pets` と `AnimalType`) に `Name` を `string` 型で指定します。`GetItem` レスポンスには、`string` (`S`)、`number` (`N`)、`map` (`M`)、`list` (`L`) 型の属性を持つ、*Pets* 項目が含まれます。
DynamoDB データ型記述子の一覧を次に示します。
+ **`S`** — 文字列
+ **`N`** — 数値
+ **`B`** — バイナリ
+ **`BOOL`** — ブール
+ **`NULL`** — Null
+ **`M`** — マップ
+ **`L`** — リスト
+ **`SS`** — 文字列セット
+ **`NS`** — 数値セット
+ **`BS`** — バイナリセット
次の表は、各データ型記述子の正しい JSON 形式を示しています。数値は精度を維持するために文字列として表されますが、ブール値と null はネイティブの JSON 型を使用することに注意してください。
| ディスクリプタ | JSON 形式 | 注意事項 |
| --- | --- | --- |
| S | \$1"S": "Hello"\$1 | 値は JSON 文字列です。 |
| N | \$1"N": "123.45"\$1 | 値は文字列であり、JSON 数値ではありません。これにより、言語間で精度が維持されます。 |
| B | \$1"B": "dGhpcyBpcyBhIHRlc3Q="\$1 | 値は base64 でエンコードされた文字列です。 |
| BOOL | \$1"BOOL": true\$1 | 値は JSON ブール値 (true または false) で、文字列ではありません。 |
| NULL | \$1"NULL": true\$1 | 値は null を示す JSON ブール値 true です。 |
| M | \$1"M": \$1"Name": \$1"S": "Joe"\$1\$1\$1 | 値は、属性名と値のペアの JSON オブジェクトです。 |
| L | \$1"L": [\$1"S": "Red"\$1, \$1"N": "5"\$1]\$1 | 値は属性値の JSON 配列です。 |
| SS | \$1"SS": ["Red", "Blue"]\$1 | 値は文字列の JSON 配列です。 |
| NS | \$1"NS": ["1", "2.5"]\$1 | 値は数値文字列の JSON 配列です。 |
| BS | \$1"BS": ["U3Vubnk=", "UmFpbnk="]\$1 | 値は base64 でエンコードされた文字列の JSON 配列です。 |
**注記**
DynamoDB データ型の詳細な説明については、「[データ型](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes)」を参照してください。
## 数値データ
プログラミング言語により、提供される JSON のサポートのレベルが異なります。場合によっては、JSONドキュメントを検証し解析するにあたり、サードパーティーのライブラリを使用することもできます。
JSON Number 型に基づいて構築されたサードパーティーライブラリもあり、`int` や `long`、`double` など独自の型を提供しています。ただし、他のデータ型に正確にマッピングされない DynamoDB のネイティブ数値データ型が使用されるため、このようなデータ型の区別が競合の原因になる可能性があります。加えて、多くの JSON ライブラリでは固定精度の数値は処理されず、小数点を含む数字列は自動的に倍精度浮動小数点データ型であると推定されます。
これらの問題を解決するために、DynamoDB ではデータ損失のない単一の数値型が用意されています。誤って倍精度の値に暗黙的変換が行われないように、DynamoDB では数値のデータ転送には文字列が使用されます。この方法によって、01、2、03 などの値を適切な順序で配置するなど、適切な並べ替えセマンティクスを維持しながら、柔軟に属性値を更新することが可能になります。
数値の精度がアプリケーションにとって重要な場合は、数値を文字列に変換してから、DynamoDB に渡します。
## バイナリデータ
DynamoDB ではバイナリ属性がサポートされています。ただし JSON では、ネイティブではバイナリデータのエンコードがサポートされていません。リクエストでバイナリデータを送信するには、base64 形式でエンコードする必要があります。DynamoDB はリクエストを受け取ると、base64 データをバイナリに復号します。
DynamoDB で使用される base64 エンコーディングスキームは、Internet Engineering Task Force (IETF) ウェブサイトの「[RFC 4648](http://tools.ietf.org/html/rfc4648)」に記載されています。