使用 MongoDB 延伸模組命令，管理 Azure Cosmos DB for MongoDB 中儲存的資料

發行項
03/25/2024

適用於： MongoDB

下列文件包含 Azure Cosmos DB for MongoDB 專屬的自訂動作命令。您可以使用這些命令來建立和取得 Azure Cosmos DB 容量模型專屬的資料庫資源。

藉由使用 Azure Cosmos DB for MongoDB，您可以享受 Azure Cosmos DB 的共通優點。這些優點包括但不限於：

全域散發
自動分區化
高可用性
延遲保證
待用加密
備份

您可以在維護現有 MongoDB 應用程式的投資效益時享受這些優點。您可以使用任何開放原始碼 MongoDB 用戶端驅動程式，與 Azure Cosmos DB for MongoDB 通訊。 Azure Cosmos DB for MongoDB 依照 MongoDB 有線通訊協定，支援使用現有的用戶端驅動程式。

MongoDB 通訊協定支援

Azure Cosmos DB for MongoDB 與 MongoDB 伺服器 4.0、3.6 和 3.2 版相容。如需詳細資訊，請參閱 4.0、3.6 和 3.2 版中支援的功能和語法。

下列延伸模組命令可透過資料庫要求，建立和修改 Azure Cosmos DB 特有的資源：

建立資料庫
更新資料庫
取得資料庫
建立集合
更新集合
取得集合

建立資料庫

「建立資料庫」延伸模組命令建立新的 MongoDB 資料庫。可使用的資料庫名稱來自 use database 命令設定的資料庫內容。下表描述命令內的參數：

欄位	類型	描述
`customAction`	`string`	自訂命令的名稱。值必須是 `CreateDatabase`。
`offerThroughput`	`int`	您在資料庫上設定的佈建輸送量。這是選擇性參數。
`autoScaleSettings`	`Object`	自動調整模式的必要參數。此物件包含與自動調整容量模式相關聯的設定。您可以設定 `maxThroughput` 值，以描述集合可動態增加的要求單位數量上限。

輸出

如果命令成功，會傳回下列回應：

{ "ok" : 1 }

關於輸出中的參數，請參閱自訂命令的預設輸出。

範例：建立資料庫

若要使用所有預設值來建立名為 "test" 的資料庫，請使用下列命令：

use test
db.runCommand({customAction: "CreateDatabase"});

此命令建立無資料庫層級輸送量的資料庫。這項作業表示此資料庫中的集合必須指定您需要使用的輸送量。

範例：建立具有輸送量的資料庫

若要建立名為 "test" 的資料庫，並指定 1000 RU 的資料庫層級佈建輸送量，請使用下列命令：

use test
db.runCommand({customAction: "CreateDatabase", offerThroughput: 1000 });

此命令會建立資料庫，並設定資料庫的輸送量。除非使用特定的輸送量層級建立集合，否則此資料庫中的全部集合都共用設定的輸送量。

範例：建立具有自動調整輸送量的資料庫

若要建立名為 "test" 的資料庫，並在資料庫層級指定 20,000 RU/秒的自動調整最大輸送量，請使用下列命令：

use test
db.runCommand({customAction: "CreateDatabase", autoScaleSettings: { maxThroughput: 20000 } });

更新資料庫

「更新資料庫」延伸模組命令更新與特定資料庫相關聯的屬性。僅支援在 Azure 入口網站將資料庫從佈建輸送量變更為自動調整，反之亦然。下表描述命令內的參數：

欄位	類型	描述
`customAction`	`string`	自訂命令的名稱。值必須是 `UpdateDatabase`。
`offerThroughput`	`int`	當資料庫使用資料庫層級輸送量時，需要在資料庫上設定的新佈建輸送量
`autoScaleSettings`	`Object`	自動調整模式的必要參數。此物件包含與自動調整容量模式相關聯的設定。您可以設定 `maxThroughput` 值，以描述資料庫可動態增加的要求單位數量上限。

此命令使用工作階段內容中指定的資料庫。此資料庫與您在 use <database> 命令中使用的資料庫相同。目前無法使用此命令來變更資料庫名稱。

輸出

