Scan - Amazon DynamoDB
描述請求回應特殊錯誤範例相關動作

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

Scan

重要

本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。

如需目前低階 API 的文件，請參閱Amazon DynamoDB API 參考。

描述

Scan 操作會執行資料表完整掃描來傳回一或多個項目及其屬性。提供 ScanFilter 以取得更特定的結果。

注意

如果已掃描項目總數超過 1MB 限制，則掃描會停止，並將結果傳回給使用者，附帶 LastEvaluatedKey 用以在後續操作中繼續掃描。結果還包括超出限制的項目數。掃描可能導致表內資料皆不符合篩選條件。

結果集為最終一致性。

請求

語法

// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.Scan  
content-type: application/x-amz-json-1.0

{"TableName":"Table1",
    "Limit": 2,
    "ScanFilter":{
        "AttributeName1":{"AttributeValueList":[{"S":"AttributeValue"}],"ComparisonOperator":"EQ"}
    },
    "ExclusiveStartKey":{
        "HashKeyElement":{"S":"AttributeName1"},
        "RangeKeyElement":{"N":"AttributeName2"}
    },
    "AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]},
}
名稱 描述 必要
TableName

包含請求項目的資料表的名稱。

類型：字串

 是
AttributesToGet

屬性名稱陣列。如果未指定屬性名稱，則會傳回所有屬性。如果有部分屬性未找到，則這些屬性不會出現在結果中。

類型：陣列

 否
Limit

要評估的項目數上限 (不一定是相符的項目數)。如果 DynamoDB 在處理結果時處理的項目數達上限，則會停止工作，並傳回截至該時間點的相符值，附帶 LastEvaluatedKey 以套用於後續操作中繼續擷取項目。此外，如果在 DynamoDB 達到此限制之前已掃描的資料集大小超過 1MB，則會停止掃描，並傳回截至上限的相符值，附帶 LastEvaluatedKey 以套用於後續操作中繼續掃描。

類型：數字

 否
Count

如果設定為 true，則 DynamoDB 會傳回掃描操作的項目總數，即使操作沒有指派篩選條件的相符項目也一樣。您可以套用限制參數至僅計數查詢。

請勿在提供 AttributesToGet 清單之時將 Count 設定為 true，否則 DynamoDB 會傳回驗證錯誤。如需詳細資訊，請參閱 計算結果中的項目。

類型：布林值

 否
ScanFilter

評估掃描結果，並僅傳回所需值。多個條件會視為 AND 操作：必須符合所有條件才會納入結果中。

類型：具有比較運算子的值的屬性名稱映射。

 否
ScanFilter:AttributeValueList

用來評估篩選條件掃描結果的值和條件。

類型：Condition 的 AttributeValue 映射。

 否
ScanFilter:​ ComparisonOperator

用於評估所提供的屬性的條件，例如等於、大於。以下是掃描操作的有效比較運算子。

注意

大於、等於或小於的字串值比較是根據 ASCII 字元代碼值。例如，a 大於 A，aa 大於 B。如需代碼值的清單，請參閱 http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters。

針對 Binary，每當 DynamoDB 比較二進位值，例如在評估查詢表達式時，都會將二進位資料的每個位元組視為不帶正負號。

類型：字串或二進位

 否
 

EQ：等於。

對於 EQ，AttributeValueList 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 AttributeValue。如果項目內含的 AttributeValue 所屬類型與請求中指定的類型不同，則數值不相符。例如，{"S":"6"} 不等於 {"N":"6"}。另外，{"N":"6"} 不等於 {"NS":["6", "2", "1"]}。

  
 

NE：不等於。

對於 NE，AttributeValueList 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 AttributeValue。如果項目內含的 AttributeValue 所屬類型與請求中指定的類型不同，則數值不相符。例如，{"S":"6"} 不等於 {"N":"6"}。另外，{"N":"6"} 不等於 {"NS":["6", "2", "1"]}。

  
 

LE：小於或等於。

對於 LE，AttributeValueList 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 AttributeValue。如果項目內含的 AttributeValue 所屬類型與請求中指定的類型不同，則數值不相符。例如，{"S":"6"} 不等於 {"N":"6"}。另外，{"N":"6"} 不與 {"NS":["6", "2", "1"]} 比較。

  
 

LT：小於。

