Mengelola Azure Cosmos DB untuk sumber daya NoSQL menggunakan Azure CLI

Panduan berikut menjelaskan perintah umum untuk mengotomatiskan manajemen akun, database, dan kontainer Azure Cosmos DB Anda menggunakan Azure CLI. Halaman referensi untuk semua perintah CLI Azure Cosmos DB tersedia di Referensi CLI Azure.

Prerequisites

• Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai menggunakan Azure Cloud Shell.

  

• Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, instal Azure CLI. Jika Anda menjalankan Windows atau macOS, pertimbangkan untuk menjalankan Azure CLI dalam kontainer Docker. Untuk informasi lebih lanjut, lihat Cara menjalankan Azure CLI di kontainer Docker.

  • Jika Anda menggunakan instalasi lokal, masuk ke Azure CLI dengan menggunakan perintah az login. Untuk menyelesaikan proses autentikasi, ikuti langkah-langkah yang ditampilkan di terminal Anda. Untuk opsi masuk lainnya, lihat Mengautentikasi ke Azure menggunakan Azure CLI.

  • Saat diminta, instal ekstensi Azure CLI saat pertama kali digunakan. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan dan mengelola ekstensi dengan Azure CLI.

  • Jalankan az version untuk menemukan versi dan pustaka dependen yang terinstal. Untuk meng-upgrade ke versi terbaru, jalankan az upgrade.

• Artikel ini memerlukan Azure CLI versi 2.22.1 atau lebih baru. Jika menggunakan Azure Cloud Shell, versi terbaru sudah terpasang.

Untuk sampel Azure CLI untuk API lain, lihat Sampel CLI untuk Cassandra, Sampel CLI untuk API untuk MongoDB, Sampel CLI untuk Gremlin, Sampel CLI untuk Tabel

Important

Sumber daya Azure Cosmos DB tidak dapat diganti namanya karena ini melanggar cara kerja Azure Resource Manager dengan URI sumber daya.

Akun Azure Cosmos DB

Bagian berikut menunjukkan cara mengelola akun Azure Cosmos DB, termasuk:

• Membuat akun Azure Cosmos DB
• Tambah atau hapus wilayah
• Mengaktifkan penulisan multi-wilayah
• Setel prioritas failover untuk regional
• Mengaktifkan failover yang dikelola oleh layanan
• Memulai failover secara manual
• Buat daftar kunci akun
• Mencantumkan kunci akun baca-saja
• Buat daftar string koneksi
• Regenerasi kunci akun

Membuat akun Azure Cosmos DB

Buat akun Azure Cosmos DB dengan API untuk NoSQL, Konsistensi sesi di wilayah US Barat dan AS Timur:

Important

Nama akun Azure Cosmos DB harus huruf kecil dan kurang dari 44 karakter.

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

Tambah atau hapus wilayah

Buat akun Azure Cosmos DB dengan dua wilayah, tambahkan wilayah, dan hapus wilayah.

Nota

Anda tidak dapat menambahkan atau menghapus wilayah locations secara bersamaan dan mengubah properti lain untuk akun Azure Cosmos DB. Memodifikasi wilayah harus dilakukan sebagai operasi terpisah dari perubahan lain pada sumber daya akun.

Nota

Perintah ini memungkinkan Anda untuk menambah dan menghapus wilayah tetapi tidak memungkinkan Anda untuk memodifikasi prioritas failover atau memicu failover manual. Lihat Atur prioritas failover dan Picu failover manual.

Tip

Saat wilayah baru ditambahkan, semua data harus sepenuhnya direplikasi dan diterapkan ke wilayah baru sebelum wilayah ditandai sebagai tersedia. Jumlah waktu yang diperlukan operasi ini akan tergantung pada berapa banyak data yang disimpan dalam akun tersebut. Jika operasi penskalaan throughput asinkron sedang berlangsung, operasi peningkatan skala throughput akan dijeda dan akan dilanjutkan secara otomatis saat operasi penambahan/penghapusan wilayah selesai.

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

Mengaktifkan beberapa wilayah tulis

Mengaktifkan penulisan di berbagai wilayah untuk akun 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

Atur prioritas cadangan

Mengatur prioritas failover untuk akun Azure Cosmos DB yang dikonfigurasi untuk failover yang dikelola layanan

# 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'

Mengaktifkan failover yang dikelola layanan

# 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

Mengaktifkan failover manual

Caution

Mengubah wilayah dengan prioritas = 0 akan memicu failover manual untuk akun Azure Cosmos DB. Perubahan prioritas lainnya tidak akan memicu kegagalan.

Nota

Jika Anda melakukan operasi failover manual saat operasi penskalaan throughput asinkron sedang berlangsung, operasi peningkatan throughput akan dihentikan. Ini akan dilanjutkan secara otomatis ketika operasi failover selesai.

# 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'

Membuat daftar semua kunci akun

Dapatkan semua kunci untuk akun Azure Cosmos DB.

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

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

Daftar kunci akun baca-saja

Dapatkan kunci baca-saja untuk akun Azure Cosmos DB.

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

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

Buat daftar string koneksi

Dapatkan string koneksi untuk akun Azure Cosmos DB.

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

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

Regenerasi kunci akun

Regenerasi kunci baru untuk akun 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

Database Azure Cosmos DB dari Microsoft

Bagian berikut menunjukkan cara mengelola database Azure Cosmos DB, termasuk:

• Membuat database
• Membuat database dengan throughput terpadu
• Memigrasikan database ke throughput skala otomatis
• Mengubah throughput database
• Cegah database agar tidak dihapus

Membuat database

Buat database Azure Cosmos DB.

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

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

Membuat database dengan throughput yang dibagikan

Buat database Azure Cosmos DB dengan throughput bersama.

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

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

Migrasikan sebuah basis data ke penskalaan otomatis penggunaan sumber daya

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

Mengubah throughput pada database

Tingkatkan throughput dari database Azure Cosmos DB sebesar 1000 RU/s.

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

Mencegah penghapusan database

Pasang kunci penghapusan pada sumber daya Azure di sebuah database agar tidak dihapus. Fitur ini mengharuskan penguncian akun Azure Cosmos DB agar tidak diubah oleh SDK jalur data. Untuk mempelajari lebih lanjut, lihat cegah perubahan dari SDK. Kunci sumber daya Azure juga dapat mencegah sumber daya diubah dengan menentukan tipe kunci ReadOnly. Untuk database Azure Cosmos DB, database tersebut dapat digunakan untuk mencegah throughput diubah.

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

Kontainer Azure Cosmos DB

Bagian berikut menunjukkan cara mengelola akun Microsoft Azure Cosmos DB, termasuk:

• Membuat kontainer
• Buat kontainer dengan penskalaan otomatis
• Buat kontainer dengan TTL diaktifkan
• Membuat kontainer dengan kebijakan indeks kustom
• Mengubah laju kontainer
• Memigrasikan kontainer ke skala throughput otomatis
• Cegah agar kontainer tidak dihapus

Membuat kontainer

Buat kontainer Azure Cosmos DB dengan kebijakan indeks default, kunci partisi, dan 400 RU/dtk.

# 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

Buat kontainer dengan penskalaan otomatis

Buat kontainer Azure Cosmos DB dengan kebijakan indeks default, kunci partisi, dan RU/s skala otomatis 4000.

# 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

Buat kontainer dengan TTL

Buat kontainer Azure Cosmos DB dengan TTL diaktifkan.

# 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

Buat kontainer dengan kebijakan indeks kustom

Buat kontainer Azure Cosmos DB dengan kebijakan indeks kustom, indeks spasial, indeks komposit, kunci partisi, dan RU/s sebesar 400.

# 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"

Mengubah throughput kontainer

Tingkatkan throughput kontainer Azure Cosmos DB sebesar 1000 RU/detik.

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

Memigrasikan kontainer ke throughput skala otomatis

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

Cegah agar kontainer tidak dihapus

Pasang kunci penghapusan sumber daya Azure pada kontainer untuk mencegahnya dihapus. Fitur ini mengharuskan penguncian akun Azure Cosmos DB agar tidak diubah oleh SDK jalur data. Untuk mempelajari lebih lanjut, lihat cegah perubahan dari SDK. Kunci sumber daya Azure juga dapat mencegah sumber daya diubah dengan menentukan tipe kunci ReadOnly. Untuk kontainer Azure Cosmos DB, kunci dapat digunakan untuk mencegah throughput atau properti lain diubah.

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

Langkah berikutnya

Untuk informasi selengkapnya tentang Azure CLI, lihat:

• Install Azure CLI
• Referensi Azure CLI