扩展 JSON
Overview
JSON 是一种数据格式，可表示对象值、数组值、数字值、字符串值、布尔值和空值。扩展 JSON 格式定义了一组以 “ $” 为前缀的保留键，用于表示直接对应于 BSON 中每种类型的字段类型信息，BSON 是 MongoDB 用于存储数据的格式。
扩展 JSON 格式
MongoDB 扩展 JSON 采用不同的字符串格式来表示 BSON 数据。每种不同的格式都符合 JSON RFC 并满足特定的用例。扩展格式也称为规范格式，使得每个 BSON 类型都具有特定表示形式，可进行双向转换而不会丢失信息。宽松模式格式更加简洁，更接近普通 JSON，但并不表示所有类型信息，比如数字字段的具体字节大小等。
请参阅下表查看每种格式的说明：
名称 | 说明 |
|---|---|
扩展 | Also known as the canonical format, this JSON representation avoids loss of
BSON type information. This format prioritizes type preservation at the loss of human-readability and
interoperability with older formats. |
宽松模式 | JSON representation that describes BSON documents with some type information loss. This format prioritizes human-readability and interoperability at the loss of
certain type information. |
Shell | JSON representation that matches the syntax used in the MongoDB shell. This format prioritizes compatibility with the MongoDB shell, which often uses
JavaScript functions to represent types. |
严格 | Deprecated. This representation is the legacy format that fully conforms to
the JSON RFC which allows any JSON parser to read the type information. |
注意
驱动程序将 $uuid 扩展JSON类型从string解析为二进制子类型 4 的 BsonBinary 对象。 有关$uuid 字段解析的更多信息，请参阅 解析 $uuid 字段的特殊规则 扩展 JSON 规范中的 部分。
要学习；了解有关JSON、 BSON和 Extended JSON的更多信息，请参阅MongoDB Server手册中有关JSON和BSON以及Extended JSON的文章。
扩展 JSON 示例
以下示例显示了包含对象标识符、日期和长数字字段的文档，这些字段分别以扩展 JSON 格式表示。单击与要查看的示例格式相对应的选项卡：
{ "_id": { "$oid": "573a1391f29313caabcd9637" }, "createdAt": { "$date": { "$numberLong": "1601499609" }}, "numViews": { "$numberLong": "36520312" } }
{ "_id": { "$oid": "573a1391f29313caabcd9637" }, "createdAt": { "$date": "2020-09-30T18:22:51.648Z" }, "numViews": 36520312 }
{ "_id": ObjectId("573a1391f29313caabcd9637"), "createdAt": ISODate("2020-09-30T18:22:51.648Z"), "numViews": NumberLong("36520312") }
{ "_id": { "$oid": "573a1391f29313caabcd9637" }, "createdAt": { "$date": 1601499609 }, "numViews": { "$numberLong": "36520312" } }
读取扩展 JSON
您可以通过调用 bson.json_util.loads() 方法将扩展JSON字符串读入Python对象。 此方法解析扩展JSON字符串并返回包含数据的Python列表。
以下示例展示如何使用 loads() 方法将扩展JSON字符串读入字典列表：
from bson.json_util import loads ejson_str = '''[ {"foo": [1, 2]}, {"bar": {"hello": "world"}}, {"code": { "$scope": {}, "$code": "function x() { return 1; }" }}, {"bin": { "$type": "80", "$binary": "AQIDBA==" }} ]''' doc = loads(ejson_str) print(doc)
[ {'foo': [1, 2]}, {'bar': {'hello': 'world'}}, {'code': Code('function x() { return 1; }', {})}, {'bin': Binary(b'\x01\x02\x03\x04', 128)} ]
在Python 2 中读取二进制值
在Python 3 中，驾驶员将子类型为 0 的JSON二进制值解码为 bytes 类的实例。在Python 2 中，驾驶员将这些值解码为具有子类型 0 的 Binary 类的实例。
以下代码示例展示了PyMongo如何解码具有子类型 0 的JSON二进制实例。选择 Python 2或Python 3标签页以查看相应的代码：
from bson.json_util import loads doc = loads('{"b": {"$binary': b'this is a byte string'}) print(doc)
{u'b': Binary('this is a byte string', 0)}
from bson.json_util import loads doc = loads('{"b": {"$binary': b'this is a byte string'}) print(doc)
{'b': b'this is a byte string'}
写入扩展 JSON
您可以通过调用 bson.json_util.dumps() 方法从字典列表中写入扩展JSON字符串。 以下示例以宽松格式输出扩展JSON字符串：
from bson import Code, Binary from bson.json_util import dumps doc = [ {'foo': [1, 2]}, {'bar': {'hello': 'world'}}, {'code': Code('function x() { return 1; }', {})}, {'bin': Binary(b'\x01\x02\x03\x04', 128)} ] ejson_str = dumps(doc) print(ejson_str)
'''[ {"foo": [1, 2]}, {"bar": {"hello": "world"}}, {"code": { "$code": "function x() { return 1; }", "$scope": {} }}, {"bin": { "$binary": { "base64": "AQIDBA==", "subType": "80" }}} ]'''
默认下，dumps() 方法返回宽松格式的扩展JSON字符串。 要指定不同的格式，请为 json_options 参数传递以下值之一：
CANONICAL_JSON_OPTIONS：以规范格式返回扩展JSON字符串。LEGACY_JSON_OPTIONS：以传统格式返回扩展JSON字符串。 我们建议改用宽松或规范格式。
以下示例展示了如何以规范格式输出扩展JSON ：
from bson import Code, Binary from bson.json_util import dumps, CANONICAL_JSON_OPTIONS doc = [ {'foo': [1, 2]}, {'bar': {'hello': 'world'}}, {'code': Code('function x() { return 1; }', {})}, {'bin': Binary(b'\x01\x02\x03\x04', 128)} ] ejson_str = dumps(doc, json_options=CANONICAL_JSON_OPTIONS) print(ejson_str)
'''[ {"foo": [ {"$numberInt": "1"}, {"$numberInt": "2"} ]}, {"bar": {"hello": "world"}}, {"code": { "$code": "function x() { return 1; }", "$scope": {} }}, {"bin": { "$binary": { "base64": "AQIDBA==", "subType": "80" }}} ]'''
更多信息
以下部分中的资源提供了有关使用扩展JSON 的更多信息。
API 文档
有关 bson.json_util 中方法和类型的更多信息，请参阅以下API文档：
其他软件包
python-bsonjs 是另一个构建在 libbson 之上的包，可以将BSON转换为扩展JSON。python-bsonjs包不依赖于PyMongo ，在某些情况下可能比 json_util 提供更高的性能。
提示
使用 RawBSONDocument 类型
python-bsonjs 从 RawBSONDocument 类型转换时，与PyMongo搭配使用效果最佳。