Azure Cosmos アカウントを管理するManage an Azure Cosmos account

この記事では、Azure portal、Azure PowerShell、Azure CLI、Azure Resource Manager テンプレートを使用し、Azure Cosmos アカウントでさまざまなタスクを管理する方法を紹介します。This article describes how to manage various tasks on an Azure Cosmos account using the Azure portal, Azure PowerShell, Azure CLI, and Azure Resource Manager templates.

アカウントの作成Create an account

Azure PortalAzure portal

  1. Azure Portal にサインインします。Sign in to the Azure portal.

  2. [リソースの作成] > [データベース] > [Azure Cosmos DB] を選択します。Select Create a resource > Databases > Azure Cosmos DB.

    Azure Portal の [データベース] ウィンドウ

  3. [Azure Cosmos DB アカウントの作成] ページで、新しい Azure Cosmos アカウントの基本的な設定を入力します。On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    SettingSetting Value 説明Description
    サブスクリプションSubscription サブスクリプション名Subscription name この Azure Cosmos アカウントに使用する Azure サブスクリプションを選択します。Select the Azure subscription that you want to use for this Azure Cosmos account.
    リソース グループResource Group リソース グループ名Resource group name リソース グループを選択するか、 [新規作成] を選択し、新しいリソース グループの一意の名前を入力します。Select a resource group, or select Create new, then enter a unique name for the new resource group.
    アカウント名Account Name 一意の名前を入力しますEnter a unique name 自分の Azure Cosmos アカウントを識別するための名前を入力します。Enter a name to identify your Azure Cosmos account. 指定した ID に documents.azure.com が付加されて URI が作成されるので、一意の ID を使用してください。Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    ID に含めることができるのは、英小文字、数字、ハイフン (-) のみです。The ID can only contain lowercase letters, numbers, and the hyphen (-) character. 長さは 3 文字から 31 文字でなければなりません。It must be between 3-31 characters in length.
    APIAPI コア (SQL)Core (SQL) API によって、作成するアカウントの種類が決まります。The API determines the type of account to create. Azure Cosmos DB には、5 種類の API が用意されています。ドキュメント データ用のコア (SQL) と MongoDB、グラフ データ用の Gremlin、Azure Table、Cassandra です。Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. 現在は、API ごとに別のアカウントを作成する必要があります。Currently, you must create a separate account for each API.

    ドキュメント データベースを作成し、SQL 構文を使用してクエリを実行するには、 [コア (SQL)] を選択します。Select Core (SQL) to create a document database and query by using SQL syntax.

    SQL API について詳しくは、こちらをご覧くださいLearn more about the SQL API.
    LocationLocation ユーザーに最も近いリージョンを選択Select the region closest to your users Azure Cosmos DB アカウントをホストする地理的な場所を選択します。Select a geographic location to host your Azure Cosmos DB account. データに最も高速にアクセスできるよう、お客様のユーザーに最も近い場所を使用します。Use the location that is closest to your users to give them the fastest access to the data.

    Azure Cosmos DB の新しいアカウント ページ

  4. [Review + create](レビュー + 作成) を選択します。Select Review + create. [ネットワーク] セクションと [タグ] セクションはスキップできます。You can skip the Network and Tags sections.

  5. アカウントの設定を確認し、 [作成] を選択します。Review the account settings, and then select Create. アカウントの作成には数分かかります。It takes a few minutes to create the account. ポータル ページに "デプロイが完了しました" と表示されるまで待ちます。Wait for the portal page to display Your deployment is complete.

    Azure Portal の [通知] ウィンドウ

  6. [リソースに移動] を選択し、Azure Cosmos DB アカウント ページに移動します。Select Go to resource to go to the Azure Cosmos DB account page.

    Azure Cosmos DB アカウント ページ

Azure CLIAzure CLI

# Create an account
$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname' # must be lower case.

az cosmosdb create \
   --name $accountName \
   --resource-group $resourceGroupName \
   --kind GlobalDocumentDB \
   --default-consistency-level Session \
   --locations regionName=WestUS failoverPriority=0 isZoneRedundant=False \
   --locations regionName=EastUS failoverPriority=1 isZoneRedundant=False \
   --enable-multiple-write-locations true

Azure PowerShellAzure PowerShell

# Create an Azure Cosmos account for Core (SQL) API
$resourceGroupName = "myResourceGroup"
$location = "West US"
$accountName = "mycosmosaccount" # must be lower case.

$locations = @(
    @{ "locationName"="West US"; "failoverPriority"=0 },
    @{ "locationName"="East US"; "failoverPriority"=1 }
)

$consistencyPolicy = @{
    "defaultConsistencyLevel"="BoundedStaleness";
    "maxIntervalInSeconds"=300;
    "maxStalenessPrefix"=100000
}

$CosmosDBProperties = @{
    "databaseAccountOfferType"="Standard";
    "locations"=$locations;
    "consistencyPolicy"=$consistencyPolicy;
    "enableMultipleWriteLocations"="true"
}

New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName -Location $location `
    -Name $accountName -PropertyObject $CosmosDBProperties

Azure Resource Manager テンプレートAzure Resource Manager template

この Azure Resource Manager テンプレートでは、2 つのリージョンと、整合性レベル、自動フェールオーバー、およびマルチマスターを選択するオプションで構成された、サポート対象の任意の API に対する Azure Cosmos アカウントが作成されます。This Azure Resource Manager template will create an Azure Cosmos account for any supported API configured with two regions and options to select consistency level, automatic failover, and multi-master. このテンプレートをデプロイするには、Azure Cosmos アカウントの作成に関する readme ページで [Deploy to Azure](Azure に配置する) をクリックします。To deploy this template, click on Deploy to Azure on the readme page, Create Azure Cosmos account

データベース アカウントのリージョンの追加/削除Add/remove regions from your database account

Azure PortalAzure portal

  1. Azure ポータルにサインインします。Sign in to Azure portal.

  2. お使いの Azure Cosmos アカウントに移動して、 [データをグローバルにレプリケートする] メニューを開きます。Go to your Azure Cosmos account, and open the Replicate data globally menu.

  3. リージョンを追加するには、目的のリージョンに対応する六角形 ( + ラベルが付いたもの) をマップ上で選択します。To add regions, select the hexagons on the map with the + label that corresponds to your desired region(s). 別の方法でリージョンを追加するには、 [+ リージョンの追加] オプションを選択し、ドロップダウン メニューからリージョンを選択します。Alternatively, to add a region, select the + Add region option and choose a region from the drop-down menu.

  4. リージョンを削除するには、チェック マークの付いた青い六角形をマップ上で選択して、1 つ以上のリージョンを消去します。To remove regions, clear one or more regions from the map by selecting the blue hexagons with check marks. または、右側で、リージョンの横にある "ごみ箱" (🗑) アイコンを選択します。Or select the "wastebasket" (🗑) icon next to the region on the right side.

  5. 変更を保存するには、 [OK] を選択します。To save your changes, select OK.

    リージョンの追加や削除を行うメニュー

単一リージョン書き込みモードでは、書き込みリージョンを削除できません。In a single-region write mode, you cannot remove the write region. その現在の書き込みリージョンを削除する前に、別のリージョンへのフェールオーバーを行う必要があります。You must fail over to a different region before you can delete the current write region.

複数リージョン書き込みモードでは、少なくとも 1 つのリージョンがあれば、どのリージョンも追加または削除できます。In a multi-region write mode, you can add or remove any region, if you have at least one region.

Azure CLIAzure CLI

$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname'

# Create an account with 1 region
az cosmosdb create --name $accountName --resource-group $resourceGroupName --locations regionName=westus failoverPriority=0 isZoneRedundant=False

# Add a region
az cosmosdb update --name $accountName --resource-group $resourceGroupName --locations regionName=westus failoverPriority=0 isZoneRedundant=False --locations regionName=EastUS failoverPriority=1 isZoneRedundant=False

# Remove a region
az cosmosdb update --name $accountName --resource-group $resourceGroupName --locations regionName=westus failoverPriority=0 isZoneRedundant=False

Azure PowerShellAzure PowerShell

# Create an account with 1 region
$resourceGroupName = "myResourceGroup"
$location = "West US"
$accountName = "mycosmosaccount" # must be lower case.

$locations = @( @{ "locationName"="West US"; "failoverPriority"=0 } )
$consistencyPolicy = @{ "defaultConsistencyLevel"="Session" }
$CosmosDBProperties = @{
    "databaseAccountOfferType"="Standard";
    "locations"=$locations;
    "consistencyPolicy"=$consistencyPolicy
}
New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName -Location $location `
    -Name $accountName -PropertyObject $CosmosDBProperties

