本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# DynamoDB 低階 API
<a name="Programming.LowLevelAPI"></a>

Amazon DynamoDB *低階 API* 為 DynamoDB 的協定層級介面。在此層級中，每個 HTTP(S) 要求都必須依照正確的格式，並附上有效的數位簽章。

 AWS SDKs 會代表您建構低階 DynamoDB API 請求，並處理來自 DynamoDB 的回應。您如此即可專注於應用程式的邏輯，而非低階的結節。但您仍可從了解低階 DynamoDB API 運作方式的基本知識中獲益。

如需低階 DynamoDB API 的詳細資訊，請參閱《[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)》。

**注意**  
DynamoDB Streams 有自己的低階 API，與 DynamoDB 的低階 API 不同，且完全由 AWS SDKs 支援。  
如需詳細資訊，請參閱[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 物件表示法 (JSON) 作為接線協定格式。JSON 以階層顯示資料，以便同時傳達資料值和資料結構。名稱/值對以 `name:value` 格式定義。資料階層由成對的巢狀括住之名稱與值加以定義。

DynamoDB 只會使用 JSON 作為傳輸協定，而非儲存格式。 AWS SDKs 使用 JSON 將資料傳送至 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 SDKs處理通訊協定層級請求和回應的方式。\]](http://docs.aws.amazon.com/zh_tw/amazondynamodb/latest/developerguide/images/SDKSupport.DDBLowLevelAPI.png)


## 要求格式
<a name="Programming.LowLevelAPI.RequestFormat"></a>

DynamoDB 低階 API 接受 HTTP(S) `POST` 請求作為輸入。 AWS 軟體開發套件會為您建構這些請求。

假設您有一個名為 `Pets` 的資料表，其索引鍵結構描述由 `AnimalType` (分割區索引鍵) 及 `Name` (排序索引鍵) 所組成。這些屬性的類型皆為 `string`。若要從 擷取項目`Pets`，軟體 AWS 開發套件會建構下列請求。

```
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 請求](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)*Amazon Web Services 一般參考*。
+ `X-Amz-Target` 標頭包含 DynamoDB 操作的名稱：`GetItem`。(此也會同時附上低階 API 版本，在此案例中為 `20120810`。)
+ 要求的承載 (主體) 包含操作的參數 (JSON 格式)。若是 `GetItem` 操作，參數為 `TableName` 與 `Key`。

## 回應格式
<a name="Programming.LowLevelAPI.ResponseFormat"></a>

收到請求時，DynamoDB 會處理該請求並會傳回回應。針對前述的要求，HTTP(S) 回應承載會包含操作的結果，如下列範例中所示。

```
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 軟體開發套件會將回應資料傳回至您的應用程式，以供進一步處理。

**注意**  
若 DynamoDB 無法處理請求，其會傳回 HTTP 錯誤碼及訊息。 AWS 軟體開發套件會以例外狀況的形式，將這些傳播到您的應用程式。如需詳細資訊，請參閱[使用 DynamoDB 時發生錯誤](Programming.Errors.md)。

## 資料類型描述項
<a name="Programming.LowLevelAPI.DataTypeDescriptors"></a>

低階 DynamoDB API 協定需要每個屬性都要附有一個資料類型的描述項。*資料類型描述項*是告知 DynamoDB 如何解譯每項屬性的字符。

「[要求格式](#Programming.LowLevelAPI.RequestFormat)」與「[回應格式](#Programming.LowLevelAPI.ResponseFormat)」中的範例，展示如何使用資料類型描述項的範例。`GetItem` 要求指定 `Pets` 索引鍵結構描述屬性 (`AnimalType` 與 `Name`) 為 `S`，即類型為 `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 format (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 | 值是true表示 null 的 JSON 布林值。 | 
| 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)。

## 數值資料
<a name="Programming.LowLevelAPI.Numbers"></a>

不同的程式語言提供不同程度的 JSON 支援。在某些情況下，您可能會決定要使用第三方的程式庫進行 JSON 文件之驗證及剖析。

某些第三方程式庫會依據 JSON 數字類型建置，提供其本身的類型，例如 `int`、`long` 或 `double`。但 DynamoDB 中的原生數字資料類型，無法精確地映射到這些其他資料類型，所以這些類型的差異可能會導致衝突。此外，許多 JSON 程式庫不會處理固定精確度的數值，而是會自動針對包含小數點的數字，推斷為雙精確度資料類型。

為解決這些問題，DynamoDB 提供了不會造成資料遺失的單一數字類型。為避免不必要的隱含轉換為雙精確度值，DynamoDB 使用字串來進行數值資料傳輸。此方法提供了更新屬性值的彈性，同時還能維持適當的排序語意，例如將值 "01"、"2" 及 "03" 依適當的順序排列。

若數字精確度對您的應用程式來說很重要，則應在將其傳遞至 DynamoDB 之前，先將數值轉換為字串。

## 二進位資料
<a name="Programming.LowLevelAPI.Binary"></a>

DynamoDB 支援二進制屬性。但 JSON 原本並不支援二進位資料的編碼。若要在要求中傳送二進位資料，您必須將其編碼為 Base64 格式。在接收到請求時，DynamoDB 會將 Base64 資料解碼回二進位。

DynamoDB 使用的 base64 編碼結構描述會在 Internet Engineering Task Force (IETF) 網站上的 [RFC 4648](http://tools.ietf.org/html/rfc4648) 說明。