對於 LT，AttributeValueList 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 AttributeValue。如果項目內含的 AttributeValue 所屬類型與請求中指定的類型不同，則數值不相符。例如，{"S":"6"} 不等於 {"N":"6"}。另外，{"N":"6"} 不與 {"NS":["6", "2", "1"]} 比較。

  
 

GE：大於或等於。

對於 GE，AttributeValueList 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 AttributeValue。如果項目內含的 AttributeValue 所屬類型與請求中指定的類型不同，則數值不相符。例如，{"S":"6"} 不等於 {"N":"6"}。另外，{"N":"6"} 不與 {"NS":["6", "2", "1"]} 比較。

  
 

GT：大於。

對於 GT，AttributeValueList 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 AttributeValue。如果項目內含的 AttributeValue 所屬類型與請求中指定的類型不同，則數值不相符。例如，{"S":"6"} 不等於 {"N":"6"}。另外，{"N":"6"} 不與 {"NS":["6", "2", "1"]} 比較。

  
 

NOT_NULL：屬性存在。

  
 

NULL：屬性不存在。

  
 

CONTAINS：檢查子序列，或是集合中的數值。

對於 CONTAINS，AttributeValueList 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 AttributeValue。如果比較的目標屬性是字串，則操作會檢查相符子字串。如果比較的目標屬性是二進位，則操作會尋找與輸入相符的目標子序列。如果比較的目標屬性是集合 (SS、NS 或 BS)，則操作會檢查集合的成員 (不當作子字串)。

  
 

NOT_CONTAINS：檢查子序列是否不存在，或者集合中的數值是否不存在。

對於 NOT_CONTAINS，AttributeValueList 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 AttributeValue。如果比較的目標屬性是字串，則操作會檢查相符子字串是否不存在。如果比較的目標屬性是二進位，則操作會檢查與輸入相符的目標子序列是否不存在。如果比較的目標屬性是集合 (SS、NS 或 BS)，則操作會檢查集合的成員 (不當作子字串) 是否不存在。

  
 

BEGINS_WITH：檢查字首。

對於 BEGINS_WITH，AttributeValueList 僅可包含 String 或 Binary 類型 (非 Number 或集合) 的一個 AttributeValue。比較的目標屬性必須是 String 或 Binary (非 Number 或集合)。

  
 

IN：檢查完全相符項目。

對於 IN，AttributeValueList 可以包含 String、Number 或 Binary 類型 (非集合) 的多個 AttributeValue。比較的目標屬性必須為相同的類型和確切數值才相符。String 一律不與 String 集合相符。

  
 

BETWEEN：大於或等於第一個數值，並且小於或等於第二個數值。

對於 BETWEEN，AttributeValueList 必須包含 String、Number 或 Binary 類型 (非集合) 的兩個 AttributeValue 元素。如果目標數值大於或等於第一個元素，並且小於或等於第二個元素，則目標屬性相符。如果項目內含的 AttributeValue 所屬類型與請求中指定的類型不同，則數值不相符。例如，{"S":"6"} 不與 {"N":"6"} 比較。另外，{"N":"6"} 不與 {"NS":["6", "2", "1"]} 比較。

  
ExclusiveStartKey

繼續先前掃描之項目的主索引鍵。如果因為結果集大小或 Limit 參數，導致掃描操作在整個資料表掃描完之前中斷，較早的掃描可能提供此值。LastEvaluatedKey 可以在新的掃描請求中傳回，以便從該時間點繼續操作。

類型：複合主索引鍵的 HashKeyElement 或 HashKeyElement 和 RangeKeyElement。

 否

回應

語法

HTTP/1.1 200 
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375 
content-type: application/x-amz-json-1.0
content-length: 229 

{"Count":2,"Items":[{
    "AttributeName1":{"S":"AttributeValue1"},
    "AttributeName2":{"S":"AttributeValue2"},
    "AttributeName3":{"S":"AttributeValue3"}
    },{
    "AttributeName1":{"S":"AttributeValue4"},
    "AttributeName2":{"S":"AttributeValue5"},
    "AttributeName3":{"S":"AttributeValue6"},
    "AttributeName5":{"B":"dmFsdWU="}
    }],
    "LastEvaluatedKey":
        {"HashKeyElement":{"S":"AttributeName1"},
        "RangeKeyElement":{"N":"AttributeName2"},
    "ConsumedCapacityUnits":1,
    "ScannedCount":2}
}
名稱 描述
Items