如果命令成功，會傳回下列回應：

{ "ok" : 1 }

關於輸出中的參數，請參閱自訂命令的預設輸出。

範例：更新與資料庫相關聯的佈建輸送量

若要將名為 "test" 的資料庫更新為 1200 RU 的佈建輸送量，請使用下列命令：

use test
db.runCommand({customAction: "UpdateDatabase", offerThroughput: 1200 });

範例：更新與資料庫相關聯的自動調整輸送量

若要將名為 "test" 的資料庫更新為 20,000 RU 的佈建輸送量，或轉換為自動調整輸送量層級，請使用下列命令：

use test
db.runCommand({customAction: "UpdateDatabase", autoScaleSettings: { maxThroughput: 20000 } });

取得資料庫

「取得資料庫」延伸模組命令傳回資料庫物件。使用的資料庫名稱來自執行命令的資料庫內容。

{
  customAction: "GetDatabase"
}

下表描述命令內的參數：

欄位	類型	描述
`customAction`	`string`	自訂命令的名稱。值必須是 `GetDatabase`。

輸出

如果命令成功，則回應包含的文件具有下列欄位：

欄位	類型	描述
`ok`	`int`	回應的狀態。 1 == 成功。 0 == 失敗。
`database`	`string`	資料庫的名稱。
`provisionedThroughput`	`int`	當資料庫使用手動資料庫層級輸送量時，在資料庫上設定的佈建輸送量
`autoScaleSettings`	`Object`	如果資料庫使用自動調整模式，此物件包含與資料庫相關聯的容量參數。 `maxThroughput` 值描述資料庫可動態增加的要求單位數量上限。

如果命令失敗，則會傳回預設的自訂命令回應。關於輸出中的參數，請參閱自訂命令的預設輸出。

範例：取得資料庫

若要針對名為 "test" 的資料庫取得資料庫物件，請使用下列命令：

use test
db.runCommand({customAction: "GetDatabase"});

如果資料庫沒有相關聯的輸送量，則輸出如下：

{ "database" : "test", "ok" : 1 }

如果資料庫具有相關聯的資料庫層級手動輸送量，則輸出會顯示 provisionedThroughput 值：

{ "database" : "test", "provisionedThroughput" : 20000, "ok" : 1 }

如果資料庫具有相關聯的資料庫層級自動調整輸送量，輸出會顯示 provisionedThroughput (描述資料庫的最小 RU/秒)，以及包含 maxThroughput (描述資料庫的最大 RU/秒) 的 autoScaleSettings 物件。

{
        "database" : "test",
        "provisionedThroughput" : 2000,
        "autoScaleSettings" : {
                "maxThroughput" : 20000
        },
        "ok" : 1
}

建立集合

「建立集合」延伸模組命令建立新的 MongoDB 集合。使用的資料庫名稱來自 use database 命令設定的資料庫內容。 CreateCollection 命令的格式如下所示：

{
  customAction: "CreateCollection",
  collection: "<Collection Name>",
  shardKey: "<Shard key path>",
  // Replace the line below with "autoScaleSettings: { maxThroughput: (int) }" to use Autoscale instead of Provisioned Throughput. Fill the required Autoscale max throughput setting.
  offerThroughput: (int) // Provisioned Throughput enabled with required throughput amount set.
  indexes: [{key: {_id: 1}, name: "_id_1"}, ... ] // Optional indexes (3.6+ accounts only).
}

下表描述命令內的參數：

欄位	類型	必要	描述
`customAction`	`string`	必要	自訂命令的名稱。值必須是 `CreateCollection`。
`collection`	`string`	必要	集合的名稱。不允許任何特殊字元或空格。
`offerThroughput`	`int`	選擇性	在資料庫上設定的佈建輸送量。如果未提供此參數，則預設為最小 400 RU/秒。 * 若要指定超過 10,000 RU/秒的輸送量，則需要 `shardKey` 參數。
`shardKey`	`string`	大輸送量的集合需要此參數	分區化集合的分區索引鍵路徑。如果您在 `offerThroughput` 中設定超過 10,000 RU/秒，則需要此參數。如果指定此參數，則全部插入的文件都需要此索引鍵和值。
`autoScaleSettings`	`Object`	自動調整模式的必要參數	此物件包含與自動調整容量模式相關聯的設定。您可以設定 `maxThroughput` 值，以描述集合可動態增加的要求單位數量上限。
`indexes`	`Array`	選擇性設定索引。只有 3.6+ 的帳戶支援此參數。	有此參數時，需要 _id 的索引。陣列中的每個項目都必須包含一個或多個欄位的索引鍵、名稱，還可能包含索引選項。例如，若要在欄位 `a` 和 `b` 上建立複合唯一索引，請輸入：`{key: {a: 1, b: 1}, name:"a_1_b_1", unique: true}`。

輸出

傳回預設的自訂命令回應。關於輸出中的參數，請參閱自訂命令的預設輸出。

範例：建立具有最小設定的集合

若要建立名為 "testCollection" 且使用預設值的新集合，請使用下列命令：

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection"});

這項作業會產生固定、未分區的新集合，具有 400 RU/秒，並在 _id 欄位上自動建立索引。透過 insert() 函式建立新的集合時也適用這種設定。例如：

use test
db.newCollection.insert({});

範例：建立未分區化集合

若要建立名為 "testCollection" 且佈建輸送量為 1,000 RU 的未分區化集合，請使用下列命令：

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", offerThroughput: 1000});

您可以建立 offerThroughput 高達 10,000 RU/秒的集合，而不需要指定分區索引鍵。如需輸送量更大的集合，請參閱下一節。

範例：建立分區化集合

若要建立名為 "testCollection"、佈建輸送量為 11,000 RU，且 shardkey 屬性為 “a.b”的分區化集合，請使用下列命令：

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", offerThroughput: 11000, shardKey: "a.b" });

此命令現在需要 shardKey 參數，因為 offerThroughput 中指定超過 10,000 RU/秒。

範例：建立未分區化自動調整集合

若要建立名為 'testCollection'，且自動調整輸送量容量設為 4,000 RU/秒的未分區集合，請使用下列命令：

use test
db.runCommand({ 
    customAction: "CreateCollection", collection: "testCollection", 
    autoScaleSettings:{
      maxThroughput: 4000
    } 
});

針對 autoScaleSettings.maxThroughput 值，指定 4,000 RU/秒到 10,000 RU/秒的範圍都不需要使用分區索引鍵。如需更高的自動調整輸送量，您必須指定 shardKey 參數。

範例：建立分區化自動調整集合

若要建立名為 'testCollection'、分區索引鍵為 'a.b'，且自動調整輸送量容量設為 20,000 RU/秒的分區化集合，請使用下列命令：

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", shardKey: "a.b", autoScaleSettings: { maxThroughput: 20000 }});

更新集合

「更新集合」延伸模組命令更新與特定集合相關聯的屬性。僅支援在 Azure 入口網站將集合從佈建輸送量變更為自動調整，反之亦然。

{
  customAction: "UpdateCollection",
  collection: "<Name of the collection that you want to update>",
  // Replace the line below with "autoScaleSettings: { maxThroughput: (int) }" if using Autoscale instead of Provisioned Throughput. Fill the required Autoscale max throughput setting. Changing between Autoscale and Provisioned throughput is only supported in the Azure Portal.
  offerThroughput: (int) // Provisioned Throughput enabled with required throughput amount set.
  indexes: [{key: {_id: 1}, name: "_id_1"}, ... ] // Optional indexes (3.6+ accounts only).
}

下表描述命令內的參數：

欄位	類型	描述
`customAction`	`string`	自訂命令的名稱。值必須是 `UpdateCollection`。
`collection`	`string`	集合的名稱。
`offerThroughput`	`int`	在集合上設定的佈建輸送量。
`autoScaleSettings`	`Object`	自動調整模式的必要參數。此物件包含與自動調整容量模式相關聯的設定。 `maxThroughput` 值描述集合可動態增加的要求單位數量上限。
`indexes`	`Array`	選擇性設定索引。只有 3.6+ 的帳戶支援此參數。有此參數時，將會以指定的索引集取代集合的現有索引 (包括卸除索引)。需要 _id 的索引。陣列中的每個項目都必須包含一個或多個欄位的索引鍵、名稱，還可能包含索引選項。例如，若要在欄位 a 和 b 上建立複合唯一索引，請輸入：`{key: {a: 1, b: 1}, name: "a_1_b_1", unique: true}`。

