获取和更新Azure Cosmos DB的连接信息

After we set up our Azure Cosmos DB, we may want to get, add to, or update existing properties. We may use some of the get functionality that PowerShell provides to dynamically save values to encrypted configuration files or tables that we use for application purposes and this functionality could be added to the creation of the Cosmos database account, or a separate step in addition to the creation. In secure contexts, this ensures security without the properties after passing through human eyes since they are saved directly to an encrypted location. In the same manner, we may want to regenerate the keys for the account and save the connection strings with the new keys.

设置Azure Cosmos数据库之后，我们可能想要获取，添加或更新现有属性。 我们可能会使用PowerShell提供的一些get功能将值动态保存到我们用于应用程序目的的加密配置文件或表中，并且该功能可以添加到Cosmos数据库帐户的创建中，也可以添加到单独的步骤中。创建。 在安全的上下文中，这确保了安全性，因为这些属性被直接保存到加密位置，因此在通过人眼后不会出现任何属性。 以同样的方式，我们可能要重新生成该帐户的密钥，并用新密钥保存连接字符串。

For the sake of examples in this tip, we’ll show keys to demonstrate the functionality of these PowerShell scripts with Azure Cosmos DB. In secure settings, we want to save these values directly to their location (file, table, encrypted storage, etc), if we have a target for our obtaining these properties.

出于本技巧示例的目的，我们将显示一些密钥，以演示Azure PowerShell Cosmos DB中这些PowerShell脚本的功能。 在安全设置中，如果我们有获取这些属性的目标，则希望将这些值直接保存到它们的位置（文件，表，加密的存储等）。

检查依存关系 (Dependencies to Check)

Identical to the create and remove of a Cosmos database account, these scripts require PowerShell’s Az module. In addition, we can either create a new Cosmos database account (done for this tip), or we can use an existing account for these scripts to get the properties (such as the Azure Cosmos DB we created in the first part of this series). For security reasons, I recommend testing with a new account and not an existing account if the existing account is being used for any other purposes outside of testing.

与创建和删除Cosmos数据库帐户相同，这些脚本需要PowerShell的Az模块。 此外，我们可以创建一个新的Cosmos数据库帐户（此技巧已完成），也可以使用这些脚本的现有帐户来获取属性（例如在本系列的第一部分中创建的Azure Cosmos DB） 。 出于安全原因，如果测试以外的其他目的使用了现有帐户，则建议使用新帐户而不是现有帐户进行测试。

Once we have the correct module installed, we will connect to Azure using the below PowerShell call. Throughout this tip, we will not log in again but re-use the same PowerShell session. If you close the PowerShell session, another login will be required. In addition, we will also see where we can get and update this information through the Azure Portal, since the portal can be appropriate in organizations where there are few resources.

一旦安装了正确的模块，我们将使用下面的PowerShell调用连接到Azure。 在本技巧中，我们将不再重新登录，而是重新使用同一PowerShell会话。 如果关闭PowerShell会话，则需要再次登录。 此外，由于该门户适用于资源很少的组织，因此我们还将看到可以通过Azure门户获取和更新此信息的位置。

Connect-AzAccount

获取连接字符串 (Get Connection Strings)

In the Azure Portal, we can get the connection string and key information (along with regenerating keys) from the Keys option under Settings. In the below images, the most of actual keys are removed and you will see different keys when you look at your Cosmos account. We’ll also note in the two images that we have read-write keys and read-only keys.

在Azure门户中，我们可以从“设置”下的“密钥”选项中获取连接字符串和密钥信息（以及重新生成密钥）。 在下面的图像中，大多数实际密钥被删除，当您查看自己的Cosmos帐户时，您会看到不同的密钥。 我们还将在两个图像中注意到我们有读写键和只读键。

We will need the connection string for applications to connect and use the Azure Cosmos DB. In smaller contexts where we may only have one or two Cosmos database accounts, we can get this information through the portal – though security even in these contexts is a risk (screen grabbing malware or keyloggers). Automating the retrieval of this information, especially after a set up so that it can be stored in a secured location for configuration use (files, tables, encrypted storage, etc) ensures strict security over allowing this information to pass through a user. The unfortunately reality with security is that malware can include screenshot attacks, internal users can sometimes compromise environments, and other attacks may occur from sophisticated malware. Automation of saving credentials reduces these attacks along with saving time, especially during the setup.

我们将需要应用程序的连接字符串来连接和使用Azure Cosmos DB。 在较小的情况下，我们可能只有一个或两个Cosmos数据库帐户，我们可以通过门户网站获取此信息-尽管即使在这些情况下也存在安全风险（抓屏恶意软件或键盘记录程序）。 自动检索此信息，尤其是在设置之后，可以自动将其存储在安全的位置以供配置使用（文件，表，加密的存储等），从而确保了严格的安全性，以防止该信息通过用户。 不幸的是，安全性的现实是恶意软件可能包括屏幕快照攻击，内部用户有时可能会破坏环境，而其他攻击也可能来自复杂的恶意软件。 自动保存凭据可以减少这些攻击并节省时间，尤其是在设置过程中。

In the below script, we get the connection strings for our Azure Cosmos DB by saving the connectionStrings property to a variable and returning the variable. We’ll see that four connection strings return.

在下面的脚本中，通过将connectionStrings属性保存到变量并返回该变量，我们获得了Azure Cosmos DB的连接字符串。 我们将看到四个连接字符串返回。

$api = "2015-04-08"
$rGroup = "OurResourceGroup"
$cosmosdb = "scosdb"
 
$scons = (Invoke-AzResourceAction -Action listConnectionStrings `
    -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion $api -ResourceGroupName $rGroup `
    -Name $cosmosdb -Force).connectionStrings 
 
$scons.connectionString

When we look at the results from the Azure portal, we see that the first two returned are the read and write keys with the second two keys being the read only keys. For demarcating these, we’ll get these individually by specifying their location in the object (inherited from System.Array). The comments only specify what the keys are for clarification.

当我们查看Azure门户的结果时，我们看到返回的前两个键是读写键，后两个键是只读键。 为了对它们进行分界，我们将通过指定它们在对象中的位置（从System.Array继承）来单独获取它们。 注释仅指定要澄清的键。

### Read-Write keys
$scons.connectionString[0]
$scons.connectionString[1]
 
### Read-Only keys
$scons.connectionString[2]
$scons.connectionString[3]

If we wanted to save the read-write connection strings, we would access the first two and we’d make the appropriate adjustments if we only wanted the ready connection strings.

如果我们要保存读写连接字符串，则可以访问前两个字符串，如果只希望使用就绪的连接字符串，则可以进行适当的调整。

重新生成并获取密钥 (Regenerate and Get Keys)

For security purposes, we may want to regenerate keys on a schedule and update these keys for our Azure Cosmos DB. We can mirror standard password policies of updating keys every periodic cadence and follow the practices we used in the above code of saving this information directly to a secured location for configuration use. Depending on our design of regenerating keys and saving these keys, we want to thoroughly test this as it’s possible this could introduce outages if we haven’t ensured that no part of the regeneration and save fails (for instance, the script regenerates the key, but the save to the secured location fails, meaning that configurations will still use old values).

为了安全起见，我们可能希望按计划重新生成密钥，并为Azure Cosmos DB更新这些密钥。 我们可以镜像标准密码策略，以定期更新密钥，并遵循上面代码中使用的做法，将信息直接保存到安全位置以进行配置。 根据我们重新生成密钥并保存这些密钥的设计，我们要进行彻底的测试，因为如果我们不能确保没有一部分重新生成和保存失败（例如，脚本重新生成密钥，但保存到安全位置失败，这意味着配置仍将使用旧值。

In the below code, we regenerate the Azure Cosmos DB secondary key and write it out on screen, which we do only for testing purposes in this tip (the first two characters are shown to confirm it differs from the above two characters). Our logic of updating the secondary key first is the following, if we assume that the primary key is used for our application:

在下面的代码中，我们重新生成Azure Cosmos DB辅助密钥并将其写在屏幕上，在本技巧中，我们仅出于测试目的进行此操作（显示前两个字符以确认它与以上两个字符不同）。 如果我们假设主键用于我们的应用程序，那么我们首先更新辅助键的逻辑如下：

• Regenerate the secondary key, save it to the secured location, and test the key. In this tip, we’ll only verify that the key has been updated by reviewing the first two characters to demonstrate the functionality
  重新生成辅助密钥，将其保存到安全位置，然后测试密钥。 在本技巧中，我们将仅通过检查前两个字符以演示功能来验证密钥是否已更新。
• If the update to the secondary key passes, update the primary key following the same process of regeneration, saving to a secured location, and testing. Updating the primary key follows the same process of updating the secondary key in Azure Cosmos DB except its name
  如果通过了对次要密钥的更新，请按照相同的重新生成过程将主密钥更新，保存到安全的位置并进行测试。 除了主键的名称之外，更新主键的过程与更新Azure Cosmos DB中的辅助键的过程相同。
• We can follow this same process if we want to regenerate the read only keys where we update one before the other. In this tip, we’ll see how to update the secondary read only key
  如果我们要重新生成只读密钥，然后在其中一个更新另一个，我们可以遵循相同的过程。 在本技巧中，我们将看到如何更新辅助只读密钥

If the testing of the secondary key regeneration fails, we would switch back to the primary key (this can be coded logically for testing).

如果对次要密钥再生的测试失败，我们将切换回主键（可以对其进行逻辑编码以进行测试）。

$api = "2015-04-08"
$rGroup = "OurResourceGroup"
$cosmosdb = "scosdb"
$regenerate = @{"keyKind"="secondary"}
 