# Add a region
$account = Get-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName -Name $accountName

$locations = @( 
    @{ "locationName"="West US"; "failoverPriority"=0 },
    @{ "locationName"="East Us"; "failoverPriority"=1 } 
)

$account.Properties.locations = $locations
$CosmosDBProperties = $account.Properties

Set-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

# Azure Resource Manager does not wait on the resource update
Write-Host "Confirm region added before continuing..."

# Remove a region
$account = Get-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName -Name $accountName

$locations = @( @{ "locationName"="West US"; "failoverPriority"=0 } )

$account.Properties.locations = $locations
$CosmosDBProperties = $account.Properties

Set-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

複数の書き込みリージョンの構成Configure multiple write-regions

Azure PortalAzure portal

[データをグローバルにレプリケートする] タブを開き、 [有効] を選択して複数リージョンの書き込みを有効にします。Open the Replicate Data Globally tab and select Enable to enable multi-region writes. 複数リージョンの書き込みを有効にすると、アカウントで現在用意されているすべての読み取りリージョンが読み書きリージョンになります。After you enable multi-region writes, all the read regions that you currently have on the account will become read and write regions.

注意

複数リージョンの書き込みを有効にした後、無効にすることはできません。After you enable multi-region writes, you cannot disable it.

Azure Cosmos アカウントのマルチマスター構成のスクリーンショット

この機能に関して他に質問がございましたら、askcosmosdb@microsoft.com エイリアスにご連絡ください。Please reach out to the askcosmosdb@microsoft.com alias for additional questions about this feature.

Azure CLIAzure CLI

$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname'
az cosmosdb update --name $accountName --resource-group $resourceGroupName --enable-multiple-write-locations true

Azure PowerShellAzure PowerShell

# Update an Azure Cosmos account from single to multi-master

$account = Get-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName -Name $accountName

$account.Properties.enableMultipleWriteLocations = "true"
$CosmosDBProperties = $account.Properties

Set-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

Resource Manager テンプレートResource Manager template

アカウントと設定 enableMultipleWriteLocations: true の作成に使用された Resource Manager テンプレートをデプロイすることで、アカウントをシングルマスターからマルチマスターに移行できます。An account can be migrated from single-master to multi-master by deploying the Resource Manager template used to create the account and setting enableMultipleWriteLocations: true. 次の Azure Resource Manager テンプレートは飾りのない最小限のテンプレートであり、SQL API 用に Azure Cosmos アカウントをデプロイし、1 つのリージョンとマルチマスターを有効にします。The following Azure Resource Manager template is a bare minimum template that will deploy an Azure Cosmos account for SQL API with a single region and multi-master enabled.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "name": {
            "type": "String"
        },
        "location": {
            "type": "String",
            "defaultValue": "[resourceGroup().location]"
        }
    },
    "resources": [
        {
            "type": "Microsoft.DocumentDb/databaseAccounts",
            "kind": "GlobalDocumentDB",
            "name": "[parameters('name')]",
            "apiVersion": "2015-04-08",
            "location": "[parameters('location')]",
            "tags": {},
            "properties": {
                "databaseAccountOfferType": "Standard",
                "consistencyPolicy": { "defaultConsistencyLevel": "Session" },
                "locations": [
                    {
                        "locationName": "[parameters('location')]",
                        "failoverPriority": 0
                    }
                ],
                "enableMultipleWriteLocations": true
            }
        }
    ]
}

Azure Cosmos アカウントでの自動フェールオーバーの有効化Enable automatic failover for your Azure Cosmos account

自動フェールオーバーを選択すると、あるリージョンが利用できなくなったとき、フェールオーバーの優先順位が最も高いリージョンに Azure Cosmos DB がフェールオーバーされます。ユーザー側の操作は必要ありません。The Automatic failover option allows Azure Cosmos DB to failover to the region with the highest failover priority with no user action should a region become unavailable. 自動フェールオーバーが有効になっているとき、リージョン優先順位を変更できます。When automatic failover is enabled, region priority can be modified. 自動フェールオーバーを有効にするには、アカウントに 2 つ以上のリージョンを用意する必要があります。Account must have two or more regions to enable automatic failover.

Azure PortalAzure portal

  1. お使いの Azure Cosmos アカウントで、 [データをグローバルにレプリケートする] ウィンドウを開きます。From your Azure Cosmos account, open the Replicate data globally pane.

  2. ウィンドウの上部で、 [自動フェールオーバー] を選択します。At the top of the pane, select Automatic Failover.

    [データをグローバルにレプリケートする] メニュー

  3. [自動フェールオーバー] ウィンドウで、 [自動フェールオーバーの有効化][ON] に設定してください。On the Automatic Failover pane, make sure that Enable Automatic Failover is set to ON.

  4. [保存] を選択します。Select Save.

    自動フェールオーバーのポータル メニュー

Azure CLIAzure CLI

# Enable automatic failover on an existing account
$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname'

az cosmosdb update --name $accountName --resource-group $resourceGroupName --enable-automatic-failover true

Azure PowerShellAzure PowerShell

$resourceGroupName = "myResourceGroup"
$accountName = "mycosmosaccount"

$account = Get-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName

$account.Properties.enableAutomaticFailover="true";
$CosmosDBProperties = $account.Properties;

Set-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

Azure Cosmos アカウントでのフェールオーバーの優先度の設定Set failover priorities for your Azure Cosmos account

Cosmos アカウントに自動フェールオーバーを構成した後、リージョンのフェールオーバーの優先順位を変更できます。After a Cosmos account is configured for automatic failover, the failover priority for regions can be changed.

重要

アカウントに自動フェールオーバーを構成しているとき、書き込みリージョン (フェールオーバーの優先順位がゼロ) は変更できません。You cannot modify the write region (failover priority of zero) when the account is configured for automatic failover. 書き込みリージョンを変更するには、自動フェールオーバーを無効にし、手動フェールオーバーを実行する必要があります。To change the write region, you must disable automatic failover and do a manual failover.

Azure PortalAzure portal

  1. お使いの Azure Cosmos アカウントで、 [データをグローバルにレプリケートする] ウィンドウを開きます。From your Azure Cosmos account, open the Replicate data globally pane.

  2. ウィンドウの上部で、 [自動フェールオーバー] を選択します。At the top of the pane, select Automatic Failover.

    [データをグローバルにレプリケートする] メニュー

  3. [自動フェールオーバー] ウィンドウで、 [自動フェールオーバーの有効化][ON] に設定してください。On the Automatic Failover pane, make sure that Enable Automatic Failover is set to ON.

  4. フェールオーバーの優先度を変更するには、カーソルを置くと行の左側に表示される 3 つのドットを使い、読み込みリージョンをドラッグします。To modify the failover priority, drag the read regions via the three dots on the left side of the row that appear when you hover over them.

  5. [保存] を選択します。Select Save.

    自動フェールオーバーのポータル メニュー

Azure CLIAzure CLI

# Assume region order is initially eastus=0 westus=1 southeastasia=2 on account creation
$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname'

