本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Scan **重要** ***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。*** **如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。** ## 描述 `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 會傳回驗證錯誤。如需詳細資訊，請參閱 [計算結果中的項目](Scan.md#Scan.Count)。類型：布林值 | 否 | | ScanFilter | 評估掃描結果，並僅傳回所需值。多個條件會視為 AND 操作：必須符合所有條件才會納入結果中。 類型：具有比較運算子的值的屬性名稱映射。 | 否 | | ScanFilter:AttributeValueList | 用來評估篩選條件掃描結果的值和條件。類型：`Condition` 的 `AttributeValue` 映射。 | 否 | | ScanFilter:​ ComparisonOperator | 用於評估所提供的屬性的條件，例如等於、大於。以下是掃描操作的有效比較運算子。 大於、等於或小於的字串值比較是根據 ASCII 字元代碼值。例如，`a` 大於 `A`，`aa` 大於 `B`。如需代碼值的清單，請參閱 [http://en.wikipedia.org/wiki/ASCII\$1ASCII\$1printable\$1characters](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 | 回應中的項目數。如需詳細資訊，請參閱 [計算結果中的項目](Scan.md#Scan.Count)。 類型：數字 | | ScannedCount | 套用任何篩選條件之前的已完成掃描中項目數。`ScannedCount` 值很高，但 `Count` 結果很少或沒有，表示掃描操作不足。如需詳細資訊，請參閱 [計算結果中的項目](Scan.md#Scan.Count)。類型：數字 | | LastEvaluatedKey | 停止掃描操作之項目的主索引鍵。在後續掃描操作中提供此值，以便從該時間點繼續操作。當整個掃描結果集完成時 (意即操作已處理「最後一頁」)，`LastEvaluatedKey` 為 `null`。 | | ConsumedCapacityUnits | 操作所使用的讀取容量單位數目。此值顯示套用至佈建輸送量的數字。如需更多資訊，請參閱[DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。 類型：數字 | ## 特殊錯誤 **** | 錯誤 | 描述 | | --- | --- | | ResourceNotFoundException | 找不到指定的資料表。 | ## 範例 如需使用 AWS 開發套件的範例，請參閱 [掃描 DynamoDB 中的資料表](Scan.md)。 ### 請求範例 ``` // 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 } ``` ## 相關動作 + [Query](API_Query_v20111205.md) + [BatchGetItem](API_BatchGetItem_v20111205.md)