cosmosdb_sql_request 外掛程式

發行項
10/15/2024

適用於：✅Microsoft網狀架構✅Azure 數據 ✅總管 Azure 監視器 ✅Microsoft Sentinel

外掛程式 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.com/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>'`
SqlQuery	`string`	✔️	要執行的查詢。
SqlParameters	`dynamic`		要隨著查詢一起傳遞為參數的屬性包物件。參數名稱的開頭 `@`必須是。
OutputSchema			外掛程式輸出之預期 `cosmosdb_sql_request` 數據行的名稱和類型。使用下列語法： `(` ColumnName`:` ColumnType [`,` ...] `)`。指定此參數可啟用多個查詢優化。
選項	`dynamic`		進階設定的屬性包物件。 `AccountKey`如果 ConnectionString 中未提供，則需要`armResourceId`此參數的字段。如需詳細資訊，請參閱支援的選項。

支援的選項

下表描述 Options 參數支援的欄位。

名稱	類型	描述
`armResourceId`	`string`	Cosmos DB 資料庫的 Azure Resource Manager 資源識別符。如果未在連接字串自變數中提供帳戶密鑰，則需要此字段。在這種情況下， `armResourceId` 會用來向Cosmos DB進行驗證。例： `armResourceId='/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'`
`token`	`string`	具有 Cosmos DB 數據庫存取權之主體的 Microsoft Entra 存取令牌。此令牌會與搭配 `armResourceId` 使用，以向 Azure Resource Manager 進行驗證。如果未指定，則會使用建立查詢之主體的令牌。如果未 `armResourceId` 指定，則會直接使用令牌來存取 Cosmos DB 資料庫。如需令牌驗證方法的詳細資訊，請參閱驗證和授權。
`preferredLocations`	`string`	要從中查詢數據的區域。範例： `['East US']`

驗證與授權

若要授權 Azure Cosmos DB SQL 網路端點，您必須指定授權資訊。下表提供支持的驗證方法，以及如何使用該方法的描述。

驗證方法	描述
受控識別（建議）	附加`Authentication="Active Directory Managed Identity";User Id={object_id};`至連接字串。要求是代表受控識別提出，此身分識別必須具有資料庫的適當許可權。若要啟用受控識別驗證，您必須將受控識別新增至叢集，並變更受控識別原則。如需詳細資訊，請參閱受控識別原則。
Azure Resource Manager 資源識別符	此驗證方法需要在選項中指定 `armResourceId` 與選擇性`token`的。會 `armResourceId` 識別 Cosmos DB 資料庫帳戶，而且 `token` 必須是具有 Cosmos DB 資料庫存取許可權之主體的有效Microsoft Entra 持有人令牌。 `token`如果未提供，則要求主體的 Microsoft Entra 令牌將用於驗證。
帳戶金鑰	您可以將帳戶金鑰直接新增至 ConnectionString 自變數。不過，此方法較不安全，因為它牽涉到在查詢文字中包含秘密，而且對帳戶密鑰的未來變更較不具彈性。若要增強安全性，請將秘密隱藏為模糊字串常值。
Token	您可以在外掛程式選項中新增權杖值。令牌必須屬於具有相關許可權的主體。若要增強安全性，請將令牌隱藏為模糊字串常值。

設定註標原則

外掛程式會向 Azure Cosmos DB 實例發出註標。請確定叢集的註標原則會啟用目標 CosmosDbUri 類型的cosmosdb呼叫。

下列範例示範如何定義 Azure Cosmos DB 的註標原則。建議將它限制為特定端點（my_endpoint1， my_endpoint2。

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

下列範例顯示 CalloutType 的cosmosdb改變註標原則命令

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

範例

下列範例使用方括弧中的佔位元文字。

使用查詢定義的輸出架構查詢 Azure Cosmos DB

下列範例會 使用 cosmosdb_sql_request 外掛程式在只選取特定數據行時傳送 SQL 查詢。此查詢會使用明確的架構定義，在對 Cosmos DB 執行實際查詢之前允許各種優化。

evaluate cosmosdb_sql_request(
  'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;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 查詢，以使用適用於 NoSQL 的 Azure Cosmos DB 從 Azure Cosmos DB 擷取數據。

evaluate cosmosdb_sql_request(
  'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;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 查詢參數，並從替代區域查詢數據。如需詳細資訊，請參閱preferredLocations。

evaluate cosmosdb_sql_request(
   'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;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': ['East US']})) : (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.com/;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.com/;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 Resource Manager 資源識別碼來查詢 Azure Cosmos DB 以進行驗證

下列範例會使用 Azure Resource Manager 資源標識符進行驗證，以及要求主體的 Microsoft Entra 令牌，因為未指定令牌。它只會在選取特定數據行時傳送 SQL 查詢，並指定明確的架構定義。

evaluate cosmosdb_sql_request(
    'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;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)

共用方式為