輸出

傳回預設的自訂命令回應。關於輸出中的參數，請參閱自訂命令的預設輸出。

範例：更新與集合相關聯的佈建輸送量

若要將名為 "testCollection" 的集合更新為 1,200 RU 的佈建輸送量，請使用下列命令：

use test
db.runCommand({customAction: "UpdateCollection", collection: "testCollection", offerThroughput: 1200 });

取得集合

「取得集合」自訂命令傳回集合物件。

{
  customAction: "GetCollection",
  collection: "<Name of the collection>"
}

下表描述命令內的參數：

欄位	類型	描述
`customAction`	`string`	自訂命令的名稱。值必須是 `GetCollection`。
`collection`	`string`	集合的名稱。

輸出

如果命令成功，則回應包含的文件具有下列欄位

欄位	類型	描述
`ok`	`int`	回應的狀態。 1 == 成功。 0 == 失敗。
`database`	`string`	資料庫的名稱。
`collection`	`string`	集合的名稱。
`shardKeyDefinition`	`document`	作為分區索引鍵的索引規格文件。這個欄位是選擇性的回應參數。
`provisionedThroughput`	`int`	在集合上設定的佈建輸送量。這個欄位是選擇性的回應參數。
`autoScaleSettings`	`Object`	如果資料庫使用自動調整模式，此物件包含與資料庫相關聯的容量參數。 `maxThroughput` 值描述集合可動態增加的要求單位數量上限。

如果命令失敗，則會傳回預設的自訂命令回應。關於輸出中的參數，請參閱自訂命令的預設輸出。

範例：取得集合

若要取得名為 "testCollection" 集合的集合物件，請使用下列命令：

use test
db.runCommand({customAction: "GetCollection", collection: "testCollection"});

如果集合具有相關聯的輸送量容量，則會包含 provisionedThroughput 值，而且輸出如下：

{
        "database" : "test",
        "collection" : "testCollection",
        "provisionedThroughput" : 400,
        "ok" : 1
}

如果集合具有相關聯的自動調整輸送量，則會包含 autoScaleSettings 物件和 maxThroughput 參數，此參數定義集合動態增加的最大輸送量。此外還包含 provisionedThroughput 值，用以定義當此集合中沒要求時，此集合降低的輸送量下限：

{
        "database" : "test",
        "collection" : "testCollection",
        "provisionedThroughput" : 1000,
        "autoScaleSettings" : {
            "maxThroughput" : 10000
        },
        "ok" : 1
}

如果集合在自動調整或手動模式下共用資料庫層級輸送量，則輸出如下：

{ "database" : "test", "collection" : "testCollection", "ok" : 1 }

{
        "database" : "test",
        "provisionedThroughput" : 2000,
        "autoScaleSettings" : {
            "maxThroughput" : 20000
        },
        "ok" : 1
}

平行處理變更資料流

大規模使用變更串流時，最好將負載平均分散。下列命令傳回一個或多個變更串流繼續權杖，各對應至單一實體分區/分割區的資料 (一個實體分割區中可以存在多個邏輯分區/分割區)。每個繼續權杖會導致 watch() 只傳回該實體分區/分割區中的資料。

在每個繼續權杖上使用 db.collection.watch() (每個權杖一個執行緒)，可有效率縮放變更串流。

{
        customAction: "GetChangeStreamTokens", 
        collection: "<Name of the collection>", 
        startAtOperationTime: "<BSON Timestamp>" // Optional. Defaults to the time the command is run.
}

範例：取得串流權杖

執行自訂命令以取得每個實體分區/分割區的繼續權杖。

use test
db.runCommand({customAction: "GetChangeStreamTokens", collection: "<Name of the collection>"})

針對從 GetChangeStreamTokens 自訂命令傳回的每個繼續權杖，執行 watch() 執行緒/處理序。以下是一個執行緒的範例。

