扫描 - Amazon DynamoDB
描述请求响应特殊错误示例相关操作

扫描

重要

本节介绍已经弃用的 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 将返回扫描操作的项目总数，即使该操作没有与分配的筛选器匹配的项目。您可以将 Limit 参数应用于仅计数扫描。

提供 AttributesToGet 列表时不要将 Count 设置为 true；否则 DynamoDB 将返回验证错误。有关更多信息，请参阅 对结果中的项目进行计数。

类型：布尔值

 否
ScanFilter

计算扫描结果并仅返回所需值。多个条件被视为 "AND" 操作：必须满足所有条件才能包含在结果中。

类型：属性名称到具有比较运算符的值的映射。

 否
ScanFilter:AttributeValueList

用于计算筛选器扫描结果的值和条件。

类型：AttributeValue 到 Condition 的映射。

 否
ScanFilter:​ ComparisonOperator

计算所提供属性的标准，例如等于、大于等于等。以下是扫描操作的有效比较运算符。

注意

大于、等于或小于的字符串值比较基于 ASCII 字符代码值。例如，a 大于 A，aa 大于 B。有关代码值列表，请参见 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

响应中的项目数。有关更多信息，请参阅 对结果中的项目进行计数。

类型：数字
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
}