$2key = Invoke-AzResourceAction -Action regenerateKey `
    -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion $api -ResourceGroupName $rGroup `
    -Name $cosmosdb -Parameters $regenerate
 
Write-Host $2key.secondaryMasterKey

We can see that we can specify the key we want to update in the regenerate object – in the above script, we update the secondary key. What if we wanted to update the secondary read only key? In this case, we wouldn’t specify primary or secondary, but secondaryReadOnly in the regenerate object. In the below script, we run a similar regenerate and update the secondary read only key and return this value.

我们可以看到，我们可以在重新生成对象中指定要更新的密钥-在上面的脚本中，我们更新了辅助密钥。 如果我们要更新辅助只读密钥怎么办？ 在这种情况下，我们将不指定主对象或辅助对象，而是在重新生成对象中指定secondaryReadOnly。 在下面的脚本中，我们运行类似的重新生成并更新辅助只读密钥并返回此值。

$api = "2015-04-08"
$rGroup = "OurResourceGroup"
$cosmosdb = "scosdb"
$regenerate = @{"keyKind"="secondaryReadOnly"}
 
$2key = Invoke-AzResourceAction -Action regenerateKey `
    -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion $api -ResourceGroupName $rGroup `
    -Name $cosmosdb -Parameters $regenerate
 
Write-Host $2key.secondaryReadonlyMasterKey

The same logic applies to changing the primary key or primary read only key – we would simply replace secondary with primary (primary or primaryReadOnly) and regenerate the keys. Now that we’ve regenerated the secondary and secondary read only keys in our Azure Cosmos DB, we’ll call our previous function to get the connection string information and return the set of secondary keys only to confirm that both connection strings are updated with the regenerated keys.

同样的逻辑适用于更改主键或主只读键–我们只需用主键（primary或​​primaryReadOnly）替换secondary并重新生成键即可。 现在，我们已经在Azure Cosmos DB中重新生成了二级和二级只读密钥，我们将调用上一个函数来获取连接字符串信息，并返回一组二级密钥，仅用于确认两个连接字符串均已使用重新生成的密钥。

$api = "2015-04-08"
$rGroup = "OurResourceGroup"
$cosmosdb = "scosdb"
 
$scons = (Invoke-AzResourceAction -Action listConnectionStrings `
    -ResourceType "Microsoft.DocumentDb/databaseAccounts" -ApiVersion $api -ResourceGroupName $rGroup `
    -Name $cosmosdb -Force).connectionStrings 
 
### Secondary keys only
$scons.connectionString[1]
$scons.connectionString[3]

结论 (Conclusion)

We’ve seen that with PowerShell and the Az module we can get and update properties such as the keys and connection strings for our Azure Cosmos DB. With these tools, we can get the connection string or connection key information and pass it into a secure location without accessing it, if we need these values upon creation saved securely. Likewise, we can use these calls to get these values dynamically if they’re needed for a short period of time, such as a unit or security test. In a similar manner, we can regenerate keys, if we want to change the keys for security reasons (seasonal rotations, proactive security, updates, etc).

我们已经看到，通过PowerShell和Az模块，我们可以获取和更新属性，例如Azure Cosmos DB的键和连接字符串。 使用这些工具，如果我们需要在创建时将这些值安全地保存下来，则可以获取连接字符串或连接密钥信息并将其传递到安全的位置而无需访问它。 同样，如果在短时间内需要使用这些值（例如单元测试或安全测试），我们可以使用这些调用动态获取这些值。 如果出于安全原因（季节轮换，主动安全性，更新等）而要更改密钥，则可以类似的方式重新生成密钥。

Keep in mind that we still want to consider when we use these scripts to get this information, how this information will be stored securely, and how we’ll avoid any outages if we make updates. PowerShell adds significant power to our Azure Cosmos DB automation and we still have to consider the best practices for our design.

请记住，我们仍然想考虑何时使用这些脚本来获取此信息，如何安全地存储此信息以及在进行更新时如何避免任何中断。 PowerShell为我们的Azure Cosmos数据库自动化增加了强大的功能，我们仍然必须考虑设计的最佳实践。

目录 (Table of contents)

Creating and Removing Azure Cosmos DBs with PowerShell

Getting and Updating Connection Information for Azure Cosmos DB

Creating and Removing Databases with PowerShell In Azure Cosmos DB

Increasing or Decreasing Scale for Azure Cosmos DB

Creating Containers with PowerShell For Azure Cosmos DB

使用PowerShell创建和删除Azure Cosmos数据库

获取和更新Azure Cosmos DB的连接信息

在Azure Cosmos DB中使用PowerShell创建和删除数据库

增加或减少Azure Cosmos DB的规模

使用PowerShell为Azure Cosmos DB创建容器

翻译自: https://www.sqlshack.com/getting-and-updating-connection-information-for-azure-cosmos-db/