AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。

拡張JSONデータとの連携

Overview

このガイドでは、 MongoDBドキュメントを操作するときに拡張JSONデータ形式を使用する方法を学習できます。

JSON は、オブジェクト、配列、数値、string、ブール値、null の値を表す人間が判読可能なデータ形式です。この形式は、 MongoDB がデータを保存するために使用する形式であるBSONデータ型のサブセットのみをサポートします。拡張JSON形式はより多くのBSONタイプをサポートしており、 BSONの各タイプに直接対応するフィールドタイプ情報を表すために "$" のプレフィックスが付いたキーの予約セットを定義します。

JSON、 BSON、 拡張JSONの詳細については、JSONとBSONリソースおよび拡張JSON MongoDB Server のマニュアル エントリを参照してください。

拡張 JSON 形式

MongoDB拡張JSON は、 BSONデータを表す string 形式を提供します。各形式はJSON RFCに準拠し、特定のユースケースを満たしています。

次の表は、各 拡張JSON形式について説明したものです。

名前
説明

拡張または標準

データ変換中に BSON 型情報が喪失しないようにする string 形式。
この形式は、人間による読みやすさや古い形式との相互運用性を犠牲にして、型の保持を優先します。この形式の詳細については、APIドキュメントのJsonMode.EXTENDEDを参照してください。

緩和

一部の型情報が失われるBSONドキュメントを記述するstring形式。
この形式は、特定の型情報を犠牲にして、人間による読みやすさと相互運用性を優先します。Kotlin 同期ドライバーは、デフォルトで緩和モードを使用します。この形式の詳細については、APIドキュメントのJsonMode.RELAXEDを参照してください。

Shell

MongoDB shell で使用される構文に一致する string 形式。
この形式は MongoDB shell との互換性を優先します。MongoDB shell では、型を表示するのに JavaScript 関数が使用されることが多いためです。この形式の詳細については、API ドキュメントの JsonMode.SHELL を参照してください。

注意

Kotlin Syncドライバーは、$uuid 拡張JSON型を string からバイナリ サブタイプ 4 の Binaryオブジェクトに解析します。$uuidフィールド解析の詳細については、拡張JSON仕様の $uuid フィールドを解析するための特別なルール セクションを参照してください。

拡張 JSON の例

次の例は、それぞれの拡張 JSON 形式で表される ObjectId、date、long 数値フィールドを含むドキュメントを示しています。 表示する例の形式に対応するタブをクリックします。

{  "_id": { "$oid": "573a1391f29313caabcd9637" },  "createdAt": { "$date": { "$numberLong": "1601499609" }},  "numViews": { "$numberLong": "36520312" }}

拡張 JSON の読み取り

このセクションでは、拡張JSON値を次の方法でKotlinオブジェクトに読み込む方法を示します。

ドキュメント クラスの使用

拡張JSON string をKotlinドキュメントオブジェクトに読み込むには、Document クラスまたは BsonDocumentクラスから parse() 静的メソッドを呼び出します。このメソッドは、拡張JSON string を解析し、そのデータを指定されたドキュメントクラスのインスタンスに保存します。

次の例では、parse() メソッドを使用して、拡張JSON string を Documentオブジェクトに読み取ります。

val ejsonStr = """    {        "_id": { "$${"oid"}": "507f1f77bcf86cd799439011" },        "myNumber": { "$${"numberLong"}": "4794261" }    }""".trimIndent()
val doc = Document.parse(ejsonStr)println(doc)

JsonReader クラスの使用

Kotlin Syncドライバーのドキュメントクラスを使用せずに、拡張JSON string をKotlinオブジェクトに読み込むには、 BSONライブラリの JsonReaderクラスを使用します。このクラスには、拡張JSON string のフィールドと値を順番に解析し、 Kotlinオブジェクトとして返すメソッドが含まれています。ドライバーのドキュメントクラスは、 拡張JSONを解析するためにもこのクラスを使用します。

次のコードでは、JsonReaderクラスが提供するメソッドを使用して、拡張JSON string をKotlinオブジェクトに変換します。

val string = """    {        "_id": { "$${"oid"}": "507f1f77bcf86cd799439011" },        "myNumber": { "$${"numberLong"}": "4794261" }    }""".trimIndent()
val jsonReader = JsonReader(string)jsonReader.readStartDocument()
// Reads the "_id" field valuejsonReader.readName("_id")val id = jsonReader.readObjectId()
// Reads the "myNumber" field value jsonReader.readName("myNumber")val myNumber = jsonReader.readInt64()
jsonReader.readEndDocument()
println("$id is type: ${id::class.qualifiedName}")println("$myNumber is type: ${myNumber::class.qualifiedName}")
jsonReader.close()

警告

JSONをBSONに変換する前に信頼できない入力を検証する

JSON string を BSON に変換し、クエリ、更新、またはコマンドでその BSON を使用する場合、攻撃者は演算子または予期しないフィールド値を挿入して、操作の意味を変更することができます。このリスクは、JSON がユーザー、API リクエスト、またはその他の信頼できないソースから提供される場合に最も高くなります。

変換前に入力を検証する方法について詳しく学ぶには、「JSONをBSONに変換する前に信頼できない入力を検証する」を参照してください。

拡張 JSON の書込み (write)

このセクションでは、次の方法でKotlinオブジェクトから拡張JSON値を書き込む方法を示します。

ドキュメント クラスの使用

Document または BsonDocumentオブジェクトから拡張JSON string を書き込むには、toJson() メソッドを呼び出します。このメソッドに JsonWriterSettingsオブジェクトパラメータを渡して、拡張JSON形式を指定できます。

次の例では、Document データを 緩和モード拡張JSONとして書込みます。

val doc = Document()    .append("_id", ObjectId("507f1f77bcf86cd799439012"))    .append("createdAt", Date.from(Instant.ofEpochMilli(1601499609000L)))    .append("myNumber", 4794261)
val settings = JsonWriterSettings.builder()    .outputMode(JsonMode.RELAXED)    .build()
println(doc.toJson(settings))

JsonWriter クラスの使用

Kotlinオブジェクトに保存されているデータから拡張JSON string を出力するには、 BSONライブラリの JsonWriterクラスを使用できます。JsonWriterオブジェクトを構築するには、 Java Writer のサブクラスを渡して、拡張JSONの出力方法を指定します。オプションで、JsonWriterSettingsインスタンスを渡して、 拡張JSON形式などのオプションを指定できます。デフォルトでは 、JsonWriter は 緩和モード形式を使用します。Kotlin Syncドライバーのドキュメントクラスは、 BSON を拡張JSONに変換する目的でもこのクラスを使用します。

次の例では、JsonWriterオブジェクトを使用して標準モードの拡張JSON string 値を作成し、System.out に出力します。

 val settings = JsonWriterSettings.builder()    .outputMode(JsonMode.EXTENDED)    .build()
JsonWriter(BufferedWriter(OutputStreamWriter(System.out)), settings).use { jsonWriter ->    jsonWriter.writeStartDocument()    jsonWriter.writeName("_id")    jsonWriter.writeObjectId(ObjectId("507f1f77bcf86cd799439012"))    jsonWriter.writeName("myNumber")    jsonWriter.writeInt64(11223344L)    jsonWriter.writeEndDocument()    jsonWriter.flush()}

カスタム BSON 型変換

拡張JSON出力形式を指定するだけでなく、JsonWriterSettingsオブジェクトに 変換 を追加して出力をさらにカスタマイズできます。これらの変換メソッドは、変換プロセス中にさまざまなデータ型を処理するためのロジックを指定します。

次の例では、 ドキュメント クラスの使用の例と同じドキュメントを変換しています。ただし、この例では、緩和モードの拡張JSON出力を簡素化するために、JsonWriterSettingsオブジェクトで objectIdConverter() と dateTimeConverter() の変換メソッドを定義しています。

val settings = JsonWriterSettings.builder()    .outputMode(JsonMode.RELAXED)    .objectIdConverter { value, writer ->        writer.writeString(value.toHexString())    }    .dateTimeConverter { value, writer ->        val zonedDateTime = Instant.ofEpochMilli(value).atZone(ZoneOffset.UTC)        writer.writeString(DateTimeFormatter.ISO_DATE_TIME.format(zonedDateTime))    }    .build()
val doc = Document()    .append("_id", ObjectId("507f1f77bcf86cd799439012"))    .append("createdAt", Date.from(Instant.ofEpochMilli(1601499609000L)))    .append("myNumber", 4794261)
println(doc.toJson(settings))

API ドキュメント

このガイドで説明したメソッドや型の詳細については、次の API ドキュメントを参照してください。

戻る
時系列
次へ
Indexes
このページを評価

項目一覧