使用PowerShell为Azure Cosmos DB创建容器

In many situations, we will develop, test or prove new concepts by horizontally scaling new SQL API containers in Azure Cosmos DB over possibly using existing containers. As we’ve seen in previous tips, we can create and remove Cosmos database accounts and databases by using the Azure Portal or PowerShell’s Az module along with making some updates to the configuration, such as the RUs for performance reasons. Similarly, we can create and remove a container through the Azure Portal along with creating and removing the container with PowerShell’s Az module.

在许多情况下，我们将通过可能使用现有容器的方式在Azure Cosmos DB中水平扩展新SQL API容器来开发，测试或证明新概念。 正如我们在前面的技巧中所看到的，我们可以使用Azure门户或PowerShell的Az模块来创建和删除Cosmos数据库帐户和数据库，并出于性能原因对配置（例如RU）进行一些更新。 同样，我们可以通过Azure门户创建和删除容器，以及使用PowerShell的Az模块创建和删除容器。

We’ll first create a container through the Portal so that we have an idea of what we’ll need for our script before we create and remove a container in PowerShell using its Az module.

我们将首先通过门户网站创建一个容器，以便在使用PowerShell的Az模块在PowerShell中创建和删除容器之前，先了解脚本的需求。

在门户中创建数据库和第一个容器 (Creating the Database and First Container in the Portal)

For automating the creation of a container in our Azure Cosmos DB, we’ll first create our SQL API database and add a container to it through the Azure Portal. Since the portal will show us some options we’ll use, we’ll create both through the portal. We’ll select the option to also provision the RU while we name our database – in this case, ScaleDB with an RU amount of 400 RUs. While we see the message about cost, we’ll only use this database to test the creation of containers so that we can create a template for automation – once we have the template, we can remove the containers and database.

为了在Azure Cosmos DB中自动创建容器，我们首先创建SQL API数据库，然后通过Azure门户向其添加容器。 由于门户将向我们展示我们将使用的一些选项，因此我们将通过门户来创建两者。 我们将选择一个选项来在我们命名数据库的同时预配置RU –在这种情况下，ScaleDB的RU数量为400 RU。 当我们看到有关成本的消息时，我们将仅使用此数据库来测试容器的创建，以便我们可以创建自动化模板–一旦有了模板，就可以删除容器和数据库。

We create a SQL API database in our Azure Cosmos DB.

我们在Azure Cosmos数据库中创建一个SQL API数据库。

Once our SQL API database is created, we’ll select the option to create a container in the database. The below image shows the options when we create the container – Container id (required), partition key (required), checkboxes about the size of the partition key and dedicated provision through the container, and the option to add a unique key. Like the image shows, we’ll only fill in the required boxes for our template.

创建SQL API数据库后，我们将选择在数据库中创建容器的选项。 下图显示了创建容器时的选项-容器ID（必填），分区键（必填），有关分区键大小和通过容器进行专用配置的复选框，以及添加唯一键的选项。 就像图片所示，我们只填写模板所需的框。

After creating our SQL API database, we create the container in our Azure Cosmos DB.

创建SQL API数据库后，我们在Azure Cosmos DB中创建容器。

As we’ll see with the options we’ve selected, these will appear in the settings when the container is created along with other settings we don’t specify, but we’ll need to note when we create our template. This is an important point because if we want a unique key, we’ll need to ensure that this unique key is included in our template and the same if we have a custom throughput that we want to use. To simplify the template creation, I suggest creating the initial container to use the standard options that you want for other containers – especially, if you use multiple containers for scale. This does assume that our initial container will match other containers and we can create differing containers for scripting different templates.

正如我们将看到的那样，选择的选项将在创建容器时与未指定的其他设置一起显示在设置中，但是在创建模板时需要注意。 这一点很重要，因为如果我们想要一个唯一的密钥，我们需要确保此唯一的密钥包含在我们的模板中，如果我们要使用一个自定义的吞吐量，则需要确保该唯一的密钥。 为了简化模板的创建，我建议创建初始容器以使用其他容器想要的标准选项，尤其是在使用多个容器进行缩放时。 这确实假定我们的初始容器将与其他容器匹配，并且我们可以创建不同的容器来编写不同模板的脚本。

Once our container is created within our Azure Cosmos DB, let’s look at the settings of this container in the Setting options under the container itself. We’ll see the option of the last write wins as selected for conflict resolution, conflict resolver property set, time to live as off, our partition key, and Indexing Policies. Remember, that we want our second container to have the same options as this first container’s options when we script it.

在Azure Cosmos数据库中创建容器后，让我们在容器本身下的“设置”选项中查看该容器的设置。 我们将看到为冲突解决，冲突解决程序属性集，生存时间，分区键和索引策略选择的最后一次写入获胜的选项。 请记住，编写脚本时，我们希望第二个容器具有与第一个容器相同的选项。

