gql_request プラグイン

gql_request プラグインは、Microsoft Fabricのグラフに対して ISO Graph クエリ言語 (GQL) クエリを実行し、結果をテーブルとして返します。 標準の Kusto クエリ言語 (KQL) 演算子を使用して、返されたテーブルを処理します。 evaluate 演算子を使用してプラグインを呼び出します。

プラグインは、Microsoft Fabric GQL クエリ API を使用します。 必要に応じて、予想される出力スキーマを宣言できます。 指定すると、スキーマ検出中に追加の GQL クエリが回避されます。

Note

このプラグインでは、Graph クエリ言語 (GQL) を使用して、API クエリ言語である GraphQL ではなく、Fabricグラフに対してクエリを実行します。

Note

gql_request プラグインはプレビュー段階です。

Prerequisites

  • データを含むMicrosoft Fabric グラフ。 サンプル グラフを作成して読み込むには、 Graph のクイック スタートを参照してください。
  • Fabric ワークスペース内のグラフに対してクエリを実行するアクセス許可。
  • クラスター吹き出しポリシーでは、Fabric Graph GQL 要求の吹き出しをapi.fabric.microsoft.comに許可する必要があります。 このポリシーを変更するには、 AllDatabasesAdmin または Ops アクセス許可が必要です。

Syntax

evaluate gql_request ( ConnectionString,GqlQuery) [:OutputSchema]

構文規則の詳細については、 リファレンス ドキュメントの構文規則を参照してください。

Parameters

氏名 タイプ Required Description
コネクションストリング string Yes Fabricグラフ モデルの URL の後に;Impersonate。 サポートされている形式については、「 接続文字列」を参照してください。
GqlQuery string Yes グラフに対して実行する GQL クエリ。
OutputSchema - - 予想される出力列の名前と型。 構文 (ColumnName:ColumnType [, ...])を使用します。

Note

特に GQL クエリで行が返されない場合は、 OutputSchema を指定することをお勧めします。 これにより、Kusto は、スキーマの検出中にクエリを実行することなく、プラグインの出力列と型を決定できます。 返されたスキーマが宣言されたスキーマと互換性がない場合、プラグインはエラーを返します。

接続文字列

Fabricグラフ モデルの URL の後に、;Impersonate認証ディレクティブを指定します。

https://api.fabric.microsoft.com/v1/workspaces/<WorkspaceId>/GraphModels/<GraphModelId>;Impersonate

WorkspaceId と GraphModelId は有効な GUID である必要があります。

認証と承認

プラグインは、Microsoft Entraの代理認証を使用します。 エンジンは、要求するユーザーのトークンを取得し、そのユーザーのセキュリティ コンテキストでグラフにクエリを実行します。 ユーザーはグラフに対するアクセス許可を持っている必要があります。

認証ディレクティブとして ;Impersonate を使用します。 マネージド ID、サービス プリンシパル、アプリケーション キー認証はサポートされていません。

Important

機密情報を含む 文字列には、難読化された文字列リテラル を使用します。 難読化された値は、Kusto トレースには表示されません。

吹き出しポリシーを構成する

プラグインは、Microsoft Fabricへの外部呼び出しを行います。 既定の吹き出しポリシーは Graph GQL 要求コールアウトFabricブロックするため、クラスター管理者はFabric エンドポイントを明示的に許可する必要があります。

次のコマンドは、制限の厳しいFabric Graph GQL 要求ルールを既存のクラスター吹き出しポリシーにマージします。

.alter-merge cluster policy callout @'[{
    "CalloutType": "gql", 
    "CalloutUriRegex": "api\\.fabric\\.microsoft\\.com/.*", 
    "CanCall": true
}]'

ポリシーを確認します。

.show cluster policy callout

Returns

プラグインは、GQL クエリの結果を KQL テーブルとして返します。 OutputSchema を指定する場合、返される列は宣言されたスキーマと互換性がある必要があります。 予測可能な結果を得るには、ノード、エッジ、またはパス全体を返すのではなく、GQL クエリに必要なプロパティを投影します。

例

グラフから行を返す

この例では、グラフにfirstNameプロパティとlastNameプロパティを持つPersonノードが含まれていることを前提としています。 最大 100 個の名前が返されます。

evaluate gql_request(
  'https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/graphModels/<graph-model-id>;Impersonate',
  @'MATCH (p:Person)
    RETURN p.firstName AS firstName, p.lastName AS lastName
    LIMIT 100')
  : (firstName:string, lastName:string)

Kusto を使用して GQL の結果を処理する

次の例では、各CityにLIVES_INリレーションシップを持つPersonノードをカウントし、KQL を使用して、10 人以上の都市をカウント順に表示します。 グラフには、LIVES_INリレーションシップによって接続されたPersonノードとCityノードが含まれていることを前提としています。

evaluate gql_request(
  'https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/GraphModels/<graph-model-id>;Impersonate',
  @'MATCH (p:Person)-[:LIVES_IN]->(c:City)
    RETURN c.name AS city, count(DISTINCT p) AS PersonCount')
  : (city:string, PersonCount:long)
| where PersonCount > 10
| order by PersonCount desc

これは都市名ごとに個別のユーザーをカウントします。名前を共有する都市はグループ化されます。

Tip

可能な場合は、GQL のデータをフィルター処理、プロジェクト化、および制限して、Kusto に返されるデータの量を減らします。

Troubleshooting

このプラグインは、トランスポート エラーと GQL アプリケーション エラーを区別します。 GQL アプリケーション エラーは、HTTP 200 応答で到着する可能性があります。 プラグインは応答状態を評価し、使用可能な状態コード、説明、入れ子になった原因を含み、エラーをクエリ エラーとして返します。

次の表に、プラグインによって返される一般的なエラーと、考えられる原因と解決策を示します。

Error 原因と解決策
無効な接続文字列 接続文字列がサポートされている形式に従っており、ワークスペースとグラフ モデルの ID が有効な GUID であり、文字列が;Impersonateで終わることを確認します。 URL には、 /executeQuery 、クエリ パラメーター、またはフラグメントを含めないでください。 このプラグインは、API エンドポイントを内部的に構築します。
出力スキーマの不一致 宣言された列名と KQL 型が GQL の結果の列と型と互換性があることを確認します。
サポートされていない GQL の結果の種類 GQL クエリで個々のスカラー プロパティをProjectします。 複雑な値の場合は、GQL TO_JSON_STRING を使用して文字列表現を返す方法を検討してください。
吹き出しは許可されていません クラスターのコールアウト ポリシーを構成して、api.fabric.microsoft.comFabric Graph GQL 要求の呼び出しを許可します。
認証または承認エラー 呼び出し元 ID がワークスペースとグラフにアクセスできることを確認します。
HTTP 要求エラー サービスMicrosoft Fabric可用性、エンドポイントのアクセシビリティ、調整応答を確認します。
GQL クエリ エラー GQL 状態の説明、診断、入れ子になった原因 (使用可能な場合) など、クエリ エラーの詳細を確認します。