Mongo()

項目一覧

説明

互換性
AutoEncryptionOpts
api
例
MongoDB クラスターへの接続
クライアント側の暗号化が有効になっているクラスターへの接続
自動クライアント側暗号化が有効になっているクラスターへの接続
Stable API が有効になっているクラスターへの接続

説明

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`を参照してください。

Tip

以下も参照してください。

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

互換性

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

MongoDB Atlas はクラウドでの MongoDB 配置のためのフルマネージドサービスです

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

`AutoEncryptionOpts`

autoEncryptionOptsドキュメントでは、クライアント側フィールドレベル暗号化の構成オプションを指定します。データベース接続に既存のクライアント側のフィールドレベル暗号化構成がある場合は、 autoEncryptionOptsを指定するとその構成が上書きされます。

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

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

{
  "keyVaultClient" : <object>,
  "keyVaultNamespace" : "<string>",
  "kmsProviders" : <object>,
  "schemaMap" : <object>,
  "bypassAutoEncryption" : <boolean>,
  "tlsOptions": <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 Amazon Web ServicesKMSmongoshをサポートするには、またはMongoDB 以降のレガシーMongoDB4.2.2mongoshell シェルを使用します。4 。 2 。 0と 4 。 2 。 1レガシーシェルは、 mongoshellAmazon Web ServicesKMSKMS 応答オブジェクトの予期しない変更により、 Amazon Web Services KMS サービスをサポートしていません。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 schema ドラフト4標準構文と暗号化固有のキーワードを使用して指定された、自動クライアント側のフィールドレベル暗号化ルール。このオプションはexplicitEncryptionOnlyと排他関係にあります。

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

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 オプション」を参照してください。

`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 クラスターへの接続

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

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を使用して、クライアント側のフィールドレベル暗号化オプションを作成します。

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

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

データベース接続を作成するには、クライアント側のフィールドレベル暗号化オプションが構成された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 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 を生成し、改行を含まない
キーを読み込むには、 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 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と指定されたデータ暗号化キーにアクセスするために構成されたクライアントのみがフィールドを復号化できます。

次の操作では、 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
);

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

次の操作では、 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 コマンド」を参照してください。

戻る

接続

Mongo.getDB