Avvio rapido: creare un database Azure Cosmos DB e un contenitore con un modello di Resource Manager

Articolo
08/15/2024

SI APPLICA A: NoSQL

Azure Cosmos DB è il database NoSQL veloce di Microsoft con API aperte per qualsiasi scala. È possibile usare Azure Cosmos DB per creare rapidamente database di chiavi/valori, di documenti e a grafo ed eseguire query su di essi. È possibile configurare un account Azure Cosmos DB di prova gratuito anche senza una carta di credito o una sottoscrizione di Azure. Questo argomento di avvio rapido illustra il processo di distribuzione di un modello di Azure Resource Manager (modello ARM) per creare un database Azure Cosmos DB e un contenitore al suo interno. Sarà quindi possibile archiviare dati in questo contenitore.

Un modello di Azure Resource Manager è un file JSON (JavaScript Object Notation) che definisce l'infrastruttura e la configurazione del progetto. Il modello utilizza la sintassi dichiarativa. Si descrive la distribuzione prevista senza scrivere la sequenza di comandi di programmazione necessari per creare la distribuzione.

Se l'ambiente soddisfa i prerequisiti e si ha familiarità con l'uso dei modelli di Resource Manager, selezionare il pulsante Distribuisci in Azure. Il modello verrà aperto nel portale di Azure.

Prerequisiti

Una sottoscrizione di Azure o un account di prova gratuito di Azure Cosmos DB

Se non si ha una sottoscrizione di Azure, creare un account Azure gratuito prima di iniziare.
È possibile provare gratuitamente Azure Cosmos DB senza una sottoscrizione di Azure e senza impegno. In alternativa, è possibile creare un account di livello gratuito di Azure Cosmos DB, con i primi 1.000 UR/s e 25 GB di spazio di archiviazione gratuiti. È anche possibile usare l'Emulatore di Azure Cosmos DB con l'URI https://localhost:8081. Per la chiave da usare con l'emulatore, vedere Autenticazione delle richieste.

Rivedere il modello

Il modello usato in questo avvio rapido proviene dai modelli di avvio rapido di 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'))]"
    }
  }
}

Nel modello sono definite tre risorse di Azure:

Microsoft.DocumentDB/databaseAccounts: consente di creare un account Azure Cosmos DB.
Microsoft.DocumentDB/databaseAccounts/sqlDatabases: consente di creare un database Azure Cosmos DB.
Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers: consente di creare un contenitore Azure Cosmos DB.

Importante

Il provider di Azure Resource Manager, Microsoft.DocumentDB/databaseAccounts, ha mantenuto lo stesso nome per molti anni. Ciò garantisce che i modelli scritti anni fa siano ancora compatibili con lo stesso provider anche se il nome del servizio e dei sottoservizi sono cambiati.

Altri esempi di modelli di Azure Cosmos DB sono disponibili nella raccolta di modelli di avvio rapido di Azure.

Distribuire il modello

Selezionare l'immagine seguente per accedere ad Azure e aprire un modello. Il modello crea un account, un database e un contenitore Azure Cosmos DB.
Selezionare o immettere i valori seguenti.

Se non specificati, usare i valori predefiniti per creare le risorse di Azure Cosmos DB.
- Sottoscrizione: selezionare una sottoscrizione di Azure.
- Gruppo di risorse: selezionare Crea nuovo, immettere un nome univoco per il gruppo di risorse e quindi fare clic su OK.
- Località: selezionare una località. Ad esempio Stati Uniti centrali.
- Nome account: immettere un nome per l'account Azure Cosmos DB. Deve essere univoco a livello globale.
- Località: immettere una località in cui creare l'account Azure Cosmos DB. Può essere la stessa località in cui si trova il gruppo di risorse.
- Area primaria: area di replica primaria per l'account Azure Cosmos DB.
- Area secondaria: area di replica secondaria per l'account Azure Cosmos DB.
- Livello di coerenza predefinito: livello di coerenza predefinito dell'account Azure Cosmos DB.
- Prefisso di decadimento massimo: numero massimo di richieste non aggiornate. Obbligatorio per BoundedStaleness.
- Intervallo massimo in secondi: tempo di ritardo massimo. Obbligatorio per BoundedStaleness.
- Nome del database: nome del database Azure Cosmos DB.
- Nome del contenitore: nome del contenitore Azure Cosmos DB.
- Velocità effettiva: velocità effettiva del contenitore. Il valore minimo è 400 UR/sec.
- Accetto le condizioni riportate sopra: selezionare.
Selezionare Acquista. Al termine della distribuzione dell'account Azure Cosmos DB, si riceverà una notifica:

Per distribuire il modello, si usa il portale di Azure. Oltre al portale di Azure, è anche possibile usare Azure PowerShell, l'interfaccia della riga di comando di Azure e l'API REST. Per informazioni sugli altri metodi di distribuzione, vedere Distribuire modelli.

Convalidare la distribuzione

È possibile usare il portale di Azure per controllare l'account, il database e il contenitore Azure Cosmos DB oppure usare lo script dell'interfaccia della riga di comando di Azure o di Azure PowerShell seguente per elencare il segreto creato.

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..."

Pulire le risorse

Se si prevede di usare le guide di avvio rapido e le esercitazioni successive, è consigliabile non cancellare le risorse create. Quando non è più necessario, eliminare il gruppo di risorse per eliminare l'account Azure Cosmos DB e le risorse correlate. Per eliminare il gruppo di risorse con l'interfaccia della riga di comando di Azure oppure con 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..."

Passaggi successivi

In questo argomento di avvio rapido sono stati creati un account, un database e un contenitore Azure Cosmos DB usando un modello di Resource Manager ed è stata convalidata la distribuzione. Per altre informazioni su Azure Cosmos DB e Azure Resource Manager, continuare con gli articoli seguenti.

Leggere una panoramica di Azure Cosmos DB
Vedere altre informazioni su Azure Resource Manager
Ottenere altri modelli di Azure Resource Manager per Azure Cosmos DB
Si sta tentando di pianificare la capacità per una migrazione ad Azure Cosmos DB? È possibile usare le informazioni del cluster di database esistente per la pianificazione della capacità.
- Se si conosce solo il numero di vcore e server nel cluster di database esistente, leggere le informazioni sulla stima delle unità richieste usando vCore o vCPU
- Se si conosce la frequenza delle richieste tipiche per il carico di lavoro corrente del database, leggere le informazioni sulla stima delle unità richieste con lo strumento di pianificazione della capacità di Azure Cosmos DB

Condividi tramite