Overview
在本指南中，您可以学习如何在C驱动程序中使用扩展JSON格式。
JSON是一种数据格式，可表示对象值、数组值、数字值、字符串值、布尔值和空值。此格式仅支持BSON数据类型的子集，而MongoDB正是使用该格式来存储数据。扩展JSON格式支持更多BSON types，定义了一设立以 "$" 为前缀的保留键，用于表示直接对应于BSON中每种类型的字段类型信息。
有关这些格式之间区别的更多信息，请参阅JSON和BSON资源。
扩展 JSON 格式
MongoDB扩展JSON功能采用不同的string格式来表示BSON数据。每种不同的格式都符合JSON RFC 并满足特定的使用案例。
下表描述了每种格式：
名称 | 说明 |
|---|---|
扩展 | 这种 JSON 表示形式也称为规范格式，可以避免丢失 BSON 类型信息。 |
宽松模式 | JSON表示形式，用于描述丢失某些类型信息的BSON文档。 |
Shell | 已弃用。与 MongoDB shell 中使用的语法相匹配的 JSON 表示。 |
严格 | 已弃用。这种表示形式是完全符合 JSON RFC 的旧版格式，允许任何 JSON 解析器读取类型信息。 |
注意
驱动程序将 $uuid 扩展JSON类型从 string 解析为具有子类型 4 (BSON_SUBTYPE_UUID) 的二进制数据。有关 $uuid字段解析的更多信息，请参阅解析 $uuid 字段的特殊规则。
有关这些格式的详细信息，请参阅以下资源：
JSON RFC 官方文档
MongoDB 扩展 JSON 服务器手册条目
BSON_SUBTYPE_UUID API文档
扩展 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函数
您可以通过调用 bson_new_from_json() 函数将扩展JSON字符串读入BSON文档。此函数解析扩展JSON字符串并返回包含数据的 bson_t 结构。
以下示例展示了如何将示例扩展JSON string 读入 bson_t文档：
/* Read Extended JSON string to BSON */const char *ejson_str = "{ \"_id\": { \"$oid\": \"507f1f77bcf86cd799439011\"}," "\"myNumber\": {\"$numberLong\": \"4794261\" }}";bson_error_t error;bson_t *doc = bson_new_from_json ((const uint8_t *)ejson_str, -1, &error);有关更多信息，请参阅 bson_new_from_json() 和 bson_as_canonical_extended_json() API文档。
使用BSON JSON Reader
您还可以使用 bson_json_reader_t 类型解析扩展JSON字符串，该类型提供用于将JSON转换为BSON的流媒体接口。这在处理多个JSON文档或需要对解析进程进行更多控制时特别有用。
以下代码示例展示如何使用 bson_json_reader_t 将扩展JSON string 转换为BSON文档：
const char *ejson_str = "{ \"_id\": { \"$oid\": \"507f1f77bcf86cd799439011\"}," "\"myNumber\": {\"$numberLong\": \"4794261\" }}";bson_json_reader_t *reader;bson_error_t error;bson_t doc = BSON_INITIALIZER;int ret;
reader = bson_json_data_reader_new (false, 0);bson_json_data_reader_ingest (reader, (const uint8_t *)ejson_str, strlen (ejson_str));
ret = bson_json_reader_read (reader, &doc, &error);if (ret > 0) { bson_iter_t iter; if (bson_iter_init (&iter, &doc)) { while (bson_iter_next (&iter)) { const char *key = bson_iter_key (&iter);
if (strcmp (key, "_id") == 0 && BSON_ITER_HOLDS_OID (&iter)) { const bson_oid_t *oid = bson_iter_oid (&iter); char oid_str[25]; bson_oid_to_string (oid, oid_str); printf ("%s is type: ObjectId\n", oid_str); }
if (strcmp (key, "myNumber") == 0 && BSON_ITER_HOLDS_INT64 (&iter)) { int64_t number = bson_iter_int64 (&iter); printf ("%ld is type: int64_t\n", (long)number); } } }} else if (ret < 0) { printf ("Error: %s\n", error.message);}
bson_json_reader_destroy (reader);bson_destroy (&doc);有关更多信息，请参阅以下API文档：
警告
在将 JSON 转换为 BSON 之前验证不受信任的输入
如果将 JSON string 转换为 BSON 并在查询、更新或命令中使用生成的 BSON，攻击者可以注入操作符或意外的字段值，从而改变操作的含义。当 JSON 来源于用户、API 请求或其他不可信的来源时，这种风险最大。
要了解有关在转换前验证输入的更多信息，请参阅在将 JSON 转换为 BSON 之前验证不受信任的输入。
写入扩展 JSON
您可以通过调用 bson_as_json_with_opts() 函数将BSON文档写入为扩展JSON string。此函数将 bson_t文档转换为扩展JSON string，并带有用于指定输出格式的选项。
以下示例展示了如何创建BSON文档并将其输出为宽松格式的扩展JSON：
bson_t *doc;bson_oid_t oid;bson_json_opts_t *opts;char *json_str;
// Create a BSON documentdoc = bson_new ();bson_oid_init_from_string (&oid, "507f1f77bcf86cd799439012");bson_append_oid (doc, "_id", -1, &oid);bson_append_int32 (doc, "myNumber", -1, 11223344);
// Configure JSON output options for Relaxed modeopts = bson_json_opts_new (BSON_JSON_MODE_RELAXED, BSON_MAX_LEN_UNLIMITED);
// Convert to Extended JSONjson_str = bson_as_json_with_opts (doc, NULL, opts);printf ("%s\n", json_str);
// Cleanupbson_free (json_str);bson_json_opts_destroy (opts);bson_destroy (doc);有关更多信息，请参阅 bson_as_json_with_opts() API 文档。
API 文档
要详细学习了解可用于处理扩展JSON数据的函数和类型，请参阅以下API文档：