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. Nel menu del portale di Azure o dalla pagina Home selezionare Crea una risorsa.From the Azure portal menu or the Home page, select Create a resource.

  2. Nella pagina Nuovo cercare e selezionare Azure Cosmos DB.On the New page, search for and select Azure Cosmos DB.

  3. Nella pagina Azure Cosmos DB selezionare Crea.On the Azure Cosmos DB page, select Create.

  4. 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 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. Dato che al nome specificato viene aggiunto documents.azure.com per creare l'URI, usare un nome univoco.Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name.

    Il nome può contenere solo lettere minuscole, numeri e il segno meno (-).The name can only contain lowercase letters, numbers, and the hyphen (-) character. Deve avere una lunghezza compresa tra 3 e 44 caratteri.It must be between 3-44 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.
    Applica sconto per il livello gratuitoApply Free Tier Discount Applica o Non applicareApply or Do not apply Azure Cosmos DB livello gratuito offre i primi 400 UR/s e 5 GB di spazio di archiviazione gratuiti per account.With Azure Cosmos DB free tier, you will get the first 400 RU/s and 5 GB of storage for free in an account. Altre informazioni sul livello gratuito.Learn more about free tier.
    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.
    Tipo di accountAccount Type Produzione o Non di produzioneProduction or Non-Production Selezionare Produzione se l'account verrà usato per un carico di lavoro di produzione.Select Production if the account will be used for a production workload. Selezionare Non di produzione se l'account non verrà usato per un carico di lavoro di produzione, ad esempio per lo sviluppo, il test, il controllo di qualità o lo staging.Select Non-Production if the account will be used for non-production, e.g. development, testing, QA, or staging. Si tratta di un'impostazione di tag delle risorse di Azure che consente di ottimizzare l'esperienza del portale, ma non influisce sull'account Azure Cosmos DB sottostante.This is an Azure resource tag setting that tunes the Portal experience but does not affect the underlying Azure Cosmos DB account. È possibile modificare questo valore in qualsiasi momento.You can change this value anytime.

    Nota

    È possibile avere fino a un account Azure Cosmos DB del livello gratuito per ogni sottoscrizione di Azure ed è necessario acconsentire esplicitamente durante la creazione dell'account.You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt-in when creating the account. Se l'opzione per l'applicazione dello sconto per il livello gratuito non è visualizzata, un altro account nella sottoscrizione è già stato abilitato per il livello gratuito.If you do not see the option to apply the free tier discount, this means another account in the subscription has already been enabled with free tier.

    Pagina del nuovo account per Azure Cosmos DB

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

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

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

Interfaccia della riga di comando di AzureAzure 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

Vedere creare un account di Azure Cosmos DB con modelli di Azure Resource ManagerPlease see Create Azure Cosmos DB account with Azure Resource Manager templates

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

Interfaccia della riga di comando di AzureAzure 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

Interfaccia della riga di comando di AzureAzure 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

Interfaccia della riga di comando di AzureAzure 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

Interfaccia della riga di comando di AzureAzure 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

Interfaccia della riga di comando di AzureAzure 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: