cosmosdb_sql_request プラグイン

適用対象: ✅Microsoft Fabric✅Azure データ エクスプローラー✅Azure Monitor✅Microsoft Sentinel

cosmosdb_sql_request プラグインは、Azure Cosmos DB SQL ネットワーク エンドポイントに SQL クエリを送信し、クエリの結果を返します。 このプラグインは、たとえば Azure Cosmos DB に格納されている参照データを使用してデータを強化するような、主に小さなデータセットのクエリを実行するために設計されています。 このプラグインは、evaluate 演算子を使用して呼び出されます。

構文

evaluatecosmosdb_sql_request ( ConnectionString , SqlQuery [, SqlParameters [, Options]] ) [: OutputSchema]

構文規則について詳しく知る。

パラメーター

件名	タイプ	Required	説明
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 リソース ID。 接続文字列引数にアカウント キーが指定されていない場合は、このフィールドが必要です。 このような場合、 armResourceId は Cosmos DB. に対する認証に使用されます。例: armResourceId='/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'
token	string	Cosmos DB データベースにアクセスできるプリンシパルの Microsoft Entra アクセス トークン。 このトークンは、Azure Resource Manager で認証するために armResourceId と共に使用されます。 指定しない場合は、クエリを作成したプリンシパルのトークンが使用されます。 armResourceIdが指定されていない場合、トークンは Cosmos DB データベースへのアクセスに直接使用されます。 トークン認証方法の詳細については、「 認証と承認を参照してください。
preferredLocations	string	データのクエリを実行するリージョン。 例: ['East US']

認証と権限承認

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

認証方法	説明
マネージド ID (推奨)	接続文字列にAuthentication="Active Directory Managed Identity";User Id={object_id};を追加します。 要求は、データベースに対する適切なアクセス許可を持っている必要があるマネージド ID に代わって行われます。 マネージド ID 認証を有効にするには、マネージド ID をクラスターに追加し、マネージド ID ポリシーを変更する必要があります。 詳細については、「 管理 ID ポリシー」を参照してください。
Azure Resource Manager リソース ID	この認証方法では、optionsでarmResourceIdと必要に応じてtokenを指定する必要があります。 armResourceIdは Cosmos DB データベース アカウントを識別し、tokenは Cosmos DB データベースへのアクセス許可を持つプリンシパルの有効な Microsoft Entra ベアラー トークンである必要があります。 tokenが指定されていない場合は、要求元プリンシパルの Microsoft Entra トークンが認証に使用されます。
アカウント キー	アカウント キーは、 ConnectionString 引数に直接追加できます。 ただし、この方法はクエリ テキストにシークレットを含めるので安全性が低く、アカウント キーの将来の変更に対する回復力が低くなります。 セキュリティを強化するには、シークレットを obfuscated 文字列リテラルとして非表示にします。
Token	プラグインにトークン値を追加することができます options。 トークンは、関連するアクセス許可を持つプリンシパルに属している必要があります。 セキュリティを強化するには、トークンを obfuscated 文字列リテラルとして非表示にします。

コールアウト ポリシーの設定

プラグインは、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
  }
]

次の例は、 cosmosdb CalloutType の alter callout policy コマンドを示しています

.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 クエリを送信し、その Azure Cosmos DB for NoSQL を使用して 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 のパートナー データをデータベース内のパートナー データと結合します。 その結果、パートナー名で並べ替えられた電話番号、Web サイト、連絡先のメール アドレスを含むパートナーの一覧が表示されます。

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 にクエリを実行する

次の例では、 Partner フィールドを使用して、Azure Cosmos DB のパートナー データをデータベース内のパートナー データと結合します。 その結果、パートナー名で並べ替えられた電話番号、Web サイト、連絡先のメール アドレスを含むパートナーの一覧が表示されます。

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 リソース ID を使用して Azure Cosmos DB にクエリを実行する

次の例では、認証に Azure Resource Manager リソース ID と要求元プリンシパルの 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)