Краткое руководство. Создание Azure Cosmos DB и контейнера с помощью шаблона ARM

Статья
08/15/2024

ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL

Azure Cosmos DB — это быстрая база данных 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 ЕЗ/с и 25 ГБ пространства в хранилище. Также можно использовать эмулятор Azure Cosmos DB, который доступен по URI https://localhost:8081. Сведения о ключе для использования с эмулятором см. в этом разделе.

Изучение шаблона

Шаблон, используемый в этом кратком руководстве, взят из шаблонов быстрого запуска 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/container: создание контейнера Azure Cosmos DB.

Внимание

Поставщик Microsoft.DocumentDB/databaseAccountsAzure Resource Manager поддерживает то же имя в течение многих лет. Это гарантирует, что шаблоны, написанные лет назад, по-прежнему совместимы с тем же поставщиком, даже если имя службы и вложенных служб развивались.

Другие примеры шаблонов Azure Cosmos DB можно найти в коллекции шаблонов быстрого запуска Azure.

Развертывание шаблона

Выберите следующее изображение, чтобы войти на портал 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.
- Max Staleness Prefix. Максимальное число устаревших запросов. Требуется для BoundedStaleness.
- Максимальный интервал в секундах. Максимальная задержка в секундах. Требуется для BoundedStaleness.
- Имя базы данных: имя базы данных Azure Cosmos DB.
- Имя контейнера: имя контейнера Azure Cosmos DB.
- Пропускная способность. Пропускная способность контейнера, минимальное значение — 400 единиц запросов в секунду.
- I agree to the terms and conditions state above (Я принимаю указанные выше условия). Установите этот флажок.
Щелкните Приобрести. После успешного развертывания учетной записи 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..."

Следующие шаги

В этом кратком руководстве вы создали учетную запись Azure Cosmos DB, базу данных и контейнер с помощью шаблона ARM и проверили развертывание. Дополнительные сведения об Azure Cosmos DB и Azure Resource Manager см. в статьях ниже.

Ознакомьтесь с обзором Azure Cosmos DB.
Сведения об Azure Resource Manager
Получите другие шаблоны Azure Resource Manager для Azure Cosmos DB.
Если вы планируете ресурсы для миграции в Azure Cosmos DB, Для планирования ресурсов можно использовать сведения об имеющемся кластере базы данных.
- Если вам известно только количество виртуальных ядер и серверов в существующем кластере баз данных, прочитайте об оценке единиц запроса на основе этих данных.
- Если вам известна стандартная частота запросов для текущей рабочей нагрузки базы данных, ознакомьтесь со статьей о расчете единиц запросов с помощью планировщика ресурсов Azure Cosmos DB

Поделиться через