cosmosdb_sql_request plugin

プラグインは cosmosdb_sql_request 、Azure Cosmos DB SQL ネットワーク エンドポイントに 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'R8PM...;'
SqlQuery	string	✔️	実行するクエリ。
SqlParameters	dynamic		クエリと共にパラメーターとして渡すプロパティ バッグ オブジェクト。 パラメーター名は @ で始まる必要があります。
OutputSchema			プラグイン出力の予想される列の cosmosdb_sql_request 名前と型。 ColumnName:ColumnType [, ...] )の構文(を使用します。 このパラメーターを指定すると、複数のクエリの最適化が有効になります。
[オプション]	dynamic		詳細設定のプロパティ バッグ オブジェクト。 AccountKeyが ConnectionString に指定されていない場合は、armResourceIdこのパラメーターのフィールドが必要です。 詳細については、「 サポートされているオプション」を参照してください。

サポートされているオプション

次の表では、 Options パラメーターのサポートされているフィールドについて説明します。

名前	型	説明
armResourceId	string	Cosmos DB データベースの Azure Resource Manager リソース 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 Resource Managerで認証されます。 指定しない場合は、クエリを作成したプリンシパルのトークンが使用されます。
preferredLocations	string	データのクエリを実行するリージョン。 例：['East US']

認証と承認

Azure Cosmos DB SQL ネットワーク エンドポイントに対して承認するには、承認情報を指定する必要があります。 次の表に、サポートされている認証方法とその使用方法の説明を示します。

認証方法	説明
Azure Resource Manager リソース ID (推奨)	セキュリティで保護された認証を行う場合は、 オプションで と (オプションで) をtoken指定armResourceIdすることをお勧めします。 は 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\\.azure\\.com",
    "CanCall": true
  },
  {
    "CalloutType": "CosmosDB",
    "CalloutUriRegex": "my_endpoint2\\.documents\\.azure\\.com",
    "CanCall": true
  }
]

次の例は、cosmosdbCalloutType のコールアウト ポリシーの変更コマンドを示しています

.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'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.com/;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 クエリ パラメーターを使用し、別のリージョンからデータを照会します。 詳細については、「preferredLocations」を参照してください。

evaluate cosmosdb_sql_request(
    'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;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': ['East US']})) : (Id:long, Name:string, Column0: datetime) 
| where lastName == 'Smith'

この機能は、Azure Monitor ではサポートされていません。