Mengelola Azure Cosmos DB untuk sumber daya NoSQL menggunakan Azure CLI

BERLAKU UNTUK: NoSQL

Panduan berikut ini menjelaskan perintah umum untuk mengotomatiskan manajemen akun, database, dan wadah Azure Cosmos DB Anda menggunakan Azure CLI. Halaman referensi untuk semua perintah CLI Azure Cosmos DB tersedia di Referensi CLI Azure. Anda juga dapat menemukan lebih banyak contoh dalam sampel Azure CLI untuk Azure Cosmos DB, termasuk cara membuat dan mengelola akun, database, dan kontainer Azure Cosmos DB untuk MongoDB, Gremlin, Cassandra, dan API for Table.

Prasyarat

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

  

• Jika Anda lebih memilih untuk menjalankan perintah referensi CLI secara lokal, pasang 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 login az. Untuk menyelesaikan proses autentikasi, ikuti langkah-langkah yang ditampilkan di terminal Anda. Untuk opsi masuk lainnya, lihat Masuk dengan Azure CLI.

  • Saat Anda diminta, instal ekstensi Azure CLI pada penggunaan pertama. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan ekstensi dengan Azure CLI.

  • Jalankan versi az untuk menemukan versi dan pustaka dependen yang diinstal. Untuk meningkatkan ke versi terbaru, jalankan peningkatan az.

• 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

Penting

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

Azure Cosmos DBAccounts

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

• Membuat akun Azure Cosmos DB
• Tambah atau hapus wilayah
• Aktifkan penulisan multiwilayah
• Atur prioritas failover wilayah
• Mengaktifkan failover yang Dikelola Layanan
• Picu failover manual
• Buat daftar kunci akun
• Buat daftar kunci akun baca-saja
• Buat daftar string koneksi
• Regenerasi kunci akun

Buat akun Azure Cosmos DB

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

Penting

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.

Catatan

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.

Catatan

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

Aktifkan beberapa wilayah tulis

Mengaktifkan penulisan multi-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 failover

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

Picu failover manual

Perhatian

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

Catatan

Jika Anda melakukan operasi failover manual saat operasi penskalaan throughput asinkron sedang berlangsung, operasi peningkatan throughput akan dijeda. Operasi 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

Cantumkan 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

Bagian berikut menunjukkan cara mengelola akun Azure Cosmos, termasuk:

• Buat database
• Buat database dengan throughput bersama
• Migrasikan database ke autoscale throughput
• Ubah throughput database
• Cegah database dihapus

Buat database

Membuat database Azure Cosmos DB.

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

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

Buat database dengan throughput bersama

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 database ke autoscale 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

Ubah throughput database

Tingkatkan throughput database Azure Cosmos DB sebesar 1000 RU/dtk.

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

Cegah database dihapus

Kunci penghapusan sumber daya Azure pada database untuk mencegahnya dihapus. Fitur ini mengharuskan penguncian akun Azure Cosmos DB agar tidak diubah oleh SDK sarana 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 Azure Cosmos, termasuk:

• Buat kontainer
• Buat kontainer dengan autoscale
• Buat kontainer dengan TTL diaktifkan
• Buat kontainer dengan kebijakan indeks kustom
• Ubah throughput kontainer
• Migrasikan kontainer ke autoscale throughput
• Cegah agar kontainer tidak dihapus

Buat kontainer

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

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

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/dtk 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"

Ubah throughput kontainer

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

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

Migrasikan kontainer ke autoscale throughput

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

Kunci penghapusan sumber daya Azure pada database untuk mencegahnya dihapus. Fitur ini mengharuskan penguncian akun Azure Cosmos DB agar tidak diubah oleh SDK sarana 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:

• Menginstal Azure CLI
• Referensi Azure CLI
• Sampel Azure CLI lainnya untuk Azure Cosmos DB