Creare un account di Azure Cosmos DB mediante PowerShellCreate an Azure Cosmos DB account using PowerShell

La guida seguente illustra i comandi per automatizzare la gestione degli account del database Azure Cosmos DB usando Azure Powershell.The following guide describes commands to automate management of your Azure Cosmos DB database accounts using Azure Powershell. Include anche i comandi per gestire le chiavi dell'account e le priorità di failover in account di database tra più aree.It also includes commands to manage account keys and failover priorities in multi-region database accounts. L'aggiornamento dell'account del database consente di modificare i criteri di coerenza e di aggiungere/rimuovere le aree.Updating your database account allows you to modify consistency policies and add/remove regions. Per la gestione multipiattaforma dell'account di Azure Cosmos DB, è possibile usare l'interfaccia della riga di comando di Azure, l'API REST del provider di risorse o il portale di Azure.For cross-platform management of your Azure Cosmos DB account, you can use either Azure CLI, the Resource Provider REST API, or the Azure portal.

IntroduzioneGetting Started

Seguire le istruzioni in Come installare e configurare Azure PowerShell per installare e accedere all'account di Azure Resource Manager in PowerShell.Follow the instructions in How to install and configure Azure PowerShell to install and log in to your Azure Resource Manager account in Powershell.

NoteNotes

  • Per eseguire i comandi seguenti senza richiedere la conferma dell'utente, aggiungere il flag -Force al comando.If you would like to execute the following commands without requiring user confirmation, append the -Force flag to the command.
  • Tutti i comandi seguenti sono sincroni.All the following commands are synchronous.

Creare un account di Azure Cosmos DBCreate an Azure Cosmos DB Account

Questo comando consente di creare un account del database di Azure Cosmos DB.This command allows you to create an Azure Cosmos DB database account. Configurare il nuovo account del database come ad area singola o a più aree con un determinato criterio di coerenza.Configure your new database account as either single-region or multi-region with a certain consistency policy.

$locations = @(@{"locationName"="<write-region-location>"; "failoverPriority"=0}, @{"locationName"="<read-region-location>"; "failoverPriority"=1})
$iprangefilter = "<ip-range-filter>"
$consistencyPolicy = @{"defaultConsistencyLevel"="<default-consistency-level>"; "maxIntervalInSeconds"="<max-interval>"; "maxStalenessPrefix"="<max-staleness-prefix>"}
$CosmosDBProperties = @{"databaseAccountOfferType"="Standard"; "locations"=$locations; "consistencyPolicy"=$consistencyPolicy; "ipRangeFilter"=$iprangefilter}
New-AzureRmResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName <resource-group-name>  -Location "<resource-group-location>" -Name <database-account-name> -Properties $CosmosDBProperties
  • <write-region-location> Nome della località dell'area di scrittura dell'account del database.<write-region-location> The location name of the write region of the database account. La località è necessaria per impostare il valore della priorità di failover su 0.This location is required to have a failover priority value of 0. Deve essere presente esattamente un'area di scrittura per ogni account di database.There must be exactly one write region per database account.
  • <read-region-location> Nome della località dell'area di lettura dell'account del database.<read-region-location> The location name of the read region of the database account. La località è necessaria per impostare il valore della priorità di failover come maggiore di 0.This location is required to have a failover priority value of greater than 0. Possono essere presenti più aree di lettura per ogni account di database.There can be more than one read regions per database account.
  • <ip-range-filter> Specifica il set di indirizzi IP e di intervalli di indirizzi IP nel formato CIDR da includere come elenco consentito di IP client per un determinato account di database.<ip-range-filter> Specifies the set of IP addresses or IP address ranges in CIDR form to be included as the allowed list of client IPs for a given database account. Gli intervalli di indirizzi IP o i singoli indirizzi IP devono essere delimitati da virgole e non devono contenere spazi.IP addresses/ranges must be comma separated and must not contain any spaces. Per altre informazioni, vedere Azure Cosmos DB Firewall Support (Supporto al firewall di Azure Cosmos DB)For more information, see Azure Cosmos DB Firewall Support
  • <default-consistency-level> Livello di coerenza predefinito dell'account di Azure Cosmos DB.<default-consistency-level> The default consistency level of the Azure Cosmos DB account. Per altre informazioni, vedere Livelli di coerenza in Azure Cosmos DB.For more information, see Consistency Levels in Azure Cosmos DB.
  • <max-interval> Quando è usato con il livello di coerenza Decadimento ristretto, questo valore rappresenta l'intervallo di tempo di decadimento (in secondi) tollerato.<max-interval> When used with Bounded Staleness consistency, this value represents the time amount of staleness (in seconds) tolerated. L'intervallo consentito per questo valore è compreso tra 1 e 100.Accepted range for this value is 1 - 100.
  • <max-staleness-prefix> Quando è usato con il livello di coerenza Decadimento ristretto, questo valore rappresenta il numero di richieste non aggiornate tollerate.<max-staleness-prefix> When used with Bounded Staleness consistency, this value represents the number of stale requests tolerated. L'intervallo consentito per questo valore è compreso tra 1 e 2.147.483.647.Accepted range for this value is 1 – 2,147,483,647.
  • <resource-group-name> Nome del gruppo di risorse di Azure a cui appartiene il nuovo account del database Azure Cosmos DB.<resource-group-name> The name of the Azure Resource Group to which the new Azure Cosmos DB database account belongs to.
  • <resource-group-location> Posizione del gruppo di risorse di Azure a cui appartiene il nuovo account del database Azure Cosmos DB.<resource-group-location> The location of the Azure Resource Group to which the new Azure Cosmos DB database account belongs to.
  • <database-account-name> Nome dell'account del database Azure Cosmos DB da creare.<database-account-name> The name of the Azure Cosmos DB database account to be created. Può contenere solo lettere minuscole, numeri, il carattere "-" e deve essere compreso fra 3 e 50 caratteri.It can only use lowercase letters, numbers, the '-' character, and must be between 3 and 50 characters.

Esempio:Example:

$locations = @(@{"locationName"="West US"; "failoverPriority"=0}, @{"locationName"="East US"; "failoverPriority"=1})
$iprangefilter = ""
$consistencyPolicy = @{"defaultConsistencyLevel"="BoundedStaleness"; "maxIntervalInSeconds"=5; "maxStalenessPrefix"=100}
$CosmosDBProperties = @{"databaseAccountOfferType"="Standard"; "locations"=$locations; "consistencyPolicy"=$consistencyPolicy; "ipRangeFilter"=$iprangefilter}
New-AzureRmResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName "rg-test" -Location "West US" -Name "docdb-test" -Properties $CosmosDBProperties

NoteNotes

  • L'esempio precedente crea un account di database con due aree.The preceding example creates a database account with two regions. È anche possibile creare un account di database con un'area (designata come area di scrittura con un valore di priorità di failover pari a 0) o con più di due aree.It is also possible to create a database account with either one region (which is designated as the write region and have a failover priority value of 0) or more than two regions. Per altre informazioni, vedere gli account di database tra più aree.For more information, see multi-region database accounts.
  • Le località devono essere aree in cui Azure Cosmos DB è disponibile a livello generale.The locations must be regions in which Azure Cosmos DB is generally available. L'elenco corrente delle aree geografiche è disponibile nella pagina Aree di Azure.The current list of regions is provided on the Azure Regions page.

Aggiornare un account di database DocumentDBUpdate a DocumentDB Database Account

Questo comando consente di aggiornare le proprietà di un account del database Azure Cosmos DB.This command allows you to update your Azure Cosmos DB database account properties. e include il criterio di coerenza e le località in cui esiste l'account di database.This includes the consistency policy and the locations which the database account exists in.

Nota

Il comando consente di aggiungere e rimuovere aree, ma non di modificare le priorità di failover.This command allows you to add and remove regions but does not allow you to modify failover priorities. Per modificare le priorità di failover, vedere sotto.To modify failover priorities, see below.

$locations = @(@{"locationName"="<write-region-location>"; "failoverPriority"=0}, @{"locationName"="<read-region-location>"; "failoverPriority"=1})
$iprangefilter = "<ip-range-filter>"
$consistencyPolicy = @{"defaultConsistencyLevel"="<default-consistency-level>"; "maxIntervalInSeconds"="<max-interval>"; "maxStalenessPrefix"="<max-staleness-prefix>"}
$CosmosDBProperties = @{"databaseAccountOfferType"="Standard"; "locations"=$locations; "consistencyPolicy"=$consistencyPolicy; "ipRangeFilter"=$iprangefilter}
Set-AzureRmResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName <resource-group-name> -Name <database-account-name> -Properties $CosmosDBProperties
  • <write-region-location> Nome della località dell'area di scrittura dell'account del database.<write-region-location> The location name of the write region of the database account. La località è necessaria per impostare il valore della priorità di failover su 0.This location is required to have a failover priority value of 0. Deve essere presente esattamente un'area di scrittura per ogni account di database.There must be exactly one write region per database account.
  • <read-region-location> Nome della località dell'area di lettura dell'account del database.<read-region-location> The location name of the read region of the database account. La località è necessaria per impostare il valore della priorità di failover come maggiore di 0.This location is required to have a failover priority value of greater than 0. Possono essere presenti più aree di lettura per ogni account di database.There can be more than one read regions per database account.
  • <default-consistency-level> Livello di coerenza predefinito dell'account di Azure Cosmos DB.<default-consistency-level> The default consistency level of the Azure Cosmos DB account. Per altre informazioni, vedere Livelli di coerenza in Azure Cosmos DB.For more information, see Consistency Levels in Azure Cosmos DB.
  • <ip-range-filter> Specifica il set di indirizzi IP e di intervalli di indirizzi IP nel formato CIDR da includere come elenco consentito di IP client per un determinato account di database.<ip-range-filter> Specifies the set of IP addresses or IP address ranges in CIDR form to be included as the allowed list of client IPs for a given database account. Gli intervalli di indirizzi IP o i singoli indirizzi IP devono essere delimitati da virgole e non devono contenere spazi.IP addresses/ranges must be comma separated and must not contain any spaces. Per altre informazioni, vedere Azure Cosmos DB Firewall Support (Supporto al firewall di Azure Cosmos DB)For more information, see Azure Cosmos DB Firewall Support
  • <max-interval> Quando è usato con il livello di coerenza Decadimento ristretto, questo valore rappresenta l'intervallo di tempo di decadimento (in secondi) tollerato.<max-interval> When used with Bounded Staleness consistency, this value represents the time amount of staleness (in seconds) tolerated. L'intervallo consentito per questo valore è compreso tra 1 e 100.Accepted range for this value is 1 - 100.
  • <max-staleness-prefix> Quando è usato con il livello di coerenza Decadimento ristretto, questo valore rappresenta il numero di richieste non aggiornate tollerate.<max-staleness-prefix> When used with Bounded Staleness consistency, this value represents the number of stale requests tolerated. L'intervallo consentito per questo valore è compreso tra 1 e 2.147.483.647.Accepted range for this value is 1 – 2,147,483,647.
  • <resource-group-name> Nome del gruppo di risorse di Azure a cui appartiene il nuovo account del database Azure Cosmos DB.<resource-group-name> The name of the Azure Resource Group to which the new Azure Cosmos DB database account belongs to.
  • <resource-group-location> Posizione del gruppo di risorse di Azure a cui appartiene il nuovo account del database Azure Cosmos DB.<resource-group-location> The location of the Azure Resource Group to which the new Azure Cosmos DB database account belongs to.
  • <database-account-name> Nome dell'account del database Azure Cosmos DB da aggiornare.<database-account-name> The name of the Azure Cosmos DB database account to be updated.

Esempio:Example:

$locations = @(@{"locationName"="West US"; "failoverPriority"=0}, @{"locationName"="East US"; "failoverPriority"=1})
$iprangefilter = ""
$consistencyPolicy = @{"defaultConsistencyLevel"="BoundedStaleness"; "maxIntervalInSeconds"=5; "maxStalenessPrefix"=100}
$CosmosDBProperties = @{"databaseAccountOfferType"="Standard"; "locations"=$locations; "consistencyPolicy"=$consistencyPolicy; "ipRangeFilter"=$iprangefilter}
Set-AzureRmResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName "rg-test" -Name "docdb-test" -Properties $CosmosDBProperties

Eliminare un account di database DocumentDBDelete a DocumentDB Database Account

Questo comando consente di eliminare un account del database Azure Cosmos DB esistente.This command allows you to delete an existing Azure Cosmos DB database account.

Remove-AzureRmResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName "<resource-group-name>" -Name "<database-account-name>"
  • <resource-group-name> Nome del gruppo di risorse di Azure a cui appartiene il nuovo account del database Azure Cosmos DB.<resource-group-name> The name of the Azure Resource Group to which the new Azure Cosmos DB database account belongs to.
  • <database-account-name> Nome dell'account del database Azure Cosmos DB da eliminare.<database-account-name> The name of the Azure Cosmos DB database account to be deleted.

Esempio:Example:

Remove-AzureRmResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName "rg-test" -Name "docdb-test"

Ottenere le proprietà di un account di database DocumentDBGet Properties of a DocumentDB Database Account

Questo comando consente di ottenere le proprietà di un account del database Azure Cosmos DB esistente.This command allows you to get the properties of an existing Azure Cosmos DB database account.

Get-AzureRmResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName "<resource-group-name>" -Name "<database-account-name>"
  • <resource-group-name> Nome del gruppo di risorse di Azure a cui appartiene il nuovo account del database Azure Cosmos DB.<resource-group-name> The name of the Azure Resource Group to which the new Azure Cosmos DB database account belongs to.
  • <database-account-name> Nome dell'account del database Azure Cosmos DB.<database-account-name> The name of the Azure Cosmos DB database account.

Esempio:Example:

Get-AzureRmResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName "rg-test" -Name "docdb-test"

Tag di aggiornamento dell'account del database Azure Cosmos DBUpdate Tags of an Azure Cosmos DB Database Account

L'esempio seguente illustra come impostare i tag delle risorse di Azure per l'account del database Azure Cosmos DB.The following example describes how to set Azure resource tags for your Azure Cosmos DB database account.

Nota

Questo comando può essere combinato con i comandi di creazione o aggiornamento aggiungendo il flag -Tags con il parametro corrispondente.This command can be combined with the create or update commands by appending the -Tags flag with the corresponding parameter.

Esempio:Example:

$tags = @{"dept" = "Finance”; environment = “Production”}
Set-AzureRmResource -ResourceType “Microsoft.DocumentDB/databaseAccounts”  -ResourceGroupName "rg-test" -Name "docdb-test" -Tags $tags

Elencare le chiavi dell'accountList Account Keys

Quando si crea un account Azure Cosmos DB, il servizio genera due chiavi di accesso principali che possono essere usate per l'autenticazione quando si accede all'account di Azure Cosmos DB.When you create an Azure Cosmos DB account, the service generates two master access keys that can be used for authentication when the Azure Cosmos DB account is accessed. Generando due chiavi di accesso, Azure Cosmos DB consente di rigenerare le chiavi senza interruzioni dell'account Azure Cosmos DB.By providing two access keys, Azure Cosmos DB enables you to regenerate the keys with no interruption to your Azure Cosmos DB account. Sono disponibili anche chiavi di sola lettura per l'autenticazione delle operazioni di sola lettura.Read-only keys for authenticating read-only operations are also available. Esistono due chiavi di lettura/scrittura (primaria e secondaria) e due chiavi di sola lettura (primaria e secondaria).There are two read-write keys (primary and secondary) and two read-only keys (primary and secondary).

$keys = Invoke-AzureRmResourceAction -Action listKeys -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName "<resource-group-name>" -Name "<database-account-name>"
  • <resource-group-name> Nome del gruppo di risorse di Azure a cui appartiene il nuovo account del database Azure Cosmos DB.<resource-group-name> The name of the Azure Resource Group to which the new Azure Cosmos DB database account belongs to.
  • <database-account-name> Nome dell'account del database Azure Cosmos DB.<database-account-name> The name of the Azure Cosmos DB database account.

Esempio:Example:

$keys = Invoke-AzureRmResourceAction -Action listKeys -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName "rg-test" -Name "docdb-test"

Elencare le stringhe di connessioneList Connection Strings

Per gli account di MongoDB, è possibile recuperare la stringa di connessione per connettere l'app MongoDB all'account del database usando il comando seguente.For MongoDB accounts, the connection string to connect your MongoDB app to the database account can be retrieved using the following command.

$keys = Invoke-AzureRmResourceAction -Action listConnectionStrings -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName "<resource-group-name>" -Name "<database-account-name>"
  • <resource-group-name> Nome del gruppo di risorse di Azure a cui appartiene il nuovo account del database Azure Cosmos DB.<resource-group-name> The name of the Azure Resource Group to which the new Azure Cosmos DB database account belongs to.
  • <database-account-name> Nome dell'account del database Azure Cosmos DB.<database-account-name> The name of the Azure Cosmos DB database account.

Esempio:Example:

$keys = Invoke-AzureRmResourceAction -Action listConnectionStrings -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName "rg-test" -Name "docdb-test"

Rigenerare una chiave dell'accountRegenerate Account Key

È consigliabile modificare periodicamente le chiavi di accesso all'account Azure Cosmos DB per mantenere più sicure le connessioni.You should change the access keys to your Azure Cosmos DB account periodically to help keep your connections more secure. Vengono assegnate due chiavi di accesso per consentire di mantenere le connessioni all'account Azure Cosmos DB con una delle due chiavi mentre si rigenera l'altra.Two access keys are assigned to enable you to maintain connections to the Azure Cosmos DB account using one access key while you regenerate the other access key.

Invoke-AzureRmResourceAction -Action regenerateKey -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName "<resource-group-name>" -Name "<database-account-name>" -Parameters @{"keyKind"="<key-kind>"}
  • <resource-group-name> Nome del gruppo di risorse di Azure a cui appartiene il nuovo account del database Azure Cosmos DB.<resource-group-name> The name of the Azure Resource Group to which the new Azure Cosmos DB database account belongs to.
  • <database-account-name> Nome dell'account del database Azure Cosmos DB.<database-account-name> The name of the Azure Cosmos DB database account.
  • <key-kind> Uno dei quattro tipi di chiavi: ["Primary"|"Secondary"|"PrimaryReadonly"|"SecondaryReadonly"] che si vuole rigenerare.<key-kind> One of the four types of keys: ["Primary"|"Secondary"|"PrimaryReadonly"|"SecondaryReadonly"] that you would like to regenerate.

Esempio:Example:

Invoke-AzureRmResourceAction -Action regenerateKey -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName "rg-test" -Name "docdb-test" -Parameters @{"keyKind"="Primary"}

Modificare la priorità di failover di un account del database Azure Cosmos DBModify Failover Priority of an Azure Cosmos DB Database Account

Per gli account del database tra più aree, è possibile modificare la priorità di failover delle diverse aree in cui esiste l'account del database Azure Cosmos DB.For multi-region database accounts, you can change the failover priority of the various regions which the Azure Cosmos DB database account exists in. Per altre informazioni sul failover nell'account del database Azure Cosmos DB, vedere Distribuire i dati a livello globale con Azure Cosmos DB.For more information on failover in your Azure Cosmos DB database account, see Distribute data globally with Azure Cosmos DB.

$failoverPolicies = @(@{"locationName"="<write-region-location>"; "failoverPriority"=0},@{"locationName"="<read-region-location>"; "failoverPriority"=1})
Invoke-AzureRmResourceAction -Action failoverPriorityChange -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName "<resource-group-name>" -Name "<database-account-name>" -Parameters @{"failoverPolicies"=$failoverPolicies}
  • <write-region-location> Nome della località dell'area di scrittura dell'account del database.<write-region-location> The location name of the write region of the database account. La località è necessaria per impostare il valore della priorità di failover su 0.This location is required to have a failover priority value of 0. Deve essere presente esattamente un'area di scrittura per ogni account di database.There must be exactly one write region per database account.
  • <read-region-location> Nome della località dell'area di lettura dell'account del database.<read-region-location> The location name of the read region of the database account. La località è necessaria per impostare il valore della priorità di failover come maggiore di 0.This location is required to have a failover priority value of greater than 0. Possono essere presenti più aree di lettura per ogni account di database.There can be more than one read regions per database account.
  • <resource-group-name> Nome del gruppo di risorse di Azure a cui appartiene il nuovo account del database Azure Cosmos DB.<resource-group-name> The name of the Azure Resource Group to which the new Azure Cosmos DB database account belongs to.
  • <database-account-name> Nome dell'account del database Azure Cosmos DB.<database-account-name> The name of the Azure Cosmos DB database account.

Esempio:Example:

$failoverPolicies = @(@{"locationName"="East US"; "failoverPriority"=0},@{"locationName"="West US"; "failoverPriority"=1})
Invoke-AzureRmResourceAction -Action failoverPriorityChange -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion "2015-04-08" -ResourceGroupName "rg-test" -Name "docdb-test" -Parameters @{"failoverPolicies"=$failoverPolicies}

Passaggi successiviNext steps