快速入門：使用 ARM 範本建立 Azure Cosmos DB 和容器

發行項
08/15/2024

適用於：NoSQL

Azure Cosmos DB 是 Microsoft 的快速 NoSQL 資料庫，可支援任何規模的開放式 API。您可以使用 Azure Cosmos DB 快速地建立及查詢機碼/值資料庫、文件資料庫與圖形資料庫。如果沒有信用卡或 Azure 訂用帳戶，您可以設定免費的試用 Azure Cosmos DB 帳戶。本快速入門所著重的程序可讓您部署 Azure Resource Manager 範本 (ARM 範本) 以建立 Azure Cosmos DB 資料庫，並於該資料庫中建立容器。您稍後可以在此容器中儲存資料。

Azure Resource Manager 範本是一個 JavaScript 物件標記法 (JSON) 檔案，會定義專案的基礎結構和設定。範本使用宣告式語法。您可以描述預期的部署，而不需要撰寫程式設計命令順序來建立部署。

如果您的環境符合必要條件，而且您很熟悉 ARM 範本，請選取 [部署至 Azure] 按鈕。範本會在 Azure 入口網站中開啟。

必要條件

Azure 訂用帳戶或免費的 Azure Cosmos DB 試用帳戶

如果您沒有 Azure 訂用帳戶，請在開始之前先建立 Azure 免費帳戶。
您可以免費試用 Azure Cosmos DB，不需 Azure 訂用帳戶，也不需要承諾用量。或者，您可以建立 Azure Cosmos DB 免費層帳戶，免費使用前 1000 RU/秒和 25 GB 的儲存體。您也可以搭配 https://localhost:8081 的 URI 使用 Azure Cosmos DB 模擬器。如需要搭配模擬器使用的金鑰，請參閱驗證要求。

檢閱範本

本快速入門中使用的範本是來自 Azure 快速入門範本。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.26.54.24096",
      "templateHash": "7578513359154607542"
    }
  },
  "parameters": {
    "accountName": {
      "type": "string",
      "defaultValue": "[format('sql-{0}', uniqueString(resourceGroup().id))]",
      "metadata": {
        "description": "Azure Cosmos DB account name, max length 44 characters"
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for the Azure Cosmos DB account."
      }
    },
    "primaryRegion": {
      "type": "string",
      "metadata": {
        "description": "The primary region for the Azure Cosmos DB account."
      }
    },
    "secondaryRegion": {
      "type": "string",
      "metadata": {
        "description": "The secondary region for the Azure Cosmos DB account."
      }
    },
    "defaultConsistencyLevel": {
      "type": "string",
      "defaultValue": "Session",
      "allowedValues": [
        "Eventual",
        "ConsistentPrefix",
        "Session",
        "BoundedStaleness",
        "Strong"
      ],
      "metadata": {
        "description": "The default consistency level of the Cosmos DB account."
      }
    },
    "maxStalenessPrefix": {
      "type": "int",
      "defaultValue": 100000,
      "minValue": 10,
      "maxValue": 2147483647,
      "metadata": {
        "description": "Max stale requests. Required for BoundedStaleness. Valid ranges, Single Region: 10 to 2147483647. Multi Region: 100000 to 2147483647."
      }
    },
    "maxIntervalInSeconds": {
      "type": "int",
      "defaultValue": 300,
      "minValue": 5,
      "maxValue": 86400,
      "metadata": {
        "description": "Max lag time (minutes). Required for BoundedStaleness. Valid ranges, Single Region: 5 to 84600. Multi Region: 300 to 86400."
      }
    },
    "systemManagedFailover": {
      "type": "bool",
      "defaultValue": true,
      "allowedValues": [
        true,
        false
      ],
      "metadata": {
        "description": "Enable system managed failover for regions"
      }
    },
    "databaseName": {
      "type": "string",
      "defaultValue": "myDatabase",
      "metadata": {
        "description": "The name for the database"
      }
    },
    "containerName": {
      "type": "string",
      "defaultValue": "myContainer",
      "metadata": {
        "description": "The name for the container"
      }
    },
    "throughput": {
      "type": "int",
      "defaultValue": 400,
      "minValue": 400,
      "maxValue": 1000000,
      "metadata": {
        "description": "The throughput for the container"
      }
    }
  },
  "variables": {
    "consistencyPolicy": {
      "Eventual": {
        "defaultConsistencyLevel": "Eventual"
      },
      "ConsistentPrefix": {
        "defaultConsistencyLevel": "ConsistentPrefix"
      },
      "Session": {
        "defaultConsistencyLevel": "Session"
      },
      "BoundedStaleness": {
        "defaultConsistencyLevel": "BoundedStaleness",
        "maxStalenessPrefix": "[parameters('maxStalenessPrefix')]",
        "maxIntervalInSeconds": "[parameters('maxIntervalInSeconds')]"
      },
      "Strong": {
        "defaultConsistencyLevel": "Strong"
      }
    },
    "locations": [
      {
        "locationName": "[parameters('primaryRegion')]",
        "failoverPriority": 0,
        "isZoneRedundant": false
      },
      {
        "locationName": "[parameters('secondaryRegion')]",
        "failoverPriority": 1,
        "isZoneRedundant": false
      }
    ]
  },
  "resources": [
    {
      "type": "Microsoft.DocumentDB/databaseAccounts",
      "apiVersion": "2024-02-15-preview",
      "name": "[toLower(parameters('accountName'))]",
      "location": "[parameters('location')]",
      "kind": "GlobalDocumentDB",
      "properties": {
        "consistencyPolicy": "[variables('consistencyPolicy')[parameters('defaultConsistencyLevel')]]",
        "locations": "[variables('locations')]",
        "databaseAccountOfferType": "Standard",
        "enableAutomaticFailover": "[parameters('systemManagedFailover')]",
        "disableKeyBasedMetadataWriteAccess": true
      }
    },
    {
      "type": "Microsoft.DocumentDB/databaseAccounts/sqlDatabases",
      "apiVersion": "2024-02-15-preview",
      "name": "[format('{0}/{1}', toLower(parameters('accountName')), parameters('databaseName'))]",
      "properties": {
        "resource": {
          "id": "[parameters('databaseName')]"
        }
      },
      "dependsOn": [
        "[resourceId('Microsoft.DocumentDB/databaseAccounts', toLower(parameters('accountName')))]"
      ]
    },
    {
      "type": "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers",
      "apiVersion": "2024-02-15-preview",
      "name": "[format('{0}/{1}/{2}', toLower(parameters('accountName')), parameters('databaseName'), parameters('containerName'))]",
      "properties": {
        "resource": {
          "id": "[parameters('containerName')]",
          "partitionKey": {
            "paths": [
              "/myPartitionKey"
            ],
            "kind": "Hash"
          },
          "indexingPolicy": {
            "indexingMode": "consistent",
            "includedPaths": [
              {
                "path": "/*"
              }
            ],
            "excludedPaths": [
              {
                "path": "/myPathToNotIndex/*"
              },
              {
                "path": "/_etag/?"
              }
            ],
            "compositeIndexes": [
              [
                {
                  "path": "/name",
                  "order": "ascending"
                },
                {
                  "path": "/age",
                  "order": "descending"
                }
              ]
            ],
            "spatialIndexes": [
              {
                "path": "/location/*",
                "types": [
                  "Point",
                  "Polygon",
                  "MultiPolygon",
                  "LineString"
                ]
              }
            ]
          },
          "defaultTtl": 86400,
          "uniqueKeyPolicy": {
            "uniqueKeys": [
              {
                "paths": [
                  "/phoneNumber"
                ]
              }
            ]
          }
        },
        "options": {
          "throughput": "[parameters('throughput')]"
        }
      },
      "dependsOn": [
        "[resourceId('Microsoft.DocumentDB/databaseAccounts/sqlDatabases', toLower(parameters('accountName')), parameters('databaseName'))]"
      ]
    }
  ],
  "outputs": {
    "location": {
      "type": "string",
      "value": "[parameters('location')]"
    },
    "name": {
      "type": "string",
      "value": "[parameters('databaseName')]"
    },
    "resourceGroupName": {
      "type": "string",
      "value": "[resourceGroup().name]"
    },
    "resourceId": {
      "type": "string",
      "value": "[resourceId('Microsoft.DocumentDB/databaseAccounts/sqlDatabases', toLower(parameters('accountName')), parameters('databaseName'))]"
    }
  }
}

範本中定義了三個 Azure 資源：

Microsoft.DocumentDB/databaseAccounts：建立 Azure Cosmos DB 帳戶。
Microsoft.DocumentDB/databaseAccounts/sqlDatabases：建立 Azure Cosmos DB 資料庫。
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers：建立 Azure Cosmos DB 容器。

重要

