Azure CLI kullanarak NoSQL için Azure Cosmos DB kaynaklarını yönetme

  • Makale

UYGULANANLAR: NOSQL

Aşağıdaki kılavuzda Azure Cosmos DB hesaplarınız, veritabanlarınız ve kapsayıcılarınızı yönetme işleminin Azure CLI kullanılarak otomatikleştirilmesini sağlayan yaygın komutlar açıklanır. Tüm Azure Cosmos DB CLI komutlarının başvuru sayfaları Azure CLI Başvurusu'nda sağlanır. Ayrıca Azure Cosmos DB için Azure CLI örneklerinde MongoDB, Gremlin, Cassandra ve Tablo için API için Azure Cosmos DB hesapları, veritabanları ve kapsayıcıları oluşturma ve yönetme gibi daha fazla örnek bulabilirsiniz.

Önkoşullar

  • Bu makale, Azure CLI'nın 2.22.1 veya sonraki bir sürümünü gerektirir. Azure Cloud Shell kullanılıyorsa en son sürüm zaten yüklüdür.

Diğer API'ler için Azure CLI örnekleri için bkz. Cassandra için CLI Örnekleri, MongoDB IÇIN API IÇIN CLI Örnekleri, Gremlin için CLI Örnekleri, Tablo için CLI Örnekleri

Önemli

Azure Cosmos DB kaynakları yeniden adlandırılamaz, bu durum Azure Resource Manager kaynak URI'leriyle çalışma biçimini ihlal eder.

Azure Cosmos DBAccounts

Aşağıdaki bölümlerde Azure Cosmos DB hesabının nasıl yönetileceğini gösterilmektedir:

Azure Cosmos DB hesabı oluşturma

Batı ABD ve Doğu ABD bölgelerinde NoSQL, Oturum tutarlılığı için API ile bir Azure Cosmos DB hesabı oluşturun:

Önemli

Azure Cosmos DB hesap adı küçük harfli ve 44 karakterden kısa olmalıdır.

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

Bölge ekleme veya kaldırma

İki bölge içeren bir Azure Cosmos DB hesabı oluşturun, bölge ekleyin ve bir bölgeyi kaldırın.

Not

Azure Cosmos DB hesabı için aynı anda bölge locations ekleyemez veya kaldıramaz ve diğer özellikleri değiştiremezsiniz. Bölgelerin değiştirilmesi, hesap kaynağında yapılan diğer değişikliklerden ayrı bir işlem olarak gerçekleştirilmelidir.

Not

Bu komut bölgeleri eklemenizi ve kaldırmanızı sağlar, ancak yük devretme önceliklerini değiştirmenize veya el ile yük devretme tetiklemenize izin vermez. Bkz . Yük devretme önceliğini ayarlama ve El ile yük devretmeyi tetikleme.

İpucu

Yeni bölge eklendiğinde, bölge kullanılabilir olarak işaretlenmeden önce tüm verilerin tamamen çoğaltılması ve yeni bölgeye işlenmesi gerekir. Bu işlemin ne kadar süreceği, hesapta ne kadar veri depolandığına bağlıdır. Zaman uyumsuz bir aktarım hızı ölçeklendirme işlemi devam ederse, aktarım hızı ölçeği artırma işlemi duraklatılır ve bölge ekleme/kaldırma işlemi tamamlandığında otomatik olarak sürdürülür.

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

Birden çok yazma bölgesini etkinleştirme

Azure Cosmos DB hesabı için çok bölgeli yazmaları etkinleştirme

# 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

Yük devretme önceliğini ayarlama

Hizmet tarafından yönetilen yük devretme için yapılandırılmış bir Azure Cosmos DB hesabı için yük devretme önceliğini ayarlama

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

Hizmet tarafından yönetilen yük devretmeyi etkinleştirme

# 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

El ile yük devretmeyi tetikleme

Dikkat

Öncelik = 0 olan bölgenin değiştirilmesi, Azure Cosmos DB hesabı için el ile yük devretmeyi tetikler. Diğer öncelik değişiklikleri yük devretmeyi tetiklemez.

Not

Zaman uyumsuz aktarım hızı ölçeklendirme işlemi devam ederken el ile yük devretme işlemi gerçekleştirirseniz, aktarım hızı ölçeği artırma işlemi duraklatılır. Yük devretme işlemi tamamlandığında otomatik olarak sürdürülür.

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

Tüm hesap anahtarlarını listeleme

Azure Cosmos DB hesabının tüm anahtarlarını alın.

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

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

Salt okunur hesap anahtarlarını listeleme

Azure Cosmos DB hesabı için salt okunur anahtarlar alın.

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

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

Bağlantı dizelerini listeleme

Azure Cosmos DB hesabı için bağlantı dizelerini alın.

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

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

Hesap anahtarını yeniden oluşturma

Azure Cosmos DB hesabı için yeni bir anahtar oluşturma.

# 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 veritabanı

Aşağıdaki bölümlerde Azure Cosmos DB veritabanının nasıl yönetileceğini gösterilmektedir:

Veritabanı oluşturma

Azure Cosmos DB veritabanı oluşturun.

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

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

Paylaşılan aktarım hızına sahip bir veritabanı oluşturma

Paylaşılan aktarım hızına sahip bir Azure Cosmos DB veritabanı oluşturun.

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

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

Veritabanını otomatik ölçeklendirme aktarım hızına geçirme

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

Veritabanı aktarım hızını değiştirme

Azure Cosmos DB veritabanının aktarım hızını 1000 RU/sn artırın.

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

Veritabanının silinmesini engelleme

Veritabanının silinmesini önlemek için bir Azure kaynak silme kilidi yerleştirin. Bu özellik, Azure Cosmos DB hesabının veri düzlemi SDK'ları tarafından değiştirilmesini kilitlemeyi gerektirir. Daha fazla bilgi edinmek için bkz. SDK'lardan değişiklik yapılmasını engelleme. Azure kaynak kilitleri, bir kilit türü belirterek ReadOnly kaynağın değiştirilmesini de engelleyebilir. Azure Cosmos DB veritabanı için aktarım hızının değiştirilmesini önlemek için kullanılabilir.

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 kapsayıcısı

Aşağıdaki bölümlerde Azure Cosmos DB kapsayıcısının nasıl yönetileceğini gösterilmektedir:

Kapsayıcı oluşturma

Varsayılan dizin ilkesi, bölüm anahtarı ve RU/sn değeri 400 olan bir Azure Cosmos DB kapsayıcısı oluşturun.

# 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

Otomatik ölçeklendirme ile kapsayıcı oluşturma

Varsayılan dizin ilkesi, bölüm anahtarı ve otomatik ölçeklendirme RU/sn değeri 4000 olan bir Azure Cosmos DB kapsayıcısı oluşturun.

# 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 ile kapsayıcı oluşturma

TTL etkin bir Azure Cosmos DB kapsayıcısı oluşturun.

# 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

Özel dizin ilkesiyle kapsayıcı oluşturma

Özel dizin ilkesi, uzamsal dizin, bileşik dizin, bölüm anahtarı ve 400 RU/sn içeren bir Azure Cosmos DB kapsayıcısı oluşturun.

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

Kapsayıcı aktarım hızını değiştirme

Azure Cosmos DB kapsayıcısının aktarım hızını 1000 RU/sn artırın.

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

Kapsayıcıyı otomatik ölçeklendirme aktarım hızına geçirme

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

Kapsayıcının silinmesini engelleme

Bir kapsayıcının silinmesini önlemek için bir Azure kaynak silme kilidi yerleştirin. Bu özellik, Azure Cosmos DB hesabının veri düzlemi SDK'ları tarafından değiştirilmesini kilitlemeyi gerektirir. Daha fazla bilgi edinmek için bkz. SDK'lardan değişiklik yapılmasını engelleme. Azure kaynak kilitleri, bir kilit türü belirterek ReadOnly kaynağın değiştirilmesini de engelleyebilir. Azure Cosmos DB kapsayıcısı için aktarım hızının veya başka bir özelliğin değiştirilmesini önlemek için kilitler kullanılabilir.

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

Sonraki adımlar

Azure CLI hakkında daha fazla bilgi için bkz: