共用方式為


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

適用於: 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.03.63.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 的索引。 陣列中的每個項目都必須包含一個或多個欄位的索引鍵、名稱,還可能包含索引選項。 例如,若要在欄位 ab 上建立複合唯一索引,請輸入:{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 概念: