Gestire un account Azure CosmosManage an Azure Cosmos account

Questo articolo descrive come gestire varie attività relative a un account Azure Cosmos usando il portale di Azure, Azure PowerShell, l'interfaccia della riga di comando di Azure e i modelli di Azure Resource Manager.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.

Creare un accountCreate an account

Portale di AzureAzure portal

  1. Passare al portale di Azure per creare un account Azure Cosmos DB.Go to the Azure portal to create an Azure Cosmos DB account. Cercare e selezionare Azure Cosmos DB.Search for and select Azure Cosmos DB.

    Riquadro Database nel portale di Azure

  2. Selezionare Aggiungi.Select Add.

  3. Nella pagina Crea account Cosmos DB immettere le impostazioni base per il nuovo account Azure Cosmos.On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    ImpostazioneSetting ValoreValue DESCRIZIONEDescription
    SubscriptionSubscription Nome della sottoscrizioneSubscription name Selezionare la sottoscrizione di Azure da usare per l'account Azure Cosmos.Select the Azure subscription that you want to use for this Azure Cosmos account.
    Gruppo di risorseResource Group Nome del gruppo di risorseResource group name Selezionare un gruppo di risorse oppure fare clic su Crea nuovo, quindi immettere un nome univoco per il nuovo gruppo di risorse.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Nome accountAccount Name Un nome univocoA unique name Immettere un nome per identificare l'account Azure Cosmos.Enter a name to identify your Azure Cosmos account. Poiché all'ID fornito viene aggiunto documents.azure.com per creare l'URI, usare un ID univoco.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    L'ID può contenere solo lettere minuscole, numeri e il carattere trattino (-).The ID can only contain lowercase letters, numbers, and the hyphen (-) character. Deve avere una lunghezza compresa tra 3 e 31 caratteri.It must be between 3-31 characters in length.
    APIAPI Il tipo di account da creareThe type of account to create Selezionare Core (SQL) per creare un database di documenti e una query con la sintassi SQL.Select Core (SQL) to create a document database and query by using SQL syntax.

    L'API determina il tipo di account da creare.The API determines the type of account to create. Azure Cosmos DB offre cinque API: Core (SQL) e MongoDB per dati dei documenti, Gremlin per i dati dei grafici, Tabelle di Azure e Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. Attualmente, è necessario creare un account separato per ogni API.Currently, you must create a separate account for each API.

    Altre informazioni sull'API SQL.Learn more about the SQL API.
    LocationLocation Area più vicina ai propri utentiThe region closest to your users Selezionare una posizione geografica in cui ospitare l'account Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Usare la località più vicina agli utenti per offrire loro la massima velocità di accesso ai dati.Use the location that is closest to your users to give them the fastest access to the data.

    Pagina del nuovo account per Azure Cosmos DB

  4. Selezionare Rivedi e crea.Select Review + create. È possibile ignorare le sezioni Rete e Tag.You can skip the Network and Tags sections.

  5. Esaminare le impostazioni dell'account e quindi selezionare Crea.Review the account settings, and then select Create. La creazione dell'account richiede alcuni minuti.It takes a few minutes to create the account. Attendere che la pagina del portale visualizzi La distribuzione è stata completata.Wait for the portal page to display Your deployment is complete.

    Riquadro Notifiche del portale di Azure

  6. Selezionare Vai alla risorsa per passare alla pagina dell'account Azure Cosmos DB.Select Go to resource to go to the Azure Cosmos DB account page.

    Pagina dell'account Azure Cosmos DB

Azure CLI

Vedere creare un account di Azure Cosmos DB con l'interfaccia della riga di comando di AzurePlease see Create an Azure Cosmos DB account with Azure CLI

Azure PowerShellAzure PowerShell

Vedere creare un account Azure Cosmos DB con PowerShellPlease see Create an Azure Cosmos DB account with Powershell

Modello di Azure Resource ManagerAzure Resource Manager template

Questo modello di Azure Resource Manager creerà un account Azure Cosmos per l'API SQL configurato con due aree e opzioni per selezionare il livello di coerenza, il failover automatico e il multimaster.This Azure Resource Manager template will create an Azure Cosmos account for SQL API configured with two regions and options to select consistency level, automatic failover, and multi-master. Per distribuire il modello, fare clic su Deploy to Azure (Distribuisci in Azure) nella pagina README relativa alla creazione di un account Azure Cosmos.To deploy this template, click on Deploy to Azure on the readme page, Create Azure Cosmos account

Aggiungere o rimuovere aree dall'account di databaseAdd/remove regions from your database account

Portale di AzureAzure portal

  1. Accedere al portale di Azure.Sign in to Azure portal.

  2. Passare all'account Azure Cosmos e aprire il menu Replica i dati a livello globale.Go to your Azure Cosmos account, and open the Replicate data globally menu.

  3. Per aggiungere aree, selezionare gli esagoni sulla mappa con l'etichetta + corrispondente alle aree geografiche desiderate.To add regions, select the hexagons on the map with the + label that corresponds to your desired region(s). In alternativa, per aggiungere un'area, selezionare l'opzione + Aggiungi area e scegliere un'area dal menu a discesa.Alternatively, to add a region, select the + Add region option and choose a region from the drop-down menu.

  4. Per rimuovere aree, deselezionare una o più aree nella mappa selezionando gli esagoni blu con segni di spunta.To remove regions, clear one or more regions from the map by selecting the blue hexagons with check marks. In alternativa, selezionare l'icona del cestino (🗑) accanto all'area sul lato destro.Or select the "wastebasket" (🗑) icon next to the region on the right side.

  5. Selezionare OK per salvare le modifiche.To save your changes, select OK.

    Aggiungere o rimuovere aree

In modalità di scrittura in una singola area non è possibile rimuovere l'area di scrittura.In a single-region write mode, you cannot remove the write region. È necessario eseguire il failover in un'area diversa prima di poter eliminare l'area di scrittura corrente.You must fail over to a different region before you can delete the current write region.

In modalità di scrittura in più aree è possibile aggiungere o rimuovere qualsiasi area, purché resti almeno un'area.In a multi-region write mode, you can add or remove any region, if you have at least one region.

Azure CLI

Vedere aggiungere o rimuovere aree con l'interfaccia della riga di comando di AzurePlease see Add or remove regions with Azure CLI

Azure PowerShellAzure PowerShell

Vedere aggiungere o rimuovere aree con PowerShellPlease see Add or remove regions with Powershell

Configurare più aree di scritturaConfigure multiple write-regions

Portale di AzureAzure portal

Aprire la scheda Replica i dati a livello globale e selezionare Abilita per abilitare le operazioni di scrittura in più aree.Open the Replicate Data Globally tab and select Enable to enable multi-region writes. Dopo aver abilitato tali operazioni, tutte le aree di lettura di cui si dispone attualmente nell'account diventeranno aree di lettura e scrittura.After you enable multi-region writes, all the read regions that you currently have on the account will become read and write regions.

Screenshot relativo alla configurazione della funzionalità multimaster per l'account Azure Cosmos

Azure CLI

Vedere abilitare aree con più scritture con l'interfaccia della riga di comando di AzurePlease see Enable multiple-write regions with Azure CLI

Azure PowerShellAzure PowerShell

Vedere abilitare aree con più scritture con PowerShellPlease see Enable multiple-write regions with Powershell

modello di Resource ManagerResource Manager template

È possibile eseguire la migrazione di un account da master singolo a multimaster distribuendo il modello di Resource Manager usato per creare l'account e impostando enableMultipleWriteLocations: true.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. Il modello di Azure Resource Manager seguente è il modello minimo essenziale che distribuirà un account Azure Cosmos per l'API SQL con due aree e più località di scrittura abilitate.The following Azure Resource Manager template is a bare minimum template that will deploy an Azure Cosmos account for SQL API with two regions and multiple write locations 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]"
        },
        "primaryRegion":{
            "type":"string",
            "metadata": {
                "description": "The primary replica region for the Cosmos DB account."
            }
        },
        "secondaryRegion":{
            "type":"string",
            "metadata": {
              "description": "The secondary replica region for the Cosmos DB account."
          }
        }
    },
    "resources": [
        {
            "type": "Microsoft.DocumentDb/databaseAccounts",
            "kind": "GlobalDocumentDB",
            "name": "[parameters('name')]",
            "apiVersion": "2019-08-01",
            "location": "[parameters('location')]",
            "tags": {},
            "properties": {
                "databaseAccountOfferType": "Standard",
                "consistencyPolicy": { "defaultConsistencyLevel": "Session" },
                "locations":
                [
                    {
                        "locationName": "[parameters('primaryRegion')]",
                        "failoverPriority": 0,
                        "isZoneRedundant": false
                    },
                    {
                        "locationName": "[parameters('secondaryRegion')]",
                        "failoverPriority": 1,
                        "isZoneRedundant": false
                    }
                ],
                "enableMultipleWriteLocations": true
            }
        }
    ]
}

Abilitare il failover automatico per l'account Azure CosmosEnable automatic failover for your Azure Cosmos account

L'opzione di failover automatico consente ad Azure Cosmos DB di eseguire il failover all'area con la priorità di failover più alta senza alcuna azione da parte dell'utente nel caso in cui un'area diventasse non disponibile.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. Quando il failover automatico è abilitato, è possibile modificare la priorità delle aree.When automatic failover is enabled, region priority can be modified. Per abilitare il failover automatico, è necessario che l'account abbia almeno due aree.Account must have two or more regions to enable automatic failover.

Portale di AzureAzure portal

  1. Dall'account Azure Cosmos aprire il riquadro Replica i dati a livello globale.From your Azure Cosmos account, open the Replicate data globally pane.

  2. Nella parte superiore del riquadro fare clic sul pulsante Failover automatico.At the top of the pane, select Automatic Failover.

    Menu Replica i dati a livello globale

  3. Nel riquadro Failover automatico assicurarsi che Abilita failover automatico sia impostato su .On the Automatic Failover pane, make sure that Enable Automatic Failover is set to ON.

  4. Selezionare Salva.Select Save.

    Menu del portale Failover automatico

Azure CLI

Vedere abilitare il failover automatico con l'interfaccia della riga di comando di AzurePlease see Enable automatic failover with Azure CLI

Azure PowerShellAzure PowerShell

Vedere abilitare il failover automatico con PowerShellPlease see Enable automatic failover with Powershell

Impostare le priorità di failover per l'account Azure CosmosSet failover priorities for your Azure Cosmos account

Dopo aver configurato un account Cosmos per il failover automatico, è possibile modificare la priorità di failover per le aree.After a Cosmos account is configured for automatic failover, the failover priority for regions can be changed.

Importante

Se l'account è configurato per il failover automatico, non è possibile modificare l'area di scrittura (priorità di failover zero).You cannot modify the write region (failover priority of zero) when the account is configured for automatic failover. Per cambiare l'area di scrittura, è necessario disabilitare il failover automatico ed eseguire un failover manuale.To change the write region, you must disable automatic failover and do a manual failover.

Portale di AzureAzure portal

  1. Dall'account Azure Cosmos aprire il riquadro Replica i dati a livello globale.From your Azure Cosmos account, open the Replicate data globally pane.

  2. Nella parte superiore del riquadro fare clic sul pulsante Failover automatico.At the top of the pane, select Automatic Failover.

    Menu Replica i dati a livello globale

  3. Nel riquadro Failover automatico assicurarsi che Abilita failover automatico sia impostato su .On the Automatic Failover pane, make sure that Enable Automatic Failover is set to ON.

  4. Per modificare la priorità di failover, trascinare le aree di lettura tramite i tre puntini a sinistra nella riga, visualizzati al passaggio del mouse.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. Selezionare Salva.Select Save.

    Menu del portale Failover automatico

Azure CLI

Vedere impostare priorità di failover con l'interfaccia della riga di comando di AzurePlease see Set failover priority with Azure CLI

Azure PowerShellAzure PowerShell

Vedere impostare la priorità di failover con PowerShellPlease see Set failover priority with Powershell

Eseguire un failover manuale per un account Azure CosmosPerform manual failover on an Azure Cosmos account

Importante

Affinché questa operazione abbia esito positivo, è necessario configurare l'account Azure Cosmos per il failover manuale.The Azure Cosmos account must be configured for manual failover for this operation to succeed.

Il processo di esecuzione di un failover manuale prevede la modifica dell'area di scrittura dell'account (priorità di failover = 0) mediante l'impostazione di un'altra area configurata per l'account.The process for performing a manual failover involves changing the account's write region (failover priority = 0) to another region configured for the account.

Nota

Non è possibile sottoporre a failover manuale gli account multimaster.Multi-master accounts cannot be manually failed over. Per le applicazioni che usano l'SDK di Azure Cosmos, l'SDK rileverà quando un'area diventa non disponibile e quindi eseguirà automaticamente il reindirizzamento all'area successiva più vicina, se nell'SDK viene usata l'API multihosting.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.

Portale di AzureAzure portal

  1. Passare all'account Azure Cosmos e aprire il menu Replica i dati a livello globale.Go to your Azure Cosmos account, and open the Replicate data globally menu.

  2. Nella parte superiore del menu selezionare Failover manuale.At the top of the menu, select Manual Failover.

    Menu Replica i dati a livello globale

  3. Nel menu Failover manuale selezionare la nuova area di scrittura.On the Manual Failover menu, select your new write region. Selezionare la casella di controllo per indicare di aver compreso che questa opzione modifica l'area di scrittura.Select the check box to indicate that you understand this option changes your write region.

  4. Per attivare il failover, selezionare OK.To trigger the failover, select OK.

    Menu del portale Failover manuale

Azure CLI

Vedere attivare il failover manuale con l'interfaccia della riga di comando di AzurePlease see Trigger manual failover with Azure CLI

Azure PowerShellAzure PowerShell

Vedere attivare il failover manuale con PowerShellPlease see Trigger manual failover with Powershell

Passaggi successiviNext steps

Per altre informazioni ed esempi su come gestire l'account Azure Cosmos, nonché il database e i contenitori, leggere gli articoli seguenti:For more information and examples on how to manage the Azure Cosmos account as well as database and containers, read the following articles: