مشاركة عبر

إدارة Azure Cosmos DB لموارد NoSQL باستخدام Azure CLI

  • مقالة

ينطبق على: NoSQL

يصف الدليل التالي الأوامر الشائعة لأتمتة إدارة حساباتAzure Cosmos DB وقواعد البيانات والحاويات باستخدام Azure CLI. تتوفر الصفحات المرجعية لجميع أوامر Azure Cosmos DB CLI في مرجع Azure CLI. يمكنك أيضا العثور على المزيد من الأمثلة في نماذج Azure CLI ل Azure Cosmos DB، بما في ذلك كيفية إنشاء وإدارة حسابات Azure Cosmos DB وقواعد البيانات والحاويات ل MongoDB وGremlin وCassandra وواجهة برمجة التطبيقات للجدول.

المتطلبات الأساسية

  • تتطلب هذه المقالة الإصدار 2.22.1 أو إصدارًا أحدث منAzure CLI. إذا كنت تستخدم Azure Cloud Shell، يتم تثبيت أحدث إصدار بالفعل.

بالنسبة لعينات Azure CLI لواجهات برمجة التطبيقات الأخرى، راجع نماذج CLI ل Cassandra ونماذج CLI لواجهة برمجة التطبيقات ل MongoDB ونماذج CLI ل Gremlin ونماذج CLI للجدول

هام

لا يمكن إعادة تسمية موارد Azure Cosmos DB لأن هذا ينتهك كيفية عمل إدارة موارد Azure مع معرّف الموارد المنتظمة.

حسابات Azure Cosmos DB

توضح الأقسام التالية كيفية إدارة حساب Azure Cosmos DB، بما في ذلك:

إنشاء حساب Azure Cosmos DB

إنشاء حساب Azure Cosmos DB باستخدام واجهة برمجة التطبيقات ل NoSQL وتناسق الجلسة في منطقتي غرب الولايات المتحدة وشرق الولايات المتحدة:

هام

يجب أن يكون اسم حساب Azure Cosmos DB صغيرا وأقل من 44 حرفا.

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

إضافة مناطق أو إزالتها

إنشاء حساب Azure Cosmos DB مع منطقتين، وإضافة منطقة، وإزالة منطقة.

إشعار

لا يمكنك إضافة مناطق locations أو إزالتها في وقت واحد وتغيير خصائص أخرى لحساب Azure Cosmos DB. يجب إجراء تعديل المناطق كعمليات منفصلة عن أي تغيير آخر في مورد الحساب.

إشعار

يسمح لك هذا الأمر بإضافة المناطق وإزالتها ولكن لا يسمح لك بتعديل أولويات تجاوز الفشل أو تشغيل تجاوز الفشل اليدوي. يمكنك الاطلاع على تعيين أولوية تجاوز الفشل وتشغيل تجاوز الفشل اليدوي.

تلميح

عند إضافة منطقة جديدة، يجب نسخ جميع البيانات بالكامل وتثبيتها في المنطقة الجديدة قبل وضع علامة على المنطقة على أنها متوفرة. يعتمد مقدار الوقت الذي تستغرقه هذه العملية على مقدار البيانات المخزنة داخل الحساب. إذا كانت هناك عملية تحجيم معدل النقل غير المتزامن قيد التقدم، فستقف عملية زيادة معدلات النقل مؤقتاً وستُستأنف تلقائياً عند اكتمال عملية إضافة / إزالة المنطقة.

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

تمكين مناطق الكتابة المتعددة

تمكين عمليات الكتابة متعددة المناطق لحساب 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

تعيين أولوية تجاوز الفشل

تعيين أولوية تجاوز الفشل لحساب Azure Cosmos DB الذي تم تكوينه لتجاوز الفشل المدار بواسطة الخدمة

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

تمكين تجاوز الفشل المُدار بواسطة الخدمة

# 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

تشغيل تجاوز الفشل اليدوي

تنبيه

سيؤدي تغيير المنطقة ذات الأولوية = 0 إلى تشغيل تجاوز فشل يدوي لحساب Azure Cosmos DB. لن يؤدي أي تغيير آخر في الأولوية إلى حدوث تجاوز للفشل.