In Settings under our container in our Azure Cosmos DB, we see the options that we’ll use for our template.

在Azure Cosmos DB中容器下方的设置中，我们将看到将用于模板的选项。

When we look at the Indexing Policy box, we see JSON that has various specifications for our container about the indexing of this container. Because we want our second container to match these specifications, we’ll use a layered hash object to specify these and other settings for the second container’s template. The final option that we see titled excludedPaths we will remove from our hash object, as we’ll see this is automatically added to our second container even when it is not specified. If in doubt about an option, add it unless you’ve confirmed that it will be added.

当我们查看Indexing Policy框时，我们看到JSON，它具有关于该容器的索引的各种规范。 因为我们希望第二个容器符合这些规范，所以我们将使用分层的哈希对象为第二个容器的模板指定这些设置和其他设置。 我们看到的最后一个选项名为“ exclusivePaths” ，将从哈希对象中删除，因为即使没有指定，它也会自动添加到第二个容器中。 如果对某个选项有疑问，请添加它，除非您已确认将要添加。

{
    "indexingMode": "consistent",
    "automatic": true,
    "includedPaths": [
        {
            "path": "/*",
            "indexes": [
                {
                    "kind": "Spatial",
                    "dataType": "Point"
                },
                {
                    "kind": "Range",
                    "dataType": "Number",
                    "precision": -1
                },
                {
                    "kind": "Range",
                    "dataType": "String",
                    "precision": -1
                }
            ]
        }
    ],
    "excludedPaths": [
        {
            "path": "/\"_etag\"/?"
        }
    ]
}

Now that our first container in our Azure Cosmos DB is created through the Azure Portal and we have looked at the settings, we’ll create our template to build the second container through PowerShell.

现在我们已经通过Azure门户在Azure Cosmos DB中创建了第一个容器，并且已经查看了设置，接下来，我们将创建模板以通过PowerShell构建第二个容器。

在PowerShell中创建第二个容器 (Creating the Second Container in PowerShell)

We’ll create our second container using a similar format with PowerShell’s Az module. Like other scripts where we create and remove Cosmos database accounts and databases, we will need to ensure that the Az module is installed. For our container creation script, this time we’ll name some of our objects with shorter names to organize their function – object $srv for server, $db for database and $cont for container. This also helps prevent confusion in our development as our database ($db) exists within a server ($srv) and has a container ($cont); we see this when we specify the -Name parameter in our call and the order these come in – notice how the container follows database, which follows the database type (sql) which follows the server.

我们将使用与PowerShell的Az模块类似的格式创建第二个容器。 与创建和删除Cosmos数据库帐户和数据库的其他脚本一样，我们将需要确保安装了Az模块。 对于容器创建脚本，这一次我们将使用较短的名称来命名一些对象以组织其功能-服务器的对象$ srv ，数据库的$ db和容器的$ cont 。 这也有助于防止开发过程中的混乱，因为我们的数据库（ $ db ）存在于服务器（ $ srv ）内并且具有容器（ $ cont ）； 当我们在调用中指定-Name参数以及它们的输入顺序时，我们会看到这一点–请注意容器如何跟随数据库，后者如何跟随服务器的数据库类型（ sql ）。

 Connect-AzAccount | Out-Null
 
$resource = "Microsoft.DocumentDb/databaseAccounts"
$type = "Microsoft.DocumentDb/databaseAccounts/apis/databases/containers"
$srv = "scosdb"
$db = "ScaleDB"
$cont = "scaletwo"
$api = "2015-04-08"
 
 
$rGroup = (Get-AzResource -ResourceType $resource -Name $srv).ResourceGroupName
 
 
$indexpolicy = @{
    "resource" = @{
        "id"= $cont; 
        "partitionKey" = @{
            "paths" = @("/scaleid"); 
            "kind" = "Hash"
        }; 
        "indexingPolicy" = @{
            "indexingMode" = "consistent"; 
            "includedPaths" = @(@{
                "path" = "/*";
                "indexes" = @(@{
                        "kind" = "Range";
                        "dataType" = "number";
                        "precision" = -1
                    },
                    @{
                        "kind" = "Range";
                        "dataType" = "string";
                        "precision" = -1
                    },
                    @{
                        "kind" = "Spatial";
                        "dataType" = "Point";
                    }
                )
            });
        };
        "conflictResolutionPolicy" = @{
            "mode" = "lastWriterWins"; 
            "conflictResolutionPath" = "/_ts"
        }
    };
} 
 
New-AzResource -ResourceType $type -ApiVersion $api -ResourceGroupName $rGroup -Name "$srv/sql/$db/$cont" -PropertyObject $indexpolicy -Force

In the above options for our container within our Azure Cosmos DB, we see the same selections that we saw when we created our first container in the Azure Portal. There may be times that we want to specify other options and Microsoft has a useful page showing additional options that we can specify, such as the throughput and unique indexes, if both of these are required.

在Azure Cosmos DB中容器的上述选项中，我们看到的与在Azure门户中创建第一个容器时看到的选择相同。 有时我们可能需要指定其他选项，并且Microsoft有一个有用的页面，其中显示了我们可以指定的其他选项，例如吞吐量和唯一索引（如果这两个都需要）。

When we review the template – especially compared to its creation in the Azure Portal, one point we want to consider is the how question of design just like we do with other development. If we use a standard template for our containers in our SQL API databases, designing a template for re-use in automation may save us some time. However, it’s possible each container may differ in our Azure Cosmos DB and this would require that we update the template or create another template to use, if we re-use the second template or intend to. Automation should save us time, so if we have a handful of templates and find ourselves creating containers on a regular basis, we can create the base templates for re-use. On the other hand, if each container will be different and we seldom create containers, the Azure Portal may be faster for our needs.

当我们回顾一下模板-特别是相对于其在Azure门户创建，但有一点我们要考虑的是设计的问题， 怎么就像我们做的与其他发展。 如果我们在SQL API数据库中为容器使用标准模板，那么设计一个可在自动化中重复使用的模板可以为我们节省一些时间。 但是，每个容器在我们的Azure Cosmos数据库中可能会有所不同，并且如果我们重复使用或打算使用第二个模板，则这需要我们更新模板或创建另一个模板以使用。 自动化应该为我们节省时间，因此，如果我们有少量模板，并且发现自己定期创建容器，则可以创建基础模板以供重复使用。 另一方面，如果每个容器都不同，并且我们很少创建容器，则Azure门户可能会更快地满足我们的需求。

We confirm our second container is created in our Azure Cosmos DB in the Azure Portal.

我们确认在Azure门户的Azure Cosmos数据库中创建了第二个容器。

取出容器 (Remove A Container)

Now that we’ve created two containers in for our SQL API database, we’ll remove the first container that we created through the Azure Portal. When we use the function Remove-AzResource, we use the same -ResourceType for creation and removal and follow the same naming convention of specifying the Azure Cosmos DB ($srv), type of Cosmos account (sql), database ($db) and container name ($cont). We specify the -Force parameter to prevent the dialog and the function call removes the container.

现在，我们已经在SQL API数据库中创建了两个容器，我们将删除通过Azure门户创建的第一个容器。 当我们使用函数删除-AzResource，我们使用的创建和删除同一-ResourceType，并按照指定Azure的宇宙DB（$ SRV），类型宇宙账户（SQL），数据库（DB $）的相同的命名约定容器名称（ $ cont ）。 我们指定-Force参数以防止出现对话框，并且函数调用将删除容器。

 $resource = "Microsoft.DocumentDb/databaseAccounts"
$type = "Microsoft.DocumentDb/databaseAccounts/apis/databases/containers"
$srv = "scosdb"
$db = "ScaleDB"
$cont = "scaleone"
$api = "2015-04-08"
 
$rGroup = (Get-AzResource -ResourceType $resource -Name $srv).ResourceGroupName
 
Remove-AzResource -ResourceType $type -ApiVersion $api -ResourceGroupName $rGroup -Name "$srv/sql/$db/$cont" -Force

Following the script call, we get a true as returned output and see that scaleone has been removed when we look at the Azure Portal for confirmation.

在脚本调用之后，我们得到的返回结果为true，并且当我们查看Azure门户进行确认时，看到已删除了scaleone 。

结论 (Conclusion)

In this tip, we’ve created a container within our Azure Cosmos DB through the Azure Portal and through using PowerShell’s Az module. Our first container showed us the options to use for our second container’s template and we looked at options that we could specify for these containers. In addition, we looked at removing the containers we created through our scripts. Throughout this series, we’ve looked at creating and removing Cosmos database accounts, databases within those accounts, and containers. Depending on our testing and development needs, we may scale with any of these tools and use PowerShell for the automation of this scale, or for smaller organizations, we may find the Azure Portal appropriate for the rare situations when we need to scale.

在本技巧中，我们已通过Azure门户并使用PowerShell的Az模块在Azure Cosmos DB中创建了一个容器。 我们的第一个容器向我们展示了用于第二个容器的模板的选项，我们研究了可以为这些容器指定的选项。 另外，我们研究了如何删除通过脚本创建的容器。 在整个系列中，我们研究了如何创建和删除Cosmos数据库帐户，这些帐户中的数据库以及容器。 根据我们的测试和开发需求，我们可以使用其中任何一种工具进行扩展，并使用PowerShell进行这种规模的自动化，或者对于小型组织，我们可能会发现Azure门户适用于需要扩展的罕见情况。

目录 (Table of contents)

翻译自: https://www.sqlshack.com/creating-containers-with-powershell-for-azure-cosmos-db/