Azure CLI kullanarak Azure Cosmos Core (SQL) API kaynaklarını yönetme

  • Makale
  • Okumak için 9 dakika

ŞUNLAR IÇIN GEÇERLIDIR: SQL API

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. Azure Cosmos DB için Azure CLI örneklerinde MongoDB, Gremlin, Cassandra ve Tablo API'si için Cosmos DB hesaplarını, veritabanlarını ve kapsayıcılarını oluşturma ve yönetme gibi daha fazla örnek de 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 API için CLI Örnekleri, Gremlin için CLI Örnekleri, Tablo için CLI Örnekleri

Önemli

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

Azure Cosmos Hesapları

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

Azure Cosmos DB hesabı oluşturma

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

Önemli

Azure Cosmos 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 hesabı oluşturun, bölge ekleyin ve bir bölgeyi kaldırın.

Not

Azure Cosmos 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ğındaki 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 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

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

# Update an Azure Cosmos 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 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 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

Cosmos hesabı için tüm anahtarları alın.

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

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

Salt okunur hesap anahtarlarını listeleme

Cosmos 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

Cosmos 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

Cosmos 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ğini gösterilmektedir:

Veritabanı oluşturma

Cosmos veritabanı oluşturma.

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 Cosmos 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

Cosmos 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 cosmos 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 kaynağın değiştirilmesini de engelleyebilir. Cosmos 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 Cosmos kapsayıcısı oluşturun.

# Create a SQL API 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 Cosmos kapsayıcısı oluşturun.

# Create a SQL API 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 Cosmos kapsayıcısı oluşturun.

# Create an Azure Cosmos 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 Cosmos kapsayıcısı oluşturun.

# Create a SQL API 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

Cosmos 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 kaynağı silme kilidi koyun. Bu özellik cosmos 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 kaynağın değiştirilmesini de engelleyebilir. Cosmos kapsayıcısı için bu, aktarım hızının veya başka bir özelliğin değiştirilmesini önlemek için 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: