cosmosdb_sql_request 插件

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

语法

evaluatecosmosdb_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'R8PM...;'
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 进行身份验证。
示例:/subscriptions/a0cd6542-7eaf-43d2-bbdd-b678a869aad1/resourceGroups/ cosmoddbresourcegrouput/providers/Microsoft.DocumentDb/databaseAccounts/cosmosdbacc
token string 有权访问 Cosmos DB 数据库的主体的 Microsoft Entra 访问令牌。 此令牌与 armResourceId 一起用于向 Azure 资源管理器进行身份验证。 如果未指定此项,则使用进行查询的主体的令牌。
preferredLocations string 要从中查询数据的区域。 示例:
['China East 2']

身份验证和授权

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

身份验证方法 说明
Azure 资源管理器资源 ID(推荐) 若要进行安全身份验证,建议在选项中指定 armResourceIdtoken(可选)。 armResourceId 可标识 Cosmos DB 数据库帐户,token 应该是对 Cosmos DB 数据库拥有访问权限的主体的有效 Microsoft Entra 持有者令牌。 如果未提供 token,则将使用请求主体的 Microsoft Entra 令牌进行身份验证。
帐户密钥 可以将帐户密钥直接添加到 ConnectionString 参数。 但是,此方法要求在查询文本中包含机密,因此不太安全,并且不能灵活应对将来帐户密钥的更改。 若要增强安全性,请将机密作为经过模糊处理的字符串字面量隐藏。

设置标注策略

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

以下示例演示如何为 Azure Cosmos DB 定义标注策略。 建议将其限制为特定的终结点(my_endpoint1my_endpoint2)。

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

以下示例为一条针对 cosmosdb CalloutType 更改标注策略的命令

.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'R8PM...;',
  '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'R8PM...;',
  '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'R8PM...;',
    "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 Monitor 不支持此功能