cosmosdb_sql_request 插件

项目
10/02/2024

适用于：✅Azure 数据资源管理器✅Azure Monitor✅Microsoft Sentinel

cosmosdb_sql_request 插件会将 SQL 查询发送到 Azure Cosmos DB SQL 网络终结点，并返回查询的结果。此插件主要为查询小数据集而设计，例如，使用存储在 Azure Cosmos DB 中的参考数据来扩充数据。该插件通过 evaluate 运算符调用。

语法

evaluate cosmosdb_sql_request ( ConnectionString , SqlQuery [, SqlParameters [, Options]] ) [: OutputSchema]

详细了解语法约定。

参数

客户	类型	必需	描述
ConnectionString	`string`	✔️	指向要查询的 Azure Cosmos DB 集合的连接字符串。它必须包括“AccountEndpoint”、“Database”和“Collection”。如果主密钥用于身份验证，则可能包括“AccountKey”。有关详细信息，请参阅身份验证和授权。示例：`'AccountEndpoint=https://cosmosdbacc.documents.azure.cn/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>'`
SqlQuery	`string`	✔️	要执行的查询。
SqlParameters	`dynamic`		要作为参数与查询一起传递的属性包对象。参数名称必须以 `@` 开头。
OutputSchema			`cosmosdb_sql_request` 插件输出的所需列的名称和类型。使用以下语法：`(` ColumnName `:` ColumnType [`,` ...] `)`。指定此参数可启用多个查询优化。
选项	`dynamic`		高级设置的属性包对象。如果未在 ConnectionString 中提供 `AccountKey`，则此参数的 `armResourceId` 字段是必需的。有关详细信息，请参阅支持的选项。

支持的选项

下表描述了 Options 参数支持的字段。

名称	Type	描述
`armResourceId`	`string`	Cosmos DB 数据库的 Azure 资源管理器资源 ID。如果未在连接字符串参数中提供帐户密钥，则此字段是必需的。在这种情况下，将使用 `armResourceId` 向 Cosmos DB 进行身份验证。示例：`armResourceId='/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'`
`token`	`string`	有权访问 Cosmos DB 数据库的主体的 Microsoft Entra 访问令牌。此令牌与 `armResourceId` 一起使用，用于向 Azure 资源管理器进行身份验证。如果未指定此项，则使用进行查询的主体的令牌。如果未指定 `armResourceId`，则使用该令牌直接访问 Cosmos DB 数据库。有关令牌身份验证方法的详细信息，请参阅身份验证和授权。
`preferredLocations`	`string`	要从中查询数据的区域。示例：`['China East 2']`

身份验证和授权

若要向 Azure Cosmos DB SQL 网络终结点进行授权，需要指定授权信息。下表提供了支持的身份验证方法以及如何使用该方法的说明。

身份验证方法	说明
托管标识（建议）	将 `Authentication="Active Directory Managed Identity";User Id={object_id};` 追加到连接字符串。请求是代表托管标识发出的，该标识必须具有对数据库的适当权限。若要启用托管标识身份验证，必须将托管标识添加到群集并更改托管标识策略。有关详细信息，请参阅托管标识策略。
Azure Resource Manager 资源 ID	此身份验证方法需要在选项中指定 `armResourceId` 和 `token`（可选）。 `armResourceId` 标识 Cosmos DB 数据库帐户，并且必须 `token` 是具有 Cosmos DB 数据库访问权限的主体的有效 Microsoft Entra 持有者令牌。如果未提供 `token`，则将使用请求主体的 Microsoft Entra 令牌进行身份验证。
帐户密钥	可以将帐户密钥直接添加到 ConnectionString 参数。但是，此方法要求在查询文本中包含机密，因此不太安全，并且不能灵活应对将来帐户密钥的更改。若要增强安全性，请将机密作为经过模糊处理的字符串字面量隐藏。
令牌	可以在插件选项中添加令牌值。令牌必须属于具有相关权限的主体。为了增强安全性，请将令牌隐藏为模糊字符串字面量。

设置标注策略

该插件会对 Azure Cosmos DB 实例进行标注。请确保群集的标注策略允许对目标 CosmosDbUri 进行 cosmosdb 类型的调用。

以下示例演示如何为 Azure Cosmos DB 定义标注策略。建议将其限制为特定的终结点（my_endpoint1、my_endpoint2）。

[
  {
    "CalloutType": "CosmosDB",
    "CalloutUriRegex": "my_endpoint1\\.documents\\.chinacloudapi\\.cn",
    "CanCall": true
  },
  {
    "CalloutType": "CosmosDB",
    "CalloutUriRegex": "my_endpoint2\\.documents\\.chinacloudapi\\.cn",
    "CanCall": true
  }
]

以下示例显示了针对 cosmosdb CalloutType 的 alter callout policy 命令

.alter cluster policy callout @'[{"CalloutType": "cosmosdb", "CalloutUriRegex": "\\.documents\\.chinacloudapi\\.cn", "CanCall": true}]'

示例

以下示例使用括号中的占位符文本。

使用查询定义的输出架构查询 Azure Cosmos DB

以下示例使用 cosmosdb_sql_request 插件在仅选择特定列时发送 SQL 查询。此查询使用显式架构定义，以便在针对 Cosmos DB 运行实际查询之前进行各种优化。

evaluate cosmosdb_sql_request(
  'AccountEndpoint=https://cosmosdbacc.documents.azure.cn/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>',
  'SELECT c.Id, c.Name from c') : (Id:long, Name:string)

查询 Azure Cosmos DB

以下示例使用 cosmosdb_sql_request 插件发送 SQL 查询，以便使用其 Azure Cosmos DB for NoSQL 从 Azure Cosmos DB 提取数据。

evaluate cosmosdb_sql_request(
  'AccountEndpoint=https://cosmosdbacc.documents.azure.cn/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>',
  'SELECT * from c') // OutputSchema is unknown, so it is not specified. This may harm the performance of the query.

使用参数查询 Azure Cosmos DB

以下示例使用 SQL 查询参数从备用区域查询数据。

evaluate cosmosdb_sql_request(
   'AccountEndpoint=https://cosmosdbacc.documents.azure.cn/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>',
    "SELECT c.id, c.lastName, @param0 as Column0 FROM c WHERE c.dob >= '1970-01-01T00:00:00Z'",
    dynamic({'@param0': datetime(2019-04-16 16:47:26.7423305)}),
    dynamic({'preferredLocations': ['China East 2']})) : (Id:long, Name:string, Column0: datetime) 
| where lastName == 'Smith'

查询 Azure Cosmos DB 并将数据加入数据库表

以下示例使用 Partner 字段联接 Azure Cosmos DB 中的合作伙伴数据与数据库中的合作伙伴数据。它会生成一个合作伙伴列表，其中包含他们的电话号码、网站和联系电子邮件地址，并按合作伙伴名称排序。

evaluate cosmosdb_sql_request(
    'AccountEndpoint=https://cosmosdbacc.documents.azure.cn/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>',
    "SELECT c.id, c.Partner, c. phoneNumber FROM c') : (Id:long, Partner:string, phoneNumber:string) 
| join kind=innerunique Partner on Partner
| project id, Partner, phoneNumber, website, Contact
| sort by Partner

使用令牌身份验证查询 Azure Cosmos DB

evaluate cosmosdb_sql_request(
    'AccountEndpoint=https://cosmosdbacc.documents.azure.cn/;Database=<MyDatabase>;Collection=<MyCollection>;',
    "SELECT c.Id, c.Name, c.City FROM c",
    dynamic(null),
    dynamic({'token': h'abc123...'})
) : (Id:long, Name:string, City:string)

使用 Azure 资源管理器资源 ID 查询 Azure Cosmos DB 进行身份验证

以下示例使用 Azure 资源管理器资源 ID 进行身份验证，并使用请求主体的 Microsoft Entra 令牌（因为未指定令牌）。它在仅选择特定列时发送 SQL 查询并指定明确的架构定义。

evaluate cosmosdb_sql_request(
    'AccountEndpoint=https://cosmosdbacc.documents.azure.cn/;Database=<MyDatabase>;Collection=<MyCollection>;',
    "SELECT c.Id, c.Name, c.City FROM c",
    dynamic({'armResourceId': '/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'})
) : (Id:long, Name:string, City:string)

通过