共用方式為


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

適用於: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 帳戶、資料庫和容器。

必要條件

  • 本文需要 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 帳戶,具有 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 容器,包括:

建立容器

建立 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 的詳細資訊,請參閱: