{"id":1367,"date":"2020-06-08T11:14:00","date_gmt":"2020-06-08T18:14:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cosmosdb\/?p=1367"},"modified":"2020-06-08T11:14:00","modified_gmt":"2020-06-08T18:14:00","slug":"manage-with-powershell","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cosmosdb\/manage-with-powershell\/","title":{"rendered":"Manage Azure Cosmos DB with PowerShell"},"content":{"rendered":"<p>We are excited to announce that you can now manage Azure Cosmos DB resources using the new <strong>Az.CosmosDB<\/strong> PowerShell package. This package is currently in public preview and will be generally available (GA) soon!<\/p>\n<p>&nbsp;<\/p>\n<h3>Get Az.CosmosDB<\/h3>\n<p>To work with Az.CosmosDB, you will need:<\/p>\n<ol>\n<li><a href=\"https:\/\/docs.microsoft.com\/powershell\/scripting\/install\/installing-powershell\" target=\"_blank\" rel=\"noopener noreferrer\">PowerShell<\/a>. The Az and Az.CosmosDB packages are compatible with Windows PowerShell 5.1 or cross-platform PowerShell 7.<\/li>\n<li>The <a href=\"https:\/\/docs.microsoft.com\/powershell\/azure\/install-az-ps\" target=\"_blank\" rel=\"noopener noreferrer\">Az package<\/a>.<\/li>\n<li>The <a href=\"https:\/\/www.powershellgallery.com\/packages\/Az.CosmosDB\" target=\"_blank\" rel=\"noopener noreferrer\">Az.CosmosDB package<\/a>. (Note that when Az.CosmosDB becomes GA, the Az package will include it.)<\/li>\n<\/ol>\n<p>You can work with Az.CosmosDB in your preferred Powershell console or editor. You can also work with Az.CosmosDB directly in the <a href=\"https:\/\/docs.microsoft.com\/azure\/cloud-shell\/quickstart-powershell\" target=\"_blank\" rel=\"noopener noreferrer\">Azure portal Cloud Shell with PowerShell<\/a>. (Note: Az is automatically installed in Cloud Shell. Before GA, you will need to install Az.CosmosDB separately.)<\/p>\n<p>Check your installations of Az and Az.CosmosDB with <a href=\"https:\/\/docs.microsoft.com\/powershell\/module\/powershellget\/get-installedmodule\" target=\"_blank\" rel=\"noopener noreferrer\">Get-InstalledModule<\/a> (your versions may differ):<\/p>\n<p><img decoding=\"async\" class=\"aligncenter wp-image-1372 size-full\" src=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2020\/06\/202006-powershell-get-installed.png\" alt=\"Get-InstalledModule output for Az and Az.CosmosDB Powershell packages\" width=\"1159\" height=\"272\" srcset=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2020\/06\/202006-powershell-get-installed.png 1159w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2020\/06\/202006-powershell-get-installed-300x70.png 300w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2020\/06\/202006-powershell-get-installed-1024x240.png 1024w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2020\/06\/202006-powershell-get-installed-768x180.png 768w\" sizes=\"(max-width: 1159px) 100vw, 1159px\" \/><\/p>\n<p>&nbsp;<\/p>\n<h3>Use Az.CosmosDB<\/h3>\n<p>Now that you have Az.CosmosDB installed, what can you do with it?<\/p>\n<p>You can run a complete set of management operations &#8211; create, update, delete, and list &#8211; on A<span style=\"font-size: 1rem;\">zure Cosmos DB <\/span><a style=\"background-color: #f7f7f9; font-size: 1rem;\" href=\"https:\/\/docs.microsoft.com\/azure\/cosmos-db\/account-overview\" target=\"_blank\" rel=\"noopener noreferrer\">accounts<\/a><span style=\"font-size: 1rem;\">, <\/span><a style=\"background-color: #f7f7f9; font-size: 1rem;\" href=\"https:\/\/docs.microsoft.com\/azure\/cosmos-db\/databases-containers-items\" target=\"_blank\" rel=\"noopener noreferrer\">databases, and containers.<\/a><span style=\"font-size: 1rem;\"> Management cmdlets are available for all Cosmos DB APIs: Core (SQL), MongoDB, Cassandra, Gremlin, and Table.<\/span><\/p>\n<p>Az.CosmosDB cmdlets can also manage:<\/p>\n<ul>\n<li>database and container throughput<\/li>\n<li>partition keys and unique keys<\/li>\n<li>range, composite, and spatial indexes<\/li>\n<li>stored procedures and user-defined functions<\/li>\n<li>conflict resolution policies<\/li>\n<li>virtual network rules<\/li>\n<li>and more! See the <a href=\"https:\/\/docs.microsoft.com\/powershell\/module\/az.cosmosdb\/\" target=\"_blank\" rel=\"noopener noreferrer\">Az.CosmosDB cmdlet reference<\/a> for all operations.<\/li>\n<\/ul>\n<p>&nbsp;<\/p>\n<h3>Combine PowerShell management operations<\/h3>\n<p>Az.CosmosDB cmdlets expose different combinations of parameters, or parameter sets. All cmdlets can run with typical value parameters for resource names and configuration settings. Many cmdlets can also run with parameter sets that include a <code>ParentObject<\/code> or <code>InputObject<\/code> parameter.<\/p>\n<p>These parameter sets are useful when scripts maintain local state during operations on related resources. For example, let&#8217;s add a new database and container to an existing Azure Cosmos DB SQL API account.<\/p>\n<p>First, we retrieve the existing Azure Cosmos DB account using <code>Get-AzCosmosDBAccount<\/code> and set the output to a local variable:<\/p>\n<p><code>$account = Get-AzCosmosDBAccount -ResourceGroupName \"myResourceGroup\" -Name \"ps-cosmos-db\"<\/code><\/p>\n<p>Next, we create a new database in the account using <code>New-AzCosmosDBSqlDatabase<\/code>, pass <code>$account<\/code> for the <code>ParentObject<\/code> parameter, and set the output to another local variable:<\/p>\n<p><code>$database = New-AzCosmosDBSqlDatabase <strong>-ParentObject $account<\/strong> -Name \"myDatabaseName\"<\/code><\/p>\n<p>Finally, we create a new container in the database using <code>New-AzCosmosDBSqlContainer<\/code>, passing <code>$database<\/code> for the <code>ParentObject<\/code> parameter:<\/p>\n<p><code>New-AzCosmosDBSqlContainer <strong>-ParentObject $database<\/strong> -Name \"myContainerName\" -PartitionKeyKind \"Hash\" -PartitionKeyPath \"\/myPartitionKey\" -Throughput 400<\/code><\/p>\n<p>Note that we did not set the output of <code>New-AzCosmosDBSqlContainer<\/code> to a local variable. We do not have further management steps, so another local variable was not needed. Like all <code>New-AzCosmosDB*<\/code> cmdlets, <code>New-AzCosmosDBSqlContainer<\/code> outputs an object reflecting the updated state of the resource.<\/p>\n<p>Similarly, <code>Update-AzCosmosDB*<\/code> cmdlets output objects reflecting the updated state of the resources. You can use these outputs to maintain local state and combine management operations on related resources in your scripts.<\/p>\n<p><img decoding=\"async\" class=\"aligncenter wp-image-1384 size-full\" src=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2020\/06\/202006-powershell-multi-ops.png\" alt=\"Powershell console showing multiple Az.CosmosDB cmdlets using ParentObject parameter and local variables\" width=\"1218\" height=\"451\" srcset=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2020\/06\/202006-powershell-multi-ops.png 1218w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2020\/06\/202006-powershell-multi-ops-300x111.png 300w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2020\/06\/202006-powershell-multi-ops-1024x379.png 1024w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2020\/06\/202006-powershell-multi-ops-768x284.png 768w\" sizes=\"(max-width: 1218px) 100vw, 1218px\" \/><\/p>\n<p>&nbsp;<\/p>\n<h3>Work with Samples<\/h3>\n<p>To get you started, PowerShell samples for Azure Cosmos DB management are available for each of the Azure Cosmos DB APIs:<\/p>\n<ul>\n<li><a href=\"https:\/\/docs.microsoft.com\/azure\/cosmos-db\/powershell-samples-sql\" target=\"_blank\" rel=\"noopener noreferrer\">Core (SQL) API samples<\/a><\/li>\n<li><a href=\"https:\/\/docs.microsoft.com\/azure\/cosmos-db\/powershell-samples-mongodb\" target=\"_blank\" rel=\"noopener noreferrer\">MongoDB API samples<\/a><\/li>\n<li><a href=\"https:\/\/docs.microsoft.com\/azure\/cosmos-db\/powershell-samples-cassandra\" target=\"_blank\" rel=\"noopener noreferrer\">Cassandra API samples<\/a><\/li>\n<li><a href=\"https:\/\/docs.microsoft.com\/azure\/cosmos-db\/powershell-samples-gremlin\" target=\"_blank\" rel=\"noopener noreferrer\">Gremlin API samples<\/a><\/li>\n<li><a href=\"https:\/\/docs.microsoft.com\/azure\/cosmos-db\/powershell-samples-table\" target=\"_blank\" rel=\"noopener noreferrer\">Table API samples<\/a><\/li>\n<\/ul>\n<p>&nbsp;<\/p>\n<h3>References<\/h3>\n<ul>\n<li><a href=\"https:\/\/docs.microsoft.com\/azure\/cosmos-db\/manage-with-powershell\" target=\"_blank\" rel=\"noopener noreferrer\">Manage Azure Cosmos DB SQL API resources using PowerShell<\/a><\/li>\n<li><a href=\"https:\/\/docs.microsoft.com\/powershell\/module\/az.cosmosdb\/\" target=\"_blank\" rel=\"noopener noreferrer\">Az.CosmosDB cmdlet reference<\/a><\/li>\n<li><a href=\"https:\/\/github.com\/Azure\/azure-powershell\/tree\/master\/src\/CosmosDB\" target=\"_blank\" rel=\"noopener noreferrer\">Az.CosmosDB source code on GitHub<\/a><\/li>\n<li><a href=\"https:\/\/github.com\/Azure\/azure-powershell\/issues\" target=\"_blank\" rel=\"noopener noreferrer\">Bugs or feature requests on GitHub<\/a><\/li>\n<\/ul>\n<p>&nbsp;<\/p>\n<p><code><\/code><code><\/code><\/p>\n<p><code><\/code><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Learn about how you can manage Azure Cosmos DB resources using the new Az.CosmosDB PowerShell package.<\/p>\n","protected":false},"author":13019,"featured_media":1374,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[12,1460],"tags":[1430,1429],"class_list":["post-1367","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-announcements","category-powershell","tag-management","tag-powershell"],"acf":[],"blog_post_summary":"<p>Learn about how you can manage Azure Cosmos DB resources using the new Az.CosmosDB PowerShell package.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/1367","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/users\/13019"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/comments?post=1367"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/1367\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media\/1374"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media?parent=1367"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/categories?post=1367"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/tags?post=1367"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}