DynamoDB 低階 API - Amazon DynamoDB
要求格式回應格式資料類型描述項數值資料二進位資料

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

DynamoDB 低階 API

Amazon DynamoDB 低階API是 DynamoDB 的通訊協定層級介面。在此層級，每個 HTTP（S） 請求都必須正確格式化，並攜帶有效的數位簽章。

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

如需低階 DynamoDB 的詳細資訊API，請參閱 Amazon DynamoDB API參考 。

注意

DynamoDB Streams 具有自己的低階 API，與 DynamoDB 的低階 分開，完全由 支援 AWS SDKs。

如需詳細資訊，請參閱DynamoDB Streams 的變更資料擷取。如需低階 DynamoDB 串流 API，請參閱 Amazon DynamoDB 串流API參考 。

低階 DynamoDB API使用 JavaScript Object Notation （JSON） 作為有線通訊協定格式。JSON 會在階層中呈現資料，以便同時傳遞資料值和資料結構。名稱/值對以 name:value 格式定義。資料階層由成對的巢狀括住之名稱與值加以定義。

DynamoDB JSON僅用作傳輸通訊協定，而不是儲存格式。使用 AWS SDKsJSON將資料傳送至 DynamoDB ，DynamoDB 會以 回應JSON。DynamoDB 不會持續以 JSON 格式儲存資料。

注意

如需 的詳細資訊JSON，請參閱 JSON.org 網站上的簡介JSON。

DynamoDB 低階API，以及如何處理 AWS SDKs通訊協定層級的請求和回應。

要求格式

DynamoDB 低階API接受 HTTP（S） POST請求作為輸入。為您 AWS SDKs建構這些請求。

假設您有一個名為 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 版簽署程序Amazon Web Services 一般參考。

  • X-Amz-Target 標頭包含 DynamoDB 操作的名稱：GetItem。（這也會隨附低階API版本，在此情況下為 20120810。）

  • 請求的承載 （內文） 包含 操作的參數，JSON格式為 。若是 GetItem 操作，參數為 TableName 與 Key。

回應格式

收到請求時，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 SDK會將回應資料傳回至您的應用程式，以供進一步處理。

注意

如果 DynamoDB 無法處理請求，則會傳回HTTP錯誤碼和訊息。會以例外狀況的形式將這些 AWS SDK傳播到您的應用程式。如需詳細資訊，請參閱使用 DynamoDB 時發生錯誤。

資料類型描述項

低階 DynamoDB API通訊協定要求每個屬性都伴隨資料類型描述符。資料類型描述項是告知 DynamoDB 如何解譯每項屬性的字符。

「要求格式」與「回應格式」中的範例，展示如何使用資料類型描述項的範例。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：二進位集合

注意

如需 DynamoDB 資料類型的詳細說明，請參閱 資料類型。

數值資料

不同的程式設計語言為 提供不同層級的支援JSON。在某些情況下，您可能會決定使用第三方程式庫來驗證和剖析JSON文件。

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

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

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

二進位資料

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

DynamoDB 使用的 base64 編碼結構描述於網際網路工程任務小組 （IETF） 網站上的 RFC 4648。