mongo()（mongoshメソッド）

説明

Mongo(host, autoEncryptionOpts, api)

JavaScript constructor to instantiate a database connection from mongosh or from a JavaScript file.

The Mongo() method has the following parameters:

Parameter	タイプ	説明
`host`	string または`Mongo`インスタンス	任意。ホストまたは接続string 。 The host can either be a connection string or in the form of `<host>` or `<host><:port>`. The connection string can be in the form of a `Mongo` instance. If you specify a `Mongo` instance, the `Mongo()` constructor uses the connection string of the specified Mongo instance. If omitted, `Mongo()` instantiates a connection to the localhost interface on the default port `27017`.
`autoEncryptionOpts`	ドキュメント	任意。使用中の暗号化を有効にするための構成パラメーター。 `autoEncryptionOpts` overrides the existing in-use encryption configuration of the database connection. If omitted, `Mongo()` inherits the in-use encryption configuration of the current database connection. See `AutoEncryptionOpts` for usage and syntax details.
`api`	ドキュメント	任意。 Stable API を有効にするための構成オプション。 See `api` for usage and syntax details.

Tip

Mongo.getDB() および db.getMongo()

互換性

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

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

MongoDB Enterprise: サブスクリプションベースの自己管理型 MongoDB バージョン
MongoDB Community: ソースが利用可能で、無料で使用できる自己管理型の MongoDB のバージョン

`AutoEncryptionOpts`

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

For example, starting mongosh with client-side field level encryption command-line options enables client-side encryption for that connection. New database connections created using Mongo() inherit the encryption settings unless Mongo() includes autoEncryptionOpts.

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

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

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

Parameter

タイプ

説明

keyVaultClient

Mongo() 最大数。

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

Specify a Mongo() connection object pointing to the cluster:

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

If keyVaultClient is omitted, the host specified to the Mongo() object containing the autoEncryptionOpts document is used as the key vault host.

keyVaultNamespace

string

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

kmsProviders

ドキュメント

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

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

If possible, consider defining the credentials provided in kmsProviders as environment variables, and then passing them to mongosh using the --eval option. This minimizes the chances of credentials leaking into logs. See Create a Data Key for examples of this approach for each supported KMS.

Amazon Web Services KMS

重要: AWS KMS サポートには、またはMongoDB..mongosh 以降のレガシー4 22mongoシェル4 2を使用します。..0 42および..1 mongoレガシーシェルは、 KMS 応答オブジェクトの予期しない変更により、 AWS 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

オブジェクト

(Optional) The path to the TLS client certificate and private key file in PEM format (tlsCertificateKeyFile), TLS client certificate and private key file password (tlsCertificateKeyFilePassword), or TLS certificate authority file (tlsCAFile) to use to connect to the KMS in PEM format. To learn more about these options, see TLS Options.

encryptedFieldsMap

ドキュメント

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

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

`api`

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

オプション	タイプ	説明
`version`	string	API バージョンを指定します。`"1"` は現在サポートされている唯一のバージョンです。
`strict`	ブール値	`true`場合: 宣言した API バージョンに含まれないコマンドを使用すると、 APIStrictErrorエラーが返されます。 Stable API でサポートされていないインデックスは、クエリプランナーによって無視されます。 `strict`を指定する場合は、 `version`も指定する必要があります。指定しない場合、デフォルトで `false` になります。
`deprecationErrors`	ブール値	`true`の場合、指定された API バージョンで非推奨のコマンドまたは動作を使用すると、 APIDeprecationErrorが返されます。 `deprecationErrors`を指定する場合は、 `version`も指定する必要があります。指定しない場合、デフォルトで `false` になります。

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

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

例

MongoDB クラスターへの接続

The following operation creates a new connection object from within a mongosh session:

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

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

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

クライアント側の暗号化が有効になっているクラスターへの接続

mongosh を起動する

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

mongosh --nodb

キーの生成

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

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

クライアント側のフィールドレベル暗号化オプションの作成

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

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

暗号化されたクライアントの作成

Use the Mongo() constructor with the client-side field level encryption options configured to create a database connection. Replace the mongodb://myMongo.example.net URI with the connection string URI of the target cluster.

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

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

// returns the database object
myDB = cluster.getDB("myDB");
// returns the collection object
myColl = myDB.getCollection("myColl");
// returns object for managing data encryption keys
keyVault = cluster.getKeyVault();
// returns object for explicit encryption/decryption
clientEncryption = cluster.getClientEncryption();

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

自動クライアント側暗号化が有効になっているクラスターへの接続

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

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

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

The following operation creates a new connection object from within a mongosh session. The AutoEncryptionOpts option specifies the required options for enabling automatic client-side encryption on the hr.employees collection:

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 object
myDB = cluster.getDB("myDB");
// returns the collection object
myColl = myDB.getCollection("myColl");
myColl.insertOne(
  {
    "name" : "J Doe",
    "taxid" : "123-45-6789",
    "taxid-short" : "6789"
  }
)

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

The following operation creates a new connection object from within a mongosh session. The mongo.tlsOptions option enables a connection using KMIP as the KMS provider:

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
);

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

Stable API が有効になっているクラスターへの接続

The following operation creates a new connection object from within a mongosh session. 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 コマンド」を参照してください。

戻る

接続

Mongo.getDB