符合操作參數的屬性的容器。

類型：屬性名稱映射，以及其資料類型和值。
Count

回應中的項目數。如需詳細資訊，請參閱 計算結果中的項目。

類型：數字
ScannedCount

套用任何篩選條件之前的已完成掃描中項目數。ScannedCount 值很高，但 Count 結果很少或沒有，表示掃描操作不足。如需詳細資訊，請參閱 計算結果中的項目。

類型：數字
LastEvaluatedKey 停止掃描操作之項目的主索引鍵。在後續掃描操作中提供此值，以便從該時間點繼續操作。

當整個掃描結果集完成時 (意即操作已處理「最後一頁」)，LastEvaluatedKey 為 null。
ConsumedCapacityUnits

操作所使用的讀取容量單位數目。此值顯示套用至佈建輸送量的數字。如需詳細資訊，請參閱 DynamoDB 佈建容量模式。

類型：數字

特殊錯誤

錯誤 描述
ResourceNotFoundException 找不到指定的資料表。

範例

如需使用 AWS SDK 的範例，請參閱掃描 DynamoDB 中的資料表。

請求範例

// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.Scan 
content-type: application/x-amz-json-1.0

{"TableName":"1-hash-rangetable","ScanFilter":{}}

回應範例

HTTP/1.1 200
x-amzn-RequestId: 4e8a5fa9-71e7-11e0-a498-71d736f27375 
content-type: application/x-amz-json-1.0 
content-length: 465 

{"Count":4,"Items":[{
	"date":{"S":"1980"},
	"fans":{"SS":["Dave","Aaron"]},
	"name":{"S":"Airplane"},
	"rating":{"S":"***"}
	},{
	"date":{"S":"1999"},
	"fans":{"SS":["Ziggy","Laura","Dean"]},
	"name":{"S":"Matrix"},
	"rating":{"S":"*****"}
	},{
	"date":{"S":"1976"},
	"fans":{"SS":["Riley"]},"
	name":{"S":"The Shaggy D.A."},
	"rating":{"S":"**"}
	},{
	"date":{"S":"1985"},
	"fans":{"SS":["Fox","Lloyd"]},
	"name":{"S":"Back To The Future"},
	"rating":{"S":"****"}
	}],
    "ConsumedCapacityUnits":0.5
	"ScannedCount":4}

請求範例

// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.Scan 
content-type: application/x-amz-json-1.0
content-length: 125 

{"TableName":"comp5",
	"ScanFilter":
		{"time":
			{"AttributeValueList":[{"N":"400"}],
			"ComparisonOperator":"GT"}
	}
}

回應範例

HTTP/1.1 200 OK
x-amzn-RequestId: PD1CQK9QCTERLTJP20VALJ60TRVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 262
Date: Mon, 15 Aug 2011 16:52:02 GMT

{"Count":2,
	"Items":[
		{"friends":{"SS":["Dave","Ziggy","Barrie"]},
		"status":{"S":"chatting"},
		"time":{"N":"2000"},
		"user":{"S":"Casey"}},
		{"friends":{"SS":["Dave","Ziggy","Barrie"]},
		"status":{"S":"chatting"},
		"time":{"N":"2000"},
		"user":{"S":"Fredy"}
		}],
"ConsumedCapacityUnits":0.5
"ScannedCount":4
}

請求範例

// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.Scan
content-type: application/x-amz-json-1.0

{"TableName":"comp5",
	"Limit":2,
	"ScanFilter":
		{"time":
			{"AttributeValueList":[{"N":"400"}],
			"ComparisonOperator":"GT"}
	},
	"ExclusiveStartKey":
		{"HashKeyElement":{"S":"Fredy"},"RangeKeyElement":{"N":"2000"}}
}

回應範例

HTTP/1.1 200 OK
x-amzn-RequestId: PD1CQK9QCTERLTJP20VALJ60TRVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 232
Date: Mon, 15 Aug 2011 16:52:02 GMT

{"Count":1,
	"Items":[
		{"friends":{"SS":["Jane","James","John"]},
		"status":{"S":"exercising"},
		"time":{"N":"2200"},
		"user":{"S":"Roger"}}
	],
	"LastEvaluatedKey":{"HashKeyElement":{"S":"Riley"},"RangeKeyElement":{"N":"250"}},
"ConsumedCapacityUnits":0.5
"ScannedCount":2
}