إشعار

إذا أجريت عملية تجاوز الفشل اليدوي أثناء عملية تحجيم سرعة نقل غير متزامنة قيد التقدم، فستقف عملية زيادة معدلات النقل مؤقتاً. سيتم استئنافها تلقائياً عند اكتمال عملية تجاوز الفشل.

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

سرد كافة مفاتيح الحساب

احصل على جميع المفاتيح لحساب Azure Cosmos DB.

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

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

سرد مفاتيح الحساب للقراءة فقط

احصل على مفاتيح للقراءة فقط لحساب Azure Cosmos DB.

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

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

سرد سلاسل الاتصال

احصل على سلسلة الاتصال لحساب Azure Cosmos DB.

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

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

إعادة تجديد مفاتيح الحساب

إعادة إنشاء مفتاح جديد لحساب 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

قاعدة بيانات Azure Cosmos DB

توضح المقاطع التالية كيفية إدارة قاعدة بيانات Azure Cosmos DB، بما في ذلك:

إنشاء قاعدة بيانات

إنشاء قاعدة بيانات في Azure Cosmos DB.

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

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

بناء قاعدة بيانات مع معدل نقل مشترك

إنشاء قاعدة بيانات Azure Cosmos DB مع معدل النقل المشترك.

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

az cosmosdb sql database create \
    -a $accountName \
    -g $resourceGroupName \
    -n $databaseName \
    --throughput $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

تغيير معدل نقل قاعدة البيانات

زيادة معدل نقل قاعدة بيانات Azure Cosmos DB بمقدار 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

منع حذف قاعدة بيانات

وضع تأمين حذف مورد Azure على قاعدة بيانات لمنع حذفه. تتطلب هذه الميزة تأمين حساب Azure Cosmos DB من التغيير بواسطة SDKs لمستوى البيانات. لمعرفة المزيد راجع، منع التغييرات من SDKs. يمكن أيضا أن يمنع تأمين مورد Azure مورد من التغيير عن طريق تحديد ReadOnly نوع تأمين. بالنسبة لقاعدة بيانات Azure Cosmos DB، يمكن استخدامها لمنع تغيير معدل النقل.

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

توضح المقاطع التالية كيفية إدارة حاوية Azure Cosmos DB، بما في ذلك:

إنشاء حاوية

إنشاء حاوية Azure Cosmos DB مع نهج الفهرس الافتراضي ومفتاح القسم و RU/s من 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

أنشاء حاوية ذات تحجيم تلقائي

إنشاء حاوية Azure Cosmos DB مع نهج الفهرس الافتراضي ومفتاح القسم و RU/s للتحجيم التلقائي من 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

إنشاء حاوية مع تمكين TTL

إنشاء حاوية Azure Cosmos DB مع تمكين TTL.

# 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

إنشاء حاوية بسياسة الفهرس المخصص

إنشاء حاوية Azure Cosmos DB مع نهج فهرس مخصص، فهرس مكاني، فهرس مركب، مفتاح قسم و RU/s من 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"

تغيير معدل نقل الحاوية

زيادة معدل نقل حاوية Azure Cosmos DB بمقدار 1000 RU/s.

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

ترحيل حاوية إلى معدل نقل بتحجيم تلقائي

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

منع حذف حاوية

وضع تأمين حذف مورد Azure على حاوية لمنع حذفه. تتطلب هذه الميزة تأمين حساب Azure Cosmos DB من التغيير بواسطة SDKs لمستوى البيانات. لمعرفة المزيد راجع، منع التغييرات من SDKs. يمكن أيضا أن يمنع تأمين مورد Azure مورد من التغيير عن طريق تحديد ReadOnly نوع تأمين. بالنسبة لحاوية Azure Cosmos DB، يمكن استخدام الأقفال لمنع تغيير معدل النقل أو أي خاصية أخرى.

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

الخطوات التالية

لمزيد من المعلومات حول Azure CLI، راجع: