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

mongo()(mongoshメソッド)

Mongo(host, autoEncryptionOpts, api)

mongoshまたは JavaScript ファイルからデータベース接続をインスタンス化するための JavaScript コンストラクター。

Mongo()メソッドには次のパラメータがあります。

Parameter
タイプ
説明

host

string またはMongoインスタンス

任意。 ホストまたは接続string 。

ホストは接続string 、または <host> または <host><:port> の形式にすることもできます。 接続stringは Mongo インスタンスの形式にすることができます。 Mongoインスタンスを指定すると、 コンストラクターは指定されたMongo() インスタンスの接続string mongoを使用します。

省略した場合、 Mongo()はデフォルトのポート27017でローカルホスト インターフェースへの接続をインスタンス化します。

autoEncryptionOpts

ドキュメント

任意 。使用中の暗号化 を有効にするための構成パラメーター。

autoEncryptionOpts データベース接続の既存の使用中の暗号化設定を上書きします。省略した場合、Mongo()は現在のデータベース接続の使用中の暗号化設定を継承します。

使用方法と構文の詳細については、 AutoEncryptionOptsを参照してください。

api

ドキュメント

任意。 Stable API を有効にするための構成オプション。

使用方法と構文の詳細については、 apiを参照してください。

このメソッドは、次の環境でホストされている配置で使用できます。

  • MongoDB Atlas はクラウドでの MongoDB 配置のためのフルマネージド サービスです
  • MongoDB Enterprise: サブスクリプションベースの自己管理型 MongoDB バージョン

  • MongoDB Community: ソースが利用可能で、無料で使用できる自己管理型の MongoDB のバージョン

autoEncryptionOptsドキュメントでは、使用中の暗号化の構成オプションを指定します。データベース接続に既存の使用中の暗号化構成がある場合、autoEncryptionOpts はその構成を上書きします。MongoDBは、使用中の暗号化に対して、クライアント側フィールド レベルの暗号化とQueryable Encryption2 つのアプローチを提供します。

たとえば、クライアント側のフィールドレベル暗号化コマンドライン オプションを使用してmongoshを起動すると、その接続のクライアント側暗号化が有効になります。 を使用して作成された新しいデータベース接続は、Mongo() に Mongo()が含まれてい ない限りautoEncryptionOpts 、暗号化設定を継承します。

autoEncryptionOptsドキュメントの構文は次のとおりです。

{ "keyVaultClient" : <object>, "keyVaultNamespace" : "<string>", "kmsProviders" : <object>, "schemaMap" : <object>, "bypassAutoEncryption" : <boolean>, "tlsOptions": <object>, "encryptedFieldsMap": <object>}

autoEncryptionOptsドキュメントは次のパラメータを取ります。

Parameter
タイプ
説明

keyVaultClient

Mongo() 最大数。

(任意)キーヴォールトコレクションをホストしている MongoDB クラスター。

クラスターを指すMongo()接続オブジェクトを指定します。

var keyVaultClient = Mongo(<MongoDB URI>); var autoEncryptionOptions = { "keyVaultClient" : keyVaultClient, "keyVaultNamespace" : "<database>.<collection>", "kmsProviders" : { ... }}

keyVaultClientが省略されている場合、 autoEncryptionOptsドキュメントを含むMongo()オブジェクトに指定されたhostがキーヴォールト ホストとして使用されます。

keyVaultNamespace

string

(必須)キーヴォールト コレクションの完全な名前空間。

kmsProviders

ドキュメント

(必須) CMK(Customer Master Key)を管理するためにクライアント側のフィールドレベル暗号化で使用されるKMS ( KMS )。 クライアント側のフィールドレベル暗号化では、データ暗号化キーの暗号化と復号化に CMK を使用します。

クライアント側のフィールドレベル暗号化は、次の KMS プロバイダーをサポートしています。

可能であれば、 で提供される認証情報を環境変数として定義し、 オプションを使用してkmsProviders mongosh--evalに渡すことを検討してください。これにより、認証情報がログに漏洩する可能性を最小限に抑えられます。 サポートされている KMS ごとのこのアプローチの例については、「 データキーの作成」を参照してください。

Amazon Web Services KMS

重要: Amazon Web Services KMS をサポートするには、mongosh またはMongoDB 4.2.2 以降のレガシーmongo シェルを使用します。4.2.0と 4.2.1レガシーmongo シェル は、 KMS 応答オブジェクトの予期しない変更により、 Amazon Web Services KMS サービスをサポートしていません。 詳細については、 SERVER-44721 を参照してください。

次のフィールドを使用してawsドキュメントをkmsProvidersに指定します。

"kmsProviders" : { "aws" : { "accessKeyId" : "AWSAccessKeyId", "secretAccessKey" : "AWSSecretAccessKey" } }

指定されたaccessKeyId ListReadは、KMS サービスに対するすべての 権限と 権限を持つ IAM ユーザーに対応する必要があります。

一部の環境では、 Amazon Web Services SDK は認証情報を自動的に取得できます。 SDK Amazon Web ServicesKMSに明示的な認証情報を提供せずに の使用を有効にするには、Amazon Web ServiceskmsProvider の詳細をMongo() コンストラクターに渡します。

{ "kmsProviders" : { "aws" : { } }}
Azure Key Vault

次のフィールドを使用してazureドキュメントをkmsProvidersに指定します。

"kmsProviders" : { "azure" : { "tenantId" : "AzureTenantId", "clientId" : "AzureClientId", "clientSecret" : "AzureClientSecret" }}

バージョン 5.0 の新機能。

Google Cloud KMS

次のフィールドを使用してgcpドキュメントをkmsProvidersに指定します。

"kmsProviders" : { "gcp" : { "email" : "GCPEmail", "privateKey" : "GCPPrivateKey" }}

バージョン 5.0 の新機能。

ローカルで管理されるキー

次のフィールドを使用して、 localドキュメントをkmsProvidersに指定します。

"kmsProviders" : { "local" : { "key" : BinData(0, "<96 byte base-64 encoded key>") }}

指定されるkeyは、 64でエンコードされた96バイトの string で、改行文字を含まない基本文字列である必要があります。

schemaMap

ドキュメント

(任意) JSON スキーマドラフト 4 標準構文と暗号化固有のキーワードを使用して指定された、自動クライアント側のフィールドレベル暗号化ルール。このオプションは explicitEncryptionOnly と排他関係にあります。コレクションが schemaMap と encryptedFieldsMap の両方に存在する場合、libmongocrypt は初期化時にエラーを返します。

詳細なドキュメントについては、「暗号化スキーマ 」を参照してください。

bypassAutoEncryption

ブール値

(任意) trueを指定すると、自動クライアント側のフィールドレベル暗号化ルールをバイパスし、フィールドごとの明示的(手動)暗号化が実行されます。

bypassQueryAnalysis

ブール値

(任意) crypt_sharedライブラリなしでインデックス付きフィールドで明示的な暗号化を使用するには、 trueを指定します。 詳しくは、「 Queryable Encryption の MongoClient オプション 」を参照してください。

explicitEncryptionOnly

ブール値

(任意)自動暗号化と自動復号化のいずれも使用するには、 trueを指定します。 getKeyVault()とgetClientEncryption()を使用して明示的な暗号化を実行できます。 このオプションはschemaMapと排他関係にあります。 省略された場合、デフォルトはfalseとなります。

tlsOptions

オブジェクト

(任意)次に使用する PEM形式の TLSクライアント証明書と秘密キーファイル( tlsCertificateKeyFile )、TLSクライアント証明書と秘密キーファイルパスワード( tlsCertificateKeyFilePassword )、または TLS 認証局ファイル( tlsCAFile )へのパスPEM形式で KMS に接続します。 これらのオプションの詳細については、「 TLS オプション 」を参照してください。

encryptedFieldsMap

ドキュメント

(任意)encryptedFields ドキュメントへのコレクション名前空間のマップ。encryptedFields は、 Queryable Encryption の暗号化フィールドを説明するBSONドキュメントです。コレクションが schemaMap と encryptedFieldsMap の両方に存在する場合、libmongocrypt は初期化時にエラーを返します。

Queryable Encryptionの暗号化されたフィールドの詳細については、暗号化されたフィールド と 有効なクエリ を参照してください。

apiパラメーターは、 Stable APIの構成オプションを指定します。 次のオプションを使用して、オプションの動作を有効または無効にすることができます。

オプション
タイプ
説明

version

string

API バージョンを指定します。"1" は現在サポートされている唯一のバージョンです。

strict

ブール値

true場合:

strictを指定する場合は、 versionも指定する必要があります。

指定しない場合、デフォルトで false になります。

deprecationErrors

ブール値

trueの場合、指定された API バージョンで非推奨のコマンドまたは動作を使用すると、 APIDeprecationErrorが返されます。 deprecationErrorsを指定する場合は、 versionも指定する必要があります。

指定しない場合、デフォルトで false になります。

apiパラメータの構文は次のとおりです。

{ api: { version: <string>, strict: <boolean>, deprecationErrors: <boolean> } }

次の操作では、 mongoshセッション内から新しい接続オブジェクトが作成されます。

cluster = Mongo("mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster")

clusterオブジェクトに対して操作を発行して、 mymongo.example.net:27017クラスターと対話します。

myDB = cluster.getDB("myDB"); //returns the database objectmyColl = myDB.getCollection("myColl"); // returns the collection object
1

mongoshクライアントを起動します。

mongosh --nodb
2

ローカルで管理されているキーのクライアント側フィールドレベル暗号化を構成するには、改行を含まない base64 でエンコードされた 96 バイトのstringを生成します。

const TEST_LOCAL_KEY = require("crypto").randomBytes(96).toString("base64")
3

生成されたローカルキーstringを使用して、クライアント側のフィールドレベル暗号化オプションを作成します。

let autoEncryptionOpts = { "keyVaultNamespace" : "encryption.__dataKeys", "kmsProviders" : { "local" : { "key" : BinData(0, TEST_LOCAL_KEY) } } }
4

データベース接続を作成するには、クライアント側のフィールドレベル暗号化オプションが構成されたMongo()コンストラクターを使用します。 mongodb://myMongo.example.net URI を、ターゲット クラスターの接続string URIに置き換えます。

encryptedClient = Mongo( "mongodb://myMongo.example.net:27017/?replSetName=myMongo", autoEncryptionOpts)

clusterオブジェクトに対して操作を発行して、 mymongo.example.net:27017クラスターとやり取りし、明示的な暗号化を実行します。

// returns the database objectmyDB = cluster.getDB("myDB"); // returns the collection objectmyColl = myDB.getCollection("myColl"); // returns object for managing data encryption keyskeyVault = cluster.getKeyVault(); // returns object for explicit encryption/decryptionclientEncryption = cluster.getClientEncryption();

クライアント側のフィールドレベル暗号化方法の完全なリストについては、「使用中の暗号化」を参照してください。

ローカルで管理されているキーに対してクライアント側のフィールドレベル暗号化を構成するには、次の手順に従います。

  • 基本的な64でエンコードされた96バイトの string を生成し、改行を含まない

  • キーを読み込むには、 mongoshを使用します。

export TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')") mongosh --nodb

次の操作では、 mongoshセッション内から新しい接続オブジェクトが作成されます。 AutoEncryptionOptsオプションは、 hr.employeesコレクションで自動クライアント側暗号化を有効にするために必要なオプションを指定します。

var autoEncryptionOpts = { "keyVaultNamespace" : "encryption.__dataKeys", "kmsProviders" : { "local" : { "key" : BinData(0, process.env["TEST_LOCAL_KEY"]) } }, schemaMap : { "hr.employees" : { "bsonType": "object", "properties" : { "taxid" : { "encrypt" : { "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")], "bsonType" : "string", "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random" } }, "taxid-short": { "encrypt": { "keyId": [UUID("33408ee9-e499-43f9-89fe-5f8533870617")], "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic", "bsonType": "string" } } } } }} cluster = Mongo( "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster", autoEncryptionOpts)

clusterオブジェクトに対して操作を発行して、 mymongo.example.net:27017クラスターとやり取りし、自動暗号化を利用します。

// returns the database objectmyDB = cluster.getDB("myDB"); // returns the collection objectmyColl = myDB.getCollection("myColl"); myColl.insertOne( { "name" : "J Doe", "taxid" : "123-45-6789", "taxid-short" : "6789" })

taxidtaxid-short指定された自動暗号化ルールは、指定されたデータ暗号化キーとアルゴリズムを使って フィールドと フィールドを暗号化します。正しい KMSと指定されたデータ暗号化キーにアクセスするために構成されたクライアントのみが フィールドを復号化できます。

次の操作では、 mongoshセッション内から新しい接続オブジェクトが作成されます。 mongo.tlsOptionsオプションを使用すると、KMS プロバイダーとして KMIP を使用する接続が有効になります。

var csfleConnection = { keyVaultNamespace: "encryption.__keyVault", kmsProviders: { kmip: { endpoint: "kmip.example.com:123" } }, tlsOptions: { kmip: { tlsCertificateKeyFile: "/path/to/client/cert-and-key-bundle.pem" } }} cluster = Mongo( "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster", csfleConnection);

クライアント側のフィールドレベル暗号化方法の完全なリストについては、「使用中の暗号化」を参照してください。

次の操作では、 mongoshセッション内から新しい接続オブジェクトが作成されます。 The api option enables Stable API V1 and specifies that you cannot run deprecated command or commands outside of the Stable API.

cluster = Mongo( "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster", null, { api: { version: "1", strict: true, deprecationErrors: true } })

mymongo.example.net:27017クラスターを操作するには、 clusterオブジェクトに対して操作を発行します。 Stable API コマンドの完全なリストについては、「 Stable API コマンド 」を参照してください。