Azure Resource Manager 提供者 Microsoft.DocumentDB/databaseAccounts 多年來一直維持相同的名稱。這可確保幾年前所撰寫的範本仍與相同的提供者相容，即使服務名稱和子服務的名稱已演進也一樣。

您可以在快速入門範本資源庫中找到更多 Azure Cosmos DB 範本的範例。

部署範本

選取以下影像來登入 Azure 並開啟範本。此範本會建立 Azure Cosmos DB 帳戶、資料庫和容器。
選取或輸入下列值。

除非另有指定，否則請使用預設值來建立 Azure Cosmos DB 資源。
- 訂用帳戶：選取 Azure 訂用帳戶。
- [資源群組]選取 [新建]，輸入資源群組的唯一名稱，然後按一下 [確認]。
- 位置：選取位置。例如，美國中部。
- 帳戶名稱：輸入 Azure Cosmos DB 帳戶的名稱。此名稱必須是全域唯一的。
- 位置：輸入您想要在其中建立 Azure Cosmos DB 帳戶的位置。 Azure Cosmos DB 帳戶的位置可以與資源群組相同。
- 主要區域：Azure Cosmos DB 帳戶的主要複本區域。
- 次要區域：Azure Cosmos DB 帳戶的次要複本區域。
- 預設一致性等級：Azure Cosmos DB 帳戶的預設一致性等級。
- 過期前置詞上限：過期要求上限。需要 BoundedStaleness。
- 最大間隔 (秒)：最大延遲時間。需要 BoundedStaleness。
- 資料庫名稱：Azure Cosmos DB 資料庫的名稱。
- 容器名稱：Azure Cosmos DB 容器的名稱。
- 輸送量：容器的輸送量，輸送量的最小值為 400 RU/秒。
- 我同意上方所述的條款及條件：選取。
選取 [購買] 。成功部署 Azure Cosmos DB 帳戶之後，您會收到通知：

Azure 入口網站用於部署範本。除了 Azure 入口網站以外，您也可以使用 Azure PowerShell、Azure CLI 和 REST API。若要了解其他部署方法，請參閱部署範本。

驗證部署

您可以使用 Azure 入口網站來檢查 Azure Cosmos DB 帳戶、資料庫和容器，或使用下列 Azure CLI 或 Azure PowerShell 指令碼來列出已建立的祕密。

CLI
PowerShell

echo "Enter your Azure Cosmos DB account name:" &&
read cosmosAccountName &&
echo "Enter the resource group where the Azure Cosmos DB account exists:" &&
read resourcegroupName &&
az cosmosdb show -g $resourcegroupName -n $cosmosAccountName

$resourceGroupName = Read-Host -Prompt "Enter the resource group name where your Azure Cosmos DB account exists"
(Get-AzResource -ResourceType "Microsoft.DocumentDB/databaseAccounts" -ResourceGroupName $resourceGroupName).Name
 Write-Host "Press [ENTER] to continue..."

清除資源

如果您打算繼續進行後續的快速入門和教學課程，您可以讓這些資源留在原處。請刪除不再需要的資源群組，這麼做會刪除 Azure Cosmos DB 帳戶和相關資源。若要使用 Azure CLI 或 Azure PowerShell 刪除資源群組：

CLI
PowerShell

echo "Enter the Resource Group name:" &&
read resourceGroupName &&
az group delete --name $resourceGroupName &&
echo "Press [ENTER] to continue ..."

$resourceGroupName = Read-Host -Prompt "Enter the Resource Group name"
Remove-AzResourceGroup -Name $resourceGroupName
Write-Host "Press [ENTER] to continue..."

下一步

在本快速入門中，您已使用 ARM 範本建立 Azure Cosmos DB 帳戶、資料庫和容器，並已驗證過部署。若要深入了解 Azure Cosmos DB 和 Azure Resource Manager，請繼續閱讀下列文章。

閱讀 Azure Cosmos DB 的概觀
深入了解 Azure Resource Manager
取得其他的 Azure Cosmos DB Resource Manager 範本
正在嘗試為遷移至 Azure Cosmos DB 進行容量規劃嗎？您可以使用現有資料庫叢集的相關資訊進行容量規劃。
- 如果您知道現有資料庫叢集中的虛擬核心和伺服器數目，請參閱使用虛擬核心或 vCPU 來估計要求單位
- 如果您知道目前資料庫工作負載的一般要求率，請參閱使用 Azure Cosmos DB 容量規劃工具來估計要求單位

共用方式為