ドキュメントのデータ形式: 拡張 JSON
項目一覧
Overview
このガイドでは、MongoDB Java ドライバーで拡張 JSON 形式を使用する方法を学習できます。
JSON は、オブジェクト、配列、数値、string、ブール値、null の値を表すデータ形式です。 JSON$BSON拡張 形式では、MongoDB がデータを保存するために使用する形式である の各型に直接対応するフィールド型情報を表すために、"{0 " というプレフィックスが付いたキーの予約セットが定義されます。
このガイドでは、次のトピックについて説明します。
さまざまな MongoDB 拡張 JSON 形式
BSON ライブラリを使用して拡張 JSON と Java オブジェクトを変換する方法
BSON types のカスタム変換の作成方法
これらの形式の違いの詳細については、 JSON と BSON に関するの記事をご覧ください。
拡張 JSON 形式
MongoDB 拡張 JSON は、BSON データを表すためのさまざまな string 形式を機能します。 異なる形式はそれぞれ 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. The legacy API uses this format. |
注意
ドライバーは、 $uuid拡張 JSON タイプを string からバイナリ サブタイプ4のBsonBinaryオブジェクトに解析します。 $uuidフィールド解析の詳細については、 $uuid フィールドを解析するための特別なルール をJSON 参照してください セクションを参照して 。
これらの形式の詳細については、次のリソースを参照してください。
JSON RFC 公式ドキュメント
MongoDB 拡張 JSON Server マニュアル エントリ
BsonBinary API ドキュメント
拡張JSON 仕様Github ドキュメント
拡張 JSON の例
次の例は、それぞれの拡張 JSON 形式で表される ObjectId、date、long 数値フィールドを含むドキュメントを示しています。 表示する例の形式に対応するタブをクリックします。
{ "_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 の読み取り
ドキュメント クラスの使用
必要なオブジェクトタイプに応じて、 クラスまたは クラスから 静的メソッドを呼び出すと、拡張 JSON string を Java ドキュメント オブジェクトに読み込むことができます。parse()DocumentBsonDocumentこのメソッドは、いずれかの形式の拡張 JSON string を解析し、データを含むそのクラスのインスタンスを返します。
次の例は、 Documentクラスを使用してサンプルの拡張 JSON string をparse() Documentオブジェクトに読み込む方法を示しています。
String ejsonStr = "{ \"_id\": { \"$oid\": \"507f1f77bcf86cd799439011\"}," + "\"myNumber\": {\"$numberLong\": \"4794261\" }}}"; Document doc = Document.parse(ejsonStr); System.out.println(doc);
詳しくは、 ドキュメントの「基礎」ページをご覧ください。
BSON ライブラリの使用
また、 JsonReaderクラスを使用すると、MongoDB Java ドライバーのドキュメント クラスを使用せずに、拡張 JSON string を Java オブジェクトに読み込むことができます。 このクラスには、拡張 JSON string の任意の形式のフィールドと値を順番に解析し、それらを Java オブジェクトとして返すメソッドが含まれています。 ドライバーのドキュメント クラスは、拡張 JSON を解析するためにこのクラスも使用します。
次のコード例は、 JsonReaderクラスを使用して拡張 JSON string を Java オブジェクトに変換する方法を示しています。
String ejsonStr = "{ \"_id\": { \"$oid\": \"507f1f77bcf86cd799439011\"}," + "\"myNumber\": {\"$numberLong\": \"4794261\" }}}"; JsonReader jsonReader = new JsonReader(ejsonStr); jsonReader.readStartDocument(); jsonReader.readName("_id"); ObjectId id = jsonReader.readObjectId(); jsonReader.readName("myNumber"); Long myNumber = jsonReader.readInt64(); jsonReader.readEndDocument(); System.out.println(id + " is type: " + id.getClass().getName()); System.out.println(myNumber + " is type: " + myNumber.getClass().getName()); jsonReader.close();
詳細については、 JsonReader を参照してください API ドキュメント。
拡張 JSON の書込み (write)
ドキュメント クラスの使用
拡張 JSON 文字列は、 toJson()メソッドを呼び出し、オプションでJsonWriterSettingsのインスタンスを渡して拡張 JSON 形式を指定することで、 DocumentまたはBsonDocumentのインスタンスから拡張 JSON string を作成できます。
この例では、拡張 JSON を Relaxed モード形式で出力します。
Document myDoc = new Document(); myDoc.append("_id", new ObjectId("507f1f77bcf86cd799439012")).append("myNumber", 11223344); JsonWriterSettings settings = JsonWriterSettings.builder().outputMode(JsonMode.RELAXED).build(); System.out.println(doc.toJson(settings));
BSON ライブラリの使用
JsonWriterクラスの BSON ライブラリを使用して、Java オブジェクト内のデータから拡張 JSON string を出力することもできます。 JsonWriterのインスタンスを構築するには、Java Writerのサブクラスを渡して、拡張 JSON の出力方法を指定します。 オプションで、 JsonWriterSettingsインスタンスを渡して、拡張 JSON 形式などのオプションを指定できます。 デフォルトでは、 JsonWriterは 緩和 モード形式を使用します。 MongoDB Java ドライバーのドキュメント クラスも、このクラスを使用して BSON を拡張 JSON に変換します。
次のコード例は、 JsonWriterを使用して拡張 JSON string を作成し、それをSystem.outに出力する方法を示しています。 outputMode()ビルダ メソッドにJsonMode.EXTENDED定数を渡して形式を指定します。
JsonWriterSettings settings = JsonWriterSettings.builder().outputMode(JsonMode.EXTENDED).build(); try (JsonWriter jsonWriter = new JsonWriter(new BufferedWriter(new OutputStreamWriter(System.out)), settings)) { jsonWriter.writeStartDocument(); jsonWriter.writeObjectId("_id", new ObjectId("507f1f77bcf86cd799439012")); jsonWriter.writeInt64("myNumber", 11223344); jsonWriter.writeEndDocument(); jsonWriter.flush(); }
このセクションで説明されるメソッドとクラスの詳細については、次の API ドキュメントを参照してください。
カスタム BSON 型変換
JSON 出力の形式を設定するには を指定するだけでなく、 に フィルターoutputMode()JsonWriterSettings.Builder を追加して出力をさらにカスタマイズできます。これらの変換メソッドは Java 型を検出し、それに渡されたConverterによって定義されたロジックを実行します。
次のサンプル コードは、緩和モードの 出力を簡素化するために、LambdaJSON 式として定義される変換子を追加する方法を示しています。
JsonWriterSettings settings = JsonWriterSettings.builder().outputMode(JsonMode.RELAXED) .objectIdConverter((value, writer) -> writer.writeString(value.toHexString())) .dateTimeConverter( (value, writer) -> { ZonedDateTime zonedDateTime = Instant.ofEpochMilli(value).atZone(ZoneOffset.UTC); writer.writeString(DateTimeFormatter.ISO_DATE_TIME.format(zonedDateTime)); }) .build(); Document doc = new Document() .append("_id", new ObjectId("507f1f77bcf86cd799439012")) .append("createdAt", Date.from(Instant.ofEpochMilli(1601499609000L))) .append("myNumber", 4794261); System.out.println(doc.toJson(settings)));
このコードの出力は、次のテキストのようになります。
{"_id": "507f1f77bcf86cd799439012", "createdAt": "2020-09-30T21:00:09Z", "myNumber": 4794261}
変換ツールを指定しない場合、緩和モードの JSON 出力は次のテキストのようになります。
{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "createdAt": {"$date": "2020-09-30T21:00:09Z"}, "myNumber": 4794261}
このセクションで説明されるメソッドとクラスの詳細については、次の API ドキュメントを参照してください。