使用扩展JSON数据

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 表示。这种格式优先考虑与 MongoDB shell 的兼容性，后者通常使用 JavaScript 函数来表示类型。旧版 API 使用此格式。
严格	已弃用。这种表示形式是完全符合JSON RFC 的传统格式，允许任何JSON解析器读取类型信息。旧版API使用此格式。

注意

驱动程序将 $uuid 扩展JSON类型从 string 解析为具有子类型 4 (BSON_SUBTYPE_UUID) 的二进制数据。有关 $uuid字段解析的更多信息，请参阅解析 $uuid 字段的特殊规则。

有关这些格式的详细信息，请参阅以下资源：

JSON RFC 官方文档
MongoDB 扩展 JSON 服务器手册条目
BSON_SUBTYPE_UUID API文档
GitHub 上的扩展 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函数

您可以通过调用 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);

507f1f77bcf86cd799439011 is type: ObjectId
4794261 is type: int64_t

有关更多信息，请参阅以下API文档：

警告

在将JSON转换为BSON之前验证不可信输入

如果将JSON字符串转换为BSON并在查询、更新或 command 中使用生成的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 document
doc = 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 mode
opts = bson_json_opts_new (BSON_JSON_MODE_RELAXED, BSON_MAX_LEN_UNLIMITED);
// Convert to Extended JSON
json_str = bson_as_json_with_opts (doc, NULL, opts);
printf ("%s\n", json_str);
// Cleanup
bson_free (json_str);
bson_json_opts_destroy (opts);
bson_destroy (doc);

{ "_id" : { "$oid" : "507f1f77bcf86cd799439012" }, "myNumber" : 11223344 }

有关更多信息，请参阅 bson_as_json_with_opts() API 文档。

API 文档

要详细学习了解可用于处理扩展JSON数据的函数和类型，请参阅以下API文档：