db.test_coll.watch([{ $match: { "operationType": { $in: ["insert", "update", "replace"] } } }, { $project: { "_id": 1, "fullDocument": 1, "ns": 1, "documentKey": 1 } }], 
{fullDocument: "updateLookup", 
resumeAfter: { "_data" : BinData(0,"eyJWIjoyLCJSaWQiOiJQeFVhQUxuMFNLRT0iLCJDb250aW51YXRpb24iOlt7IkZlZWRSYW5nZSI6eyJ0eXBlIjoiRWZmZWN0aXZlIFBhcnRpdGlvbiBLZXkgUmFuZ2UiLCJ2YWx1ZSI6eyJtaW4iOiIiLCJtYXgiOiJGRiJ9fSwiU3RhdGUiOnsidHlwZSI6ImNvbnRpbndkFLbiIsInZhbHVlIjoiXCIxODQ0XCIifX1dfQ=="), "_kind" : NumberInt(1)}})

resumeAfter 欄位中的文件 (值) 代表繼續權杖。對於自從 GetChangeStreamTokens 自訂命令執行後，該實體分割區上插入、更新或取代的全部文件，命令 watch() 會傳回一個游標。此處包含傳回的資料範例。

{
  "_id": {
    "_data": BinData(0,
    "eyJWIjoyLCJSaWQiOiJQeFVhQUxuMFNLRT0iLCJDfdsfdsfdsft7IkZlZWRSYW5nZSI6eyJ0eXBlIjoiRWZmZWN0aXZlIFBhcnRpdGlvbiBLZXkgUmFuZ2UiLCJ2YWx1ZSI6eyJtaW4iOiIiLCJtYXgiOiJGRiJ9fSwiU3RhdGUiOnsidHlwZSI6ImNvbnRpbnVhdGlvbiIsInZhbHVlIjoiXCIxOTgwXCIifX1dfQ=="),
    "_kind": 1
  },
  "fullDocument": {
    "_id": ObjectId("60da41ec9d1065b9f3b238fc"),
    "name": John,
    "age": 6
  },
  "ns": {
    "db": "test-db",
    "coll": "test_coll"
  },
  "documentKey": {
    "_id": ObjectId("60da41ec9d1065b9f3b238fc")
  }
}

傳回的每個文件都包含繼續權杖 (每一頁的權杖都相同)。應該儲存此繼續權杖，並於執行緒/處理程終止時重複使用。此繼續權杖會從您離開的地方接續，而且只接收來自該實體分割區的資料。

自訂命令的預設輸出

如果未指定欄位，則自訂回應包含的文件具有下列欄位：

欄位	類型	描述
`ok`	`int`	回應的狀態。 1 == 成功。 0 == 失敗。
`code`	`int`	僅在命令失敗時傳回 (亦即 ok == 0)。包含 MongoDB 錯誤碼。這個欄位是選擇性的回應參數。
`errMsg`	`string`	僅在命令失敗時傳回 (亦即 ok == 0)。包含使用者容易理解的錯誤訊息。這個欄位是選擇性的回應參數。

例如：

{ "ok" : 1 }

下一步

接下來，您可以繼續了解下列 Azure Cosmos DB 概念：

使用 MongoDB 延伸模組命令，管理 Azure Cosmos DB for MongoDB 中儲存的資料

MongoDB 通訊協定支援

建立資料庫

輸出

範例：建立資料庫

範例：建立具有輸送量的資料庫

範例：建立具有自動調整輸送量的資料庫

更新資料庫

輸出

範例：更新與資料庫相關聯的佈建輸送量

範例：更新與資料庫相關聯的自動調整輸送量

取得資料庫

輸出

範例：取得資料庫

建立集合

輸出

範例：建立具有最小設定的集合

範例：建立未分區化集合

範例：建立分區化集合

範例：建立未分區化自動調整集合

範例：建立分區化自動調整集合

更新集合

輸出

範例：更新與集合相關聯的佈建輸送量

取得集合

輸出

範例：取得集合

平行處理變更資料流

範例：取得串流權杖

自訂命令的預設輸出

下一步

其他資源