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.

팁

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 Encryption의 두 가지 접근 방식을 제공합니다.

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 cluster입니다.

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

문자열

(필수) 키 볼트 컬렉션의 전체 네임스페이스입니다.

kmsProviders

문서

(필수) 고객 마스터 키(CMK)를 관리하기 위해 클라이언트 사이드 필드 레벨 암호화에 사용되는 키 관리 서비스(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 지원 의 경우 mongosh 또는 MongoDB 4.2.2 이상의 레거시 mongo 셸 사용하세요. 4.2.0 및 4.2.1 레거시 mongo 셸 KMS 응답 객체 의 예기치 않은 변경으로 인해 AWS KMS 서비스를 지원 하지 않습니다. 자세한 내용은 서버-44721를 참조하세요.

다음 필드를 사용하여 aws 문서를 kmsProviders로 지정합니다.

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

지정된 accessKeyId는 KMS 서비스용으로 모든 List 및 Read 권한이 있는 IAM 사용자와 반드시 일치해야 합니다.

일부 환경에서는 Amazon Web Services SDK가 자동으로 자격 증명 을 선택할 수 있습니다. SDK에 명시적인 자격 증명 을 제공하지 않고 사용을 활성화 하려면 세부 Amazon Web Services KMS Amazon Web Services kmsProvider 정보를 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는 개행 문자가 없는 base64로 인코딩된 96바이트 문자열이어야 합니다.

schemaMap

문서

(선택 사항) JSON schema 초안 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`	문자열	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")

mymongo.example.net:27017 클러스터와 상호 작용하려면 cluster 객체에 대해 작업을 실행합니다.

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

클라이언트 측 암호화가 활성화된 클러스터에 연결하기

mongosh 시작

mongosh 클라이언트를 시작합니다.

mongosh --nodb

키 생성

로컬로 managed 키에 대한 클라이언트 사이드 필드 수준 암호화를 구성하려면 줄바꿈 없이 base64로 인코딩된 96바이트 문자열을 생성합니다.

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

클라이언트 측 필드 레벨 암호화 옵션 생성

생성된 로컬 키 문자열을 사용하여 클라이언트 사이드 필드 수준 암호화 옵션을 생성합니다.

 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-바이트 문자열을 생성합니다.
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"
  }
)

지정된 자동 암호화 규칙은 지정된 데이터 암호화 키 및 알고리즘을 사용하여 taxid 및 taxid-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