cosmosdb_sql_request 插件cosmosdb_sql_request plugin

cosmosdb_sql_request 插件会将 SQL 查询发送到 Cosmos DB SQL 网络终结点,并返回查询的结果。The cosmosdb_sql_request plugin sends a SQL query to a Cosmos DB SQL network endpoint and returns the results of the query. 此插件主要为查询小数据集而设计,例如,使用存储在 Azure Cosmos DB 中的参考数据来扩充数据。This plugin is primarily designed for querying small datasets, for example, enriching data with reference data stored in Azure Cosmos DB.

语法Syntax

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

参数Arguments

参数名称Argument name 说明Description 必需/可选Required/optional
ConnectionStringConnectionString 一个表示连接字符串的 string 文本,该连接字符串指向要查询的 Cosmos DB 集合。A string literal indicating the connection string that points to the Cosmos DB collection to query. 它必须包括“AccountEndpoint”、“Database”和“Collection”。It must include AccountEndpoint, Database, and Collection. 如果主密钥用于身份验证,则可能包括“AccountKey”。It may include AccountKey if a master key is used for authentication.
示例: 'AccountEndpoint=https://cosmosdbacc.documents.azure.com:443/ ;Database=MyDatabase;Collection=MyCollection;AccountKey=' h'R8PM...;'Example: 'AccountEndpoint=https://cosmosdbacc.documents.azure.com:443/ ;Database=MyDatabase;Collection=MyCollection;AccountKey=' h'R8PM...;'
必须Required
SqlQuerySqlQuery 一个 string 文本,指示要执行的查询。A string literal indicating the query to execute. 必须Required
SqlParametersSqlParameters dynamic 类型的常数值,用于保存作为参数随查询传递的键值对。A constant value of type dynamic that holds key-value pairs to pass as parameters along with the query. 参数名称必须以 @ 开头。Parameter names must begin with @. 可选Optional
选项Options dynamic 类型的常数值,它将更高级的设置保存为键值对。A constant value of type dynamic that holds more advanced settings as key-value pairs. 可选Optional
----支持的选项设置包括:---------Supported Options settings include:-----
armResourceId 从 Azure 资源管理器检索 API 密钥Retrieve the API key from the Azure Resource Manager
示例: /subscriptions/a0cd6542-7eaf-43d2-bbdd-b678a869aad1/resourceGroups/ cosmoddbresourcegrouput/providers/Microsoft.DocumentDb/databaseAccounts/cosmosdbaccExample: /subscriptions/a0cd6542-7eaf-43d2-bbdd-b678a869aad1/resourceGroups/ cosmoddbresourcegrouput/providers/Microsoft.DocumentDb/databaseAccounts/cosmosdbacc
token 提供用于通过 Azure 资源管理器进行身份验证的 Azure AD 访问令牌。Provide the Azure AD access token used to authenticate with the Azure Resource Manager.
preferredLocations 控制从哪个区域查询数据。Control which region the data is queried from.
示例: ['China East2']Example: ['China East2']

设置标注策略Set callout policy

该插件会对 Cosmos DB 进行标注。The plugin makes callouts to the Cosmos DB. 请确保群集的标注策略允许对目标 CosmosDbUri 进行 cosmosdb 类型的调用。Make sure that the cluster's callout policy enables calls of type cosmosdb to the target CosmosDbUri.

以下示例演示如何为 Cosmos DB 定义标注策略。The following example shows how to define the callout policy for Cosmos DB. 建议将其限制为特定的终结点(my_endpoint1my_endpoint2)。It's recommended to restrict it to specific endpoints (my_endpoint1, my_endpoint2).

[
  {
    "CalloutType": "CosmosDB",
    "CalloutUriRegex": "my_endpoint1.documents.azure.com",
    "CanCall": true
  },
  {
    "CalloutType": "CosmosDB",
    "CalloutUriRegex": "my_endpoint2.documents.azure.com",
    "CanCall": true
  }
]

以下示例显示了针对 cosmosdb CalloutType 的 alter callout policy 命令The following example shows an alter callout policy command for cosmosdb CalloutType

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

示例Examples

查询 Cosmos DBQuery Cosmos DB

以下示例使用 cosmosdb_sql_request 插件发送 SQL 查询,以便使用其 SQL API 从 Cosmos DB 提取数据。The following example uses the cosmosdb_sql_request plugin to send a SQL query to fetch data from Cosmos DB using its SQL API.

evaluate cosmosdb_sql_request(
  'AccountEndpoint=https://cosmosdbacc.documents.azure.com:443/;Database=MyDatabase;Collection=MyCollection;AccountKey=' h'R8PM...;',
  'SELECT * from c')

使用参数查询 Cosmos DBQuery Cosmos DB with parameters

以下示例使用 SQL 查询参数从备用区域查询数据。The following example uses SQL query parameters and queries the data from an alternate region. 有关详细信息,请参阅 preferredLocationsFor more information, see preferredLocations.

evaluate cosmosdb_sql_request(
    'AccountEndpoint=https://cosmosdbacc.documents.azure.com:443/;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 East2']}))
| where lastName == 'Smith'

Azure Monitor 不支持此功能This capability isn't supported in Azure Monitor