az cosmosdb failover-priority-change --name $accountName --resource-group $resourceGroupName --failover-policies eastus=0 southeastasia=1 westus=2

Azure PowerShellAzure PowerShell

# Assume account currently has regions with priority: West US = 0, East US = 1, Southeast Asia = 2
$resourceGroupName = "myResourceGroup"
$accountName = "myaccountname"

$failoverPolicies = @(
    @{ "locationName"="West US"; "failoverPriority"=0 },
    @{ "locationName"="Southeast Asia"; "failoverPriority"=1 },
    @{ "locationName"="East US"; "failoverPriority"=2 }
)

Invoke-AzResourceAction -Action failoverPriorityChange `
    -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" `
    -ResourceGroupName $resourceGroupName -Name $accountName -Parameters $failoverPolicies

Azure Cosmos アカウントで手動フェールオーバーを実行するPerform manual failover on an Azure Cosmos account

重要

この操作を成功させるには、Azure Cosmos アカウントに手動フェールオーバーを構成する必要があります。The Azure Cosmos account must be configured for manual failover for this operation to succeed.

手動フェールオーバーを実行するプロセスには、アカウントの書き込みリージョン (フェールオーバーの優先順位 = 0) をそのアカウントに構成されている別のリージョンに変更することが含まれます。The process for performing a manual failover involves changing the account's write region (failover priority = 0) to another region configured for the account.

注意

マルチマスター アカウントは手動でフェールオーバーできません。Multi-master accounts cannot be manually failed over. Azure Cosmos SDK を使用するアプリケーションの場合、SDK はリージョンが利用できなくなったときにそれを検出し、SDK でマルチホーミング API を使用している場合、最も近くにあるリージョンに自動的にリダイレクトします。For applications using the Azure Cosmos SDK, the SDK will detect when a region becomes unavailable, then redirect automatically to the next closest region if using multi-homing API in the SDK.

Azure PortalAzure portal

  1. お使いの Azure Cosmos アカウントに移動して、 [データをグローバルにレプリケートする] メニューを開きます。Go to your Azure Cosmos account, and open the Replicate data globally menu.

  2. メニューの上部で、 [手動フェールオーバー] を選択します。At the top of the menu, select Manual Failover.

    [データをグローバルにレプリケートする] メニュー

  3. [手動フェールオーバー] メニューで、新しい書き込みリージョンを選択します。On the Manual Failover menu, select your new write region. チェック ボックスをオンにして、このオプションによって書き込みリージョンが変更されることを理解していることを示します。Select the check box to indicate that you understand this option changes your write region.

  4. フェールオーバーをトリガーするには、 [OK] を選択します。To trigger the failover, select OK.

    手動フェールオーバーのポータル メニュー

Azure CLIAzure CLI

# Assume account currently has regions with priority: eastus=0 westus=1
# Change the priority order to trigger a failover of the write region
$resourceGroupName = 'myResourceGroup'
$accountName = 'myaccountname'

az cosmosdb update --name $accountName --resource-group $resourceGroupName --locations regionName=westus failoverPriority=0 isZoneRedundant=False --locations regionName=eastus failoverPriority=1 isZoneRedundant=False

Azure PowerShellAzure PowerShell

# Assume account currently has regions with priority: West US = 0, East US = 1
# Change the priority order to trigger a failover of the write region
$resourceGroupName = "myResourceGroup"
$accountName = "myaccountname"

$account = Get-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName

$locations = @(
    @{ "locationName"="East US"; "failoverPriority"=0 },
    @{ "locationName"="West US"; "failoverPriority"=1 }
)

$account.Properties.locations=$locations;
$CosmosDBProperties = $account.Properties;

Set-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2015-04-08" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

次の手順Next steps

Azure Cosmos アカウント、データベース、コンテナーの管理方法に関する詳細と例については、次の記事をお読みください。For more information and examples on how to manage the Azure Cosmos account as well as database and containers, read the following articles: