使用 Azure CLI 管理 Azure Cosmos DB for NoSQL 資源

發行項
03/09/2023

適用於：NoSQL

下列指南說明使用 Azure CLI 自動管理 Azure Cosmos DB 帳戶、資料庫及容器的常見命令。您可以在 Azure CLI 參考中取得所有 Azure Cosmos DB CLI 命令的參考頁面。您也可以在適用於 Azure Cosmos DB 的 Azure CLI 範例中找到更多範例，包括如何針對 MongoDB、Gremlin、Cassandra 及 API for Table 建立和管理 Azure Cosmos DB 帳戶、資料庫和容器。

必要條件

在 Azure Cloud Shell 中使用 Bash 環境。如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。
若要在本地執行 CLI 參考命令，請安裝 Azure CLI。若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。
- 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。請遵循您終端機上顯示的步驟，完成驗證程序。如需其他登入選項，請參閱使用 Azure CLI 登入。
- 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。如需擴充功能詳細資訊，請參閱使用 Azure CLI 擴充功能。
- 執行 az version 以尋找已安裝的版本和相依程式庫。若要升級至最新版本，請執行 az upgrade。

本文需要 2.22.1 版或更新版本的 Azure CLI。如果您是使用 Azure Cloud Shell，就已安裝最新版本。

如需適用於其他 API 的 Azure CLI 範例，請參閱適用於 Cassandra 的 CLI 範例、適用於 API for MongoDB 的 CLI 範例、適用於 Gremlin 的 CLI 範例、適用於資料表的 CLI 範例

重要

無法重新命名 Azure Cosmos DB 資源，因為這違反了 Azure Resource Manager 搭配資源 URI 運作的方式。

Azure Cosmos DB 帳戶

下列各節會示範如何管理 Azure Cosmos DB 帳戶，包括：

建立 Azure Cosmos DB 帳戶
新增或移除區域
啟用多重區域寫入
設定區域容錯移轉優先順序
啟用服務管理容錯移轉
觸發手動容錯移轉
列出帳戶金鑰
列出唯讀帳戶金鑰
列出連接字串
重新產生帳戶金鑰

建立 Azure Cosmos DB 帳戶

建立 Azure Cosmos DB 帳戶，具有 API for NoSQL、美國西部和美國東部區域的工作階段一致性：

重要

Azure Cosmos DB 帳戶名稱必須是小寫，且少於 44 個字元。

resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount' #needs to be lower case and less than 44 characters

az cosmosdb create \
    -n $accountName \
    -g $resourceGroupName \
    --default-consistency-level Session \
    --locations regionName='West US' failoverPriority=0 isZoneRedundant=False \
    --locations regionName='East US' failoverPriority=1 isZoneRedundant=False

新增或移除區域

建立具有兩個區域的 Azure Cosmos DB 帳戶、新增區域，以及移除區域。

注意

您不能同時新增或移除區域 locations，以及變更 Azure Cosmos DB 帳戶的其他屬性。修改區域必須與帳戶資源的任何其他變更分開作業。

注意

此命令可讓您新增及移除區域，但不允許您修改容錯移轉優先順序或觸發手動容錯移轉。請參閱設定容錯移轉優先順序和觸發手動容錯移轉。

提示

新增區域時，所有資料都必須完全複寫並認可到新的區域，才能將該區域標示為可用。此作業所需的時間取決於帳戶中儲存的資料量。如果非同步輸送量調整作業正在進行中，輸送量擴大規模作業將會暫停，並會在新增/移除區域作業完成時自動繼續。

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

# Create an account with 2 regions
az cosmosdb create --name $accountName --resource-group $resourceGroupName \
    --locations regionName="West US" failoverPriority=0 isZoneRedundant=False \
    --locations regionName="East US" failoverPriority=1 isZoneRedundant=False

# Add a region
az cosmosdb update --name $accountName --resource-group $resourceGroupName \
    --locations regionName="West US" failoverPriority=0 isZoneRedundant=False \
    --locations regionName="East US" failoverPriority=1 isZoneRedundant=False \
    --locations regionName="South Central US" failoverPriority=2 isZoneRedundant=False

# Remove a region
az cosmosdb update --name $accountName --resource-group $resourceGroupName \
    --locations regionName="West US" failoverPriority=0 isZoneRedundant=False \
    --locations regionName="East US" failoverPriority=1 isZoneRedundant=False

啟用多重寫入區域

為 Azure Cosmos DB 帳戶啟用多重區域寫入

# Update an Azure Cosmos DB account from single write region to multiple write regions
resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

# Get the account resource id for an existing account
accountId=$(az cosmosdb show -g $resourceGroupName -n $accountName --query id -o tsv)

az cosmosdb update --ids $accountId --enable-multiple-write-locations true

設定容錯移轉優先順序

為已設定服務管理容錯移轉的 Azure Cosmos DB 帳戶設定容錯移轉優先順序

# Assume region order is initially 'West US'=0 'East US'=1 'South Central US'=2 for account
resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

# Get the account resource id for an existing account
accountId=$(az cosmosdb show -g $resourceGroupName -n $accountName --query id -o tsv)

# Make South Central US the next region to fail over to instead of East US
az cosmosdb failover-priority-change --ids $accountId \
    --failover-policies 'West US=0' 'South Central US=1' 'East US=2'

啟用服務管理容錯移轉

# Enable service-managed failover on an existing account
resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

# Get the account resource id for an existing account
accountId=$(az cosmosdb show -g $resourceGroupName -n $accountName --query id -o tsv)

az cosmosdb update --ids $accountId --enable-automatic-failover true

觸發手動容錯移轉

警告

變更區域的優先順序 = 0 將會觸發 Azure Cosmos DB 帳戶的手動容錯移轉。變更其他優先順序則不會觸發容錯移轉。

注意

如果您在進行非同步調整規模作業時執行手動容錯移轉作業，則會暫停輸送量擴大規模作業。當容錯移轉作業完成時，該作業便會自動繼續。

# Assume region order is initially 'West US=0' 'East US=1' 'South Central US=2' for account
resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'

# Get the account resource id for an existing account
accountId=$(az cosmosdb show -g $resourceGroupName -n $accountName --query id -o tsv)

# Trigger a manual failover to promote East US 2 as new write region
az cosmosdb failover-priority-change --ids $accountId \
    --failover-policies 'East US=0' 'South Central US=1' 'West US=2'

列出所有帳戶金鑰

取得 Azure Cosmos DB 帳戶的所有金鑰。

# List all account keys
resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'

az cosmosdb keys list \
   -n $accountName \
   -g $resourceGroupName

列出唯讀帳戶金鑰

取得 Azure Cosmos DB 帳戶的唯讀金鑰。

# List read-only account keys
resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'

az cosmosdb keys list \
    -n $accountName \
    -g $resourceGroupName \
    --type read-only-keys

列出連接字串

取得 Azure Cosmos DB 帳戶的連接字串。

# List connection strings
resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'

az cosmosdb keys list \
    -n $accountName \
    -g $resourceGroupName \
    --type connection-strings

重新產生帳戶金鑰

為 Azure Cosmos DB 帳戶重新產生新的金鑰。

# Regenerate secondary account keys
# key-kind values: primary, primaryReadonly, secondary, secondaryReadonly
az cosmosdb keys regenerate \
    -n $accountName \
    -g $resourceGroupName \
    --key-kind secondary

Azure Cosmos DB 資料庫

下列各節會示範如何管理 Azure Cosmos DB 資料庫，包括：

建立資料庫
建立具有共用輸送量的資料庫
移轉資料庫以自動調整輸送量
變更資料庫輸送量
防止資料庫遭刪除

建立資料庫

建立 Azure Cosmos DB 資料庫。

resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'

az cosmosdb sql database create \
    -a $accountName \
    -g $resourceGroupName \
    -n $databaseName

建立具有共用輸送量的資料庫

使用共用輸送量來建立 Azure Cosmos DB 資料庫。

resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
throughput=400

az cosmosdb sql database create \
    -a $accountName \
    -g $resourceGroupName \
    -n $databaseName \
    --throughput $throughput

移轉資料庫以自動調整輸送量

resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'

# Migrate to autoscale throughput
az cosmosdb sql database throughput migrate \
    -a $accountName \
    -g $resourceGroupName \
    -n $databaseName \
    -t 'autoscale'

# Read the new autoscale max throughput
az cosmosdb sql database throughput show \
    -g $resourceGroupName \
    -a $accountName \
    -n $databaseName \
    --query resource.autoscaleSettings.maxThroughput \
    -o tsv

變更資料庫輸送量

增加 1000 RU/秒的 Azure Cosmos DB 資料庫輸送量。

resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
newRU=1000

# Get minimum throughput to make sure newRU is not lower than minRU
minRU=$(az cosmosdb sql database throughput show \
    -g $resourceGroupName -a $accountName -n $databaseName \
    --query resource.minimumThroughput -o tsv)

if [ $minRU -gt $newRU ]; then
    newRU=$minRU
fi

az cosmosdb sql database throughput update \
    -a $accountName \
    -g $resourceGroupName \
    -n $databaseName \
    --throughput $newRU

防止資料庫遭刪除

在資料庫上放置 Azure 資源刪除鎖定，以防止其遭到刪除。這項功能需要鎖定 Azure Cosmos DB 帳戶，以防止資料平面 SDK 變更。若要深入瞭解，請參閱防止 SDK 的變更。 Azure 資源鎖定也可以藉由指定 ReadOnly 鎖定類型來防止資源遭變更。對於 Azure Cosmos DB 資料庫，可用來防止輸送量遭變更。

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'

lockType='CanNotDelete' # CanNotDelete or ReadOnly
databaseParent="databaseAccounts/$accountName"
databaseLockName="$databaseName-Lock"

# Create a delete lock on database
az lock create --name $databaseLockName \
    --resource-group $resourceGroupName \
    --resource-type Microsoft.DocumentDB/sqlDatabases \
    --lock-type $lockType \
    --parent $databaseParent \
    --resource $databaseName

# Delete lock on database
lockid=$(az lock show --name $databaseLockName \
        --resource-group $resourceGroupName \
        --resource-type Microsoft.DocumentDB/sqlDatabases \
        --resource $databaseName \
        --parent $databaseParent \
        --output tsv --query id)
az lock delete --ids $lockid

Azure Cosmos DB 容器

下列各節會示範如何管理 Azure Cosmos DB 容器，包括：

建立容器
使用自動調整建立容器
建立已啟用 TTL 的容器
建立含有自訂索引原則的容器
變更容器輸送量
移轉容器以自動調整輸送量
防止容器遭刪除

建立容器

建立 Azure Cosmos DB 容器，具有預設索引原則、分割區索引鍵和 400 RU/秒。

# Create a API for NoSQL container
resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
containerName='container1'
partitionKey='/myPartitionKey'
throughput=400

az cosmosdb sql container create \
    -a $accountName -g $resourceGroupName \
    -d $databaseName -n $containerName \
    -p $partitionKey --throughput $throughput

建立具有自動調整的容器

建立 Azure Cosmos DB 容器，具有預設索引原則、分割區索引鍵和自動調整 4000 RU/秒。

# Create a API for NoSQL container
resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
containerName='container1'
partitionKey='/myPartitionKey'
maxThroughput=4000

az cosmosdb sql container create \
    -a $accountName -g $resourceGroupName \
    -d $databaseName -n $containerName \
    -p $partitionKey --max-throughput $maxThroughput

建立具有 TTL 的容器

建立 Azure Cosmos DB 容器並啟用 TTL。

# Create an Azure Cosmos DB container with TTL of one day
resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
containerName='container1'

az cosmosdb sql container update \
    -g $resourceGroupName \
    -a $accountName \
    -d $databaseName \
    -n $containerName \
    --ttl=86400

建立含有自訂索引原則的容器

建立 Azure Cosmos DB 容器，具有自訂索引原則、空間索引、複合索引、分割區索引鍵和 400 RU/秒。

# Create a API for NoSQL container
resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
containerName='container1'
partitionKey='/myPartitionKey'
throughput=400

# Generate a unique 10 character alphanumeric string to ensure unique resource names
uniqueId=$(env LC_CTYPE=C tr -dc 'a-z0-9' < /dev/urandom | fold -w 10 | head -n 1)

# Define the index policy for the container, include spatial and composite indexes
idxpolicy=$(cat << EOF
{
    "indexingMode": "consistent",
    "includedPaths": [
        {"path": "/*"}
    ],
    "excludedPaths": [
        { "path": "/headquarters/employees/?"}
    ],
    "spatialIndexes": [
        {"path": "/*", "types": ["Point"]}
    ],
    "compositeIndexes":[
        [
            { "path":"/name", "order":"ascending" },
            { "path":"/age", "order":"descending" }
        ]
    ]
}
EOF
)
# Persist index policy to json file
echo "$idxpolicy" > "idxpolicy-$uniqueId.json"


az cosmosdb sql container create \
    -a $accountName -g $resourceGroupName \
    -d $databaseName -n $containerName \
    -p $partitionKey --throughput $throughput \
    --idx @idxpolicy-$uniqueId.json

# Clean up temporary index policy file
rm -f "idxpolicy-$uniqueId.json"

變更容器輸送量

增加 1000 RU/秒的 Azure Cosmos DB 容器輸送量。

resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
containerName='container1'
newRU=1000

# Get minimum throughput to make sure newRU is not lower than minRU
minRU=$(az cosmosdb sql container throughput show \
    -g $resourceGroupName -a $accountName -d $databaseName \
    -n $containerName --query resource.minimumThroughput -o tsv)

if [ $minRU -gt $newRU ]; then
    newRU=$minRU
fi

az cosmosdb sql container throughput update \
    -a $accountName \
    -g $resourceGroupName \
    -d $databaseName \
    -n $containerName \
    --throughput $newRU

移轉容器以自動調整輸送量

resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
containerName='container1'

# Migrate to autoscale throughput
az cosmosdb sql container throughput migrate \
    -a $accountName \
    -g $resourceGroupName \
    -d $databaseName \
    -n $containerName \
    -t 'autoscale'

# Read the new autoscale max throughput
az cosmosdb sql container throughput show \
    -g $resourceGroupName \
    -a $accountName \
    -d $databaseName \
    -n $containerName \
    --query resource.autoscaleSettings.maxThroughput \
    -o tsv

防止容器遭刪除

在容器上放置 Azure 資源刪除鎖定，以防止其遭到刪除。這項功能需要鎖定 Azure Cosmos DB 帳戶，以防止資料平面 SDK 變更。若要深入瞭解，請參閱防止 SDK 的變更。 Azure 資源鎖定也可以藉由指定 ReadOnly 鎖定類型來防止資源遭變更。對於 Azure Cosmos DB 容器，鎖定可用來防止輸送量或任何其他屬性遭變更。

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
databaseName='database1'
containerName='container1'

lockType='CanNotDelete' # CanNotDelete or ReadOnly
databaseParent="databaseAccounts/$accountName"
containerParent="databaseAccounts/$accountName/sqlDatabases/$databaseName"
containerLockName="$containerName-Lock"

# Create a delete lock on container
az lock create --name $containerLockName \
    --resource-group $resourceGroupName \
    --resource-type Microsoft.DocumentDB/containers \
    --lock-type $lockType \
    --parent $containerParent \
    --resource $containerName

# Delete lock on container
lockid=$(az lock show --name $containerLockName \
        --resource-group $resourceGroupName \
        --resource-type Microsoft.DocumentDB/containers \
        --resource-name $containerName \
        --parent $containerParent \
        --output tsv --query id)
az lock delete --ids $lockid

下一步

如需 Azure CLI 的詳細資訊，請參閱：