cosmosdb_sql_request 插件
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'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(推荐) | 若要进行安全身份验证,建议在选项中指定 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 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 不支持此功能