# 扫描 **重要** ***本节介绍已经弃用的 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 将返回扫描操作的项目总数，即使该操作没有与分配的筛选器匹配的项目。您可以将 Limit 参数应用于仅计数扫描。 提供 `AttributesToGet` 列表时不要将 `Count` 设置为 `true`；否则 DynamoDB 将返回验证错误。有关更多信息，请参阅 [对结果中的项目进行计数](Scan.md#Scan.Count)。类型：布尔值 | 否 | | ScanFilter | 计算扫描结果并仅返回所需值。多个条件被视为 "AND" 操作：必须满足所有条件才能包含在结果中。 类型：属性名称到具有比较运算符的值的映射。 | 否 | | ScanFilter:AttributeValueList | 用于计算筛选器扫描结果的值和条件。类型：`AttributeValue` 到 `Condition` 的映射。 | 否 | | 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)。 对于二进制，DynamoDB 在比较二进制值时将二进制数据的每个字节视为无符号值，例如计算查询表达式时。 类型：字符串或二进制 | 否 | |   | `EQ`：等于。 对于 `EQ`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。 |   | |   | `NE`：不等于。 对于 `NE`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。 |   | |   | `LE`：小于或等于。 对于 `LE`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。 |   | |   | `LT`：小于。 对于 `LT`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。 |   | |   | `GE`：大于或等于。 对于 `GE`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。 |   | |   | `GT`：大于。 对于 `GT`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。同样，`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。 |   | |   | `NOT_NULL`：属性存在。 |   | |   | `NULL`：属性不存在。 |   | |   | `CONTAINS`：检查子序列或集合中的值。 对于 `CONTAINS`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果比较的目标属性是字符串，则操作将检查子字符串匹配。如果比较的目标属性是二进制，则操作将查找与输入匹配的目标子序列。如果比较的目标属性是集合（“SS”、“NS”或“BS”），则操作将检查集合的成员（而不是作为子字符串）。 |   | |   | `NOT_CONTAINS`：检查缺少子序列，或者集合中缺少值。 对于 `NOT_CONTAINS`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果比较的目标属性是字符串，则操作将检查是否没有子字符串匹配项。如果比较的目标属性是二进制，则操作将检查是否没有匹配输入的目标子序列。如果比较的目标属性是集合（“SS”、“NS”或“BS”），则操作将检查是否不存在集合的成员（而不是作为子字符串）。 |   | |   | `BEGINS_WITH`：检查前缀。 对于 `BEGINS_WITH`，`AttributeValueList` 只能包含一个字符串或二进制类型的 `AttributeValue`（不是数字或集合）。比较的目标属性必须是字符串或二进制（不是数字或集合）。 |   | |   | `IN`：检查确切匹配。 对于 `IN`，`AttributeValueList` 可以包含多个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。比较的目标属性必须具有相同的类型和精确值才能匹配。字符串从不匹配字符串集。 |   | |   | `BETWEEN`：大于等于第一个值，小于等于第二个值。 对于 `BETWEEN`，`AttributeValueList` 必须包含两个相同类型的 `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 SDK 的示例，请参阅 [在 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 } ``` ## 相关操作 + [查询](API_Query_v20111205.md) + [BatchGetItem](API_BatchGetItem_v20111205.md)