Aracılığıyla paylaş

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ına ait başvuru sayfalarına Azure CLI Başvurusu sayfasından erişilebilir. Ayrıca Azure Cosmos DB için Azure CLI örneklerinde MongoDB, Gremlin, Cassandra ve Tablo için API için Azure Cosmos DB hesaplarını, veritabanlarını ve kapsayıcılarını oluşturma ve yönetme gibi daha fazla örnek bulabilirsiniz.

Önkoşullar

  • Azure Cloud Shell'de Bash ortamını kullanın. Daha fazla bilgi için bkz . Azure Cloud Shell'de Bash için hızlı başlangıç.

  • CLI başvuru komutlarını yerel olarak çalıştırmayı tercih ediyorsanız Azure CLI'yı yükleyin . Windows veya macOS üzerinde çalışıyorsanız Azure CLI’yi bir Docker kapsayıcısında çalıştırmayı değerlendirin. Daha fazla bilgi için bkz . Docker kapsayıcısında Azure CLI'yi çalıştırma.

    • Yerel yükleme kullanıyorsanız az login komutunu kullanarak Azure CLI ile oturum açın. Kimlik doğrulama işlemini tamamlamak için terminalinizde görüntülenen adımları izleyin. Diğer oturum açma seçenekleri için bkz . Azure CLI ile oturum açma.

    • İstendiğinde, ilk kullanımda Azure CLI uzantısını yükleyin. Uzantılar hakkında daha fazla bilgi için bkz. Azure CLI ile uzantıları kullanma.

    • Yüklü sürümü ve bağımlı kitaplıkları bulmak için az version komutunu çalıştırın. En son sürüme yükseltmek için az upgrade komutunu çalıştırın.

  • 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 Resource Manager'ın kaynak URI'leriyle çalışma biçimini ihlal eden Azure Cosmos DB kaynakları yeniden adlandırılamaz.

Azure Cosmos DBAccounts

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

Azure Cosmos DB hesabı oluşturma

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

Önemli

Azure Cosmos DB hesap adı küçük 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ının bölgelerini locations aynı anda ekleyemez veya kaldıramaz ve diğer özelliklerini 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 süresi, 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ının 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

Liste bağlantı dizesi

Azure Cosmos DB hesabı için bağlantı dizesi 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şturun.

# 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ğinin nasıl yönetileceğinin gösterildiği gibi:

veritabanı oluşturun

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ıyla 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 kaynağı 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şiklikleri engelleme. Azure kaynak kilitleri, bir kilit türü belirterek ReadOnly bir 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östermektedir:

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 etkinleştirilmiş 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 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

# 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

Kapsayıcının silinmesini önlemek için bir Azure kaynak silme kilidi koyun. 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şiklikleri engelleme. Azure kaynak kilitleri, bir kilit türü belirterek ReadOnly bir kaynağın değiştirilmesini de engelleyebilir. Azure Cosmos DB kapsayıcısı için aktarım hızının veya diğer özelliklerin 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: