Azure CLI를 사용하여 Azure Cosmos DB for NoSQL 리소스 관리

아티클
08/15/2024

적용 대상: NoSQL

이 문서에서는 Azure CLI를 사용하여 Azure Cosmos DB 계정, 데이터베이스 및 컨테이너 관리를 자동화하는 일반 명령에 대해 설명합니다. 모든 Azure Cosmos DB CLI 명령에 대한 참조 페이지는 Azure CLI 참조에서 제공됩니다. 더 많은 예제는 Azure Cosmos DB에 대한 Azure CLI 샘플에서 확인할 수 있습니다. 여기에는 MongoDB, Gremlin, Cassandra 및 API for Table에 대한 Azure Cosmos DB 계정, 데이터베이스 및 컨테이너 만들기 및 관리 방법이 포함되어 있습니다.

사전 요구 사항

Azure Cloud Shell에서 Bash 환경을 사용합니다. 자세한 내용은 Azure Cloud Shell의 Bash에 대한 빠른 시작을 참조하세요.
CLI 참조 명령을 로컬에서 실행하려면 Azure CLI를 설치합니다. Windows 또는 macOS에서 실행 중인 경우 Docker 컨테이너에서 Azure CLI를 실행하는 것이 좋습니다. 자세한 내용은 Docker 컨테이너에서 Azure CLI를 실행하는 방법을 참조하세요.
- 로컬 설치를 사용하는 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다. 인증 프로세스를 완료하려면 터미널에 표시되는 단계를 수행합니다. 다른 로그인 옵션은 Azure CLI를 사용하여 로그인을 참조하세요.
- 메시지가 표시되면 처음 사용할 때 Azure CLI 확장을 설치합니다. 확장에 대한 자세한 내용은 Azure CLI에서 확장 사용을 참조하세요.
- az version을 실행하여 설치된 버전과 종속 라이브러리를 찾습니다. 최신 버전으로 업그레이드하려면 az upgrade를 실행합니다.

이 문서대로 하려면 Azure CLI 버전 2.22.1 이상이 필요합니다. Azure Cloud Shell을 사용하는 경우 최신 버전이 이미 설치되어 있습니다.

다른 API에 대한 Azure CLI 샘플은 Cassandra용 CLI 샘플, API for MongoDB용 CLI 샘플, Gremlin용 CLI 샘플, Table용 CLI 샘플을 참조하세요.

Important

Azure Resource Manager가 리소스 URI와 함께 작동하는 방식을 위반하므로 Azure Cosmos DB 리소스의 이름을 바꿀 수 없습니다.

Azure Cosmos DB 계정

다음 섹션에서는 아래 작업을 포함하여 Azure Cosmos DB 계정을 관리하는 방법을 보여 줍니다.

Azure Cosmos DB 계정 만들기
영역 추가 또는 제거
다중 영역 쓰기 사용
지역 장애 조치(failover) 우선 순위 설정
서비스 관리 장애 조치(failover) 사용
수동 장애 조치(failover) 트리거
계정 키 나열
읽기 전용 계정 키 나열
연결 문자열 나열
계정 키 다시 생성

Azure Cosmos DB 계정 만들기

미국 서부 및 미국 동부 지역에서 API for NoSQL, 세션 일관성을 사용하여 Azure Cosmos DB 계정을 만듭니다.

Important

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 계정에 대한 다른 속성을 변경할 수 없습니다. 지역 수정은 계정 리소스에 대한 다른 변경 사항보다 별도의 작업으로 수행해야 합니다.

참고 항목

이 명령을 사용하면 지역을 추가 및 제거할 수 있지만 장애 조치(failover) 우선 순위를 수정하거나 수동 장애 조치(failover)를 트리거할 수 없습니다. 장애 조치(failover) 우선 순위 설정 및 수동 장애 조치(failover) 트리거를 참조하세요.

팁

새 지역이 추가되면 해당 지역이 사용 가능으로 표시되기 전에 모든 데이터를 완전히 복제하고 새 지역에 커밋해야 합니다. 이 작업에 걸리는 시간은 해당 계정 내에 저장된 데이터 양에 따라 달라집니다. 비동기 처리량 스케일링 작업이 진행 중인 경우 처리량 스케일 업 작업이 일시 중지되고 영역 추가/제거 작업이 완료되면 자동으로 다시 시작됩니다.

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

장애 조치(failover) 우선 순위 설정

서비스 관리 장애 조치(failover)를 위해 구성된 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'

서비스 관리 장애 조치(failover) 사용

# 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

수동 장애 조치(failover) 트리거

주의

우선 순위가 0인 지역을 변경하면 Azure Cosmos DB 계정에 대한 수동 장애 조치가 트리거됩니다. 다른 우선 순위 변경은 장애 조치(failover)를 트리거하지 않습니다.

참고 항목

비동기식 처리량 스케일링 작업이 진행되는 동안 수동 장애 조치 작업을 수행하면 처리량 스케일 업 작업이 일시 중지됩니다. 장애 조치 작업이 완료되면 자동으로 다시 시작됩니다.

# 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 리소스 삭제 잠금을 설정하여 삭제되지 않도록 합니다. 이 기능을 사용하려면 데이터 평면 SDK에서 Azure Cosmos DB 계정을 변경하지 못하도록 잠가야 합니다. 자세한 내용은 SDK에서 변경 방지를 참조하세요. 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 컨테이너를 관리하는 방법을 보여 줍니다.

컨테이너 만들기
자동 크기 조정을 사용하여 컨테이너 만들기
TTL이 사용하도록 설정된 컨테이너 만들기
사용자 지정 정책을 사용하여 컨테이너 만들기
컨테이너 처리량 변경
컨테이너를 자동 크기 조정 처리량으로 마이그레이션
컨테이너 삭제 방지

컨테이너 만들기

기본 인덱스 정책, 파티션 키 및 400의 RU/s를 사용하여 Azure Cosmos DB 컨테이너를 만듭니다.

# 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

자동 크기 조정을 사용하여 컨테이너 만들기

기본 인덱스 정책, 파티션 키 및 자동 스케일 4000 RU/s를 사용하여 Azure Cosmos DB 컨테이너를 만듭니다.

# 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로 컨테이너 만들기

TTL이 사용하도록 설정된 Azure Cosmos DB 컨테이너를 만듭니다.

# 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

사용자 지정 정책을 사용하여 컨테이너 만들기

사용자 지정 인덱스 정책, 공간 인덱스, 복합 인덱스, 파티션 키 및 400의 RU/s를 사용하여 Azure Cosmos DB 컨테이너를 만듭니다.

# 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 리소스 삭제 잠금을 설정하여 삭제되지 않도록 합니다. 이 기능을 사용하려면 데이터 평면 SDK에서 Azure Cosmos DB 계정을 변경하지 못하도록 잠가야 합니다. 자세한 내용은 SDK에서 변경 방지를 참조하세요. 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에 대한 자세한 내용은 다음을 참조하세요.

다음을 통해 공유

Azure CLI를 사용하여 Azure Cosmos DB for NoSQL 리소스 관리

사전 요구 사항

Azure Cosmos DB 계정

Azure Cosmos DB 계정 만들기

영역 추가 또는 제거

다중 쓰기 지역 사용

장애 조치(failover) 우선 순위 설정

서비스 관리 장애 조치(failover) 사용

수동 장애 조치(failover) 트리거

모든 계정 키 나열

읽기 전용 계정 키 나열

연결 문자열 나열

계정 키 다시 생성

Azure Cosmos DB 데이터베이스

데이터베이스 만들기

공유 처리량을 사용하여 데이터베이스 만들기

데이터베이스를 자동 크기 조정 처리량으로 마이그레이션

데이터베이스 처리량 변경

데이터베이스가 삭제되지 않도록 방지

Azure Cosmos DB 컨테이너

컨테이너 만들기

자동 크기 조정을 사용하여 컨테이너 만들기

TTL로 컨테이너 만들기

사용자 지정 정책을 사용하여 컨테이너 만들기

컨테이너 처리량 변경

컨테이너를 자동 크기 조정 처리량으로 마이그레이션

컨테이너 삭제 방지

다음 단계

피드백

추가 리소스