GQL クエリ API リファレンス

注

現在、この機能はパブリックプレビュー段階にあります。このプレビュー版はサービスレベルアグリーメントなしで提供されています。運用環境のワークロードに使用することはお勧めできません。特定の機能はサポート対象ではなく、機能が制限されることがあります。詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。

RESTful HTTP API を使用して、Microsoft Fabric のプロパティグラフに対して GQL クエリを実行します。このリファレンスでは、HTTP コントラクト (要求と応答の形式、認証、JSON 結果のエンコード、エラー処理) について説明します。

Important

この記事では、ソーシャルネットワークのグラフデータセットの例のみを使用します。

概要

GQL クエリ API は、JSON ペイロードとして GQL クエリを受け入れ、構造化された型指定された結果を返す単一エンドポイント (RPC over HTTP) です。 API はステートレスであり、認証を処理し、包括的なエラー報告を提供します。

主な機能

単一エンドポイント - すべての操作で HTTP POST を 1 つの URL に使用します。
JSON ベース - 要求と応答のペイロードでは、型指定された GQL 値の豊富なエンコードで JSON が使用されます。
ステートレス - 要求間のセッション状態は必要ありません。
型セーフ - 値表現の判別共用体を使用した厳密な GQL 互換型指定。

[前提条件]

ノードとエッジ (リレーションシップ) を含むデータを含む Microsoft Fabric のグラフが必要です。サンプルグラフを作成して読み込むには、グラフのクイックスタートを参照してください。
実行結果と結果の構造など、プロパティグラフと GQL の基本的な理解を理解している必要があります。
組織にログインするには、 Azure CLI ツール az をインストールして設定する必要があります。この記事のコマンドラインの例では、bash などの POSIX と互換性のあるコマンドラインシェルを使用することを前提としています。

Authentication

GQL クエリ API には、ベアラートークンを使用した認証が必要です。

すべての要求の Authorization ヘッダーにアクセストークンを含めます。

Authorization: Bearer <your-access-token>

一般に、 Microsoft 認証ライブラリ (MSAL) または Microsoft Entra と互換性のある他の認証フローを使用してベアラートークンを取得できます。

ベアラートークンは、通常、次の 2 つの主要なパスを通じて取得されます。

ユーザー委任アクセス

Azure CLI ツール azを使用して、コマンドラインからユーザー委任サービス呼び出しのベアラートークンを取得できます。

次の方法で、コマンドラインからユーザー委任呼び出しのベアラートークンを取得します。

az login を実行する
アクション: az account get-access-token --resource https://api.fabric.microsoft.com

これにより、 Azure CLI ツール azが使用されます。

az restを使用して要求を実行すると、ベアラートークンが自動的に取得されます。

アプリケーションアクセス

Microsoft Entra に登録されているアプリケーションのベアラートークンを取得できます。詳細については、 Fabric API のクイックスタートを参照してください。

API エンドポイント

API は、すべてのクエリ操作を受け入れる単一のエンドポイントを使用します。

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels/{GraphModelId}/executeQuery?preview=true

ワークスペースの {workspaceId} を取得するには、 az restを使用して使用可能なすべてのワークスペースを一覧表示できます。

az rest --method get --resource "https://api.fabric.microsoft.com" --url "https://api.fabric.microsoft.com/v1/workspaces"

{graphId}を取得するには、az restを使用して、ワークスペース内で使用可能なすべてのグラフを一覧表示できます。

az rest --method get --resource "https://api.fabric.microsoft.com" --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels"

より多くのパラメーターを使用して、クエリ結果をさらに絞り込むことができます。

--query 'value[?displayName=='My Workspace'] displayNameのMy Workspaceを持つアイテムのみを一覧表示します。
がで始まるアイテムのみを一覧表示する場合は。
--query '{query}' 指定された JMESPath {query}に一致する項目のみを一覧表示します。でサポートされている構文については、{query}を参照してください。
-o table テーブルの結果を生成します。

注

コマンドラインシェルから API エンドポイントを使用してクエリを実行する方法については、 az-rest の使用に関するセクション、または curl の使用に関するセクションを参照してください。

要求ヘッダー

Header	価値	必須
`Content-Type`	`application/json`	イエス
`Accept`	`application/json`	イエス
`Authorization`	`Bearer <token>`	イエス

要求の形式

すべての要求では、JSON ペイロードと共に HTTP POST が使用されます。

基本的な要求構造

{
  "query": "MATCH (n) RETURN n LIMIT 100"
}

要求フィールド

フィールド	タイプ	必須	Description
`query`	文字列	イエス	実行する GQL クエリ

応答形式

成功した要求のすべての応答では、実行状態と結果を含む JSON ペイロードで HTTP 200 状態が使用されます。

応答構造

{
  "status": {
    "code": "00000",
    "description": "note: successful completion", 
    "diagnostics": {
      "OPERATION": "",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/"
    }
  },
  "result": {
    "kind": "TABLE",
    "columns": [...],
    "data": [...]
  }
}

Status オブジェクト

すべての応答には、実行情報を含む状態オブジェクトが含まれます。

フィールド	タイプ	Description
`code`	文字列	6 文字の状態コード (000000 = 成功)
`description`	文字列	人間が判読できるステータスメッセージ
`diagnostics`	オブジェクト	詳細な診断レコード
`cause`	オブジェクト	基になる原因の状態オブジェクト (省略可能)

状態コード

状態コードは階層パターンに従います。

00xxxx - 成功を完了する
01xxxx - 警告が表示された成功
02xxxx - データのない成功
03xxxx - 情報が含まれた成功
04xxxx 以上 - エラーと例外条件

詳細については、 GQL ステータスコードリファレンスを参照してください。

診断レコード

診断レコードには、状態オブジェクトをさらに詳しく説明する他のキーと値のペアを含めることができます。アンダースコア (_) で始まるキーは、Microsoft Fabric のグラフに固有です。 GQL 標準では、他のすべてのキーが規定されています。

注

Microsoft Fabric のグラフに固有のキーの診断レコードの値は、JSON でエンコードされた GQL 値です。「値の型とエンコード」を参照してください。

原因

基になる原因がわかっている場合、状態オブジェクトにはオプションの cause フィールドが含まれます。

その他の状態オブジェクト

一部の結果では、(省略可能) additionalStatuses フィールドに他の状態オブジェクトをリストとして報告できます。

その場合、GQL 標準で規定されているように、プライマリステータスオブジェクトは常に最も重大なステータスオブジェクト(例外条件など)であると判断されます。

結果の種類

結果では、 kind フィールドで判別共用体パターンが使用されます。

テーブルの結果

表形式のデータを返すクエリの場合:

{
  "kind": "TABLE",
  "columns": [
    {
      "name": "name",
      "gqlType": "STRING",
      "jsonType": "string"
    },
    {
      "name": "age",
      "gqlType": "INT32",
      "jsonType": "number"
    }
  ],
  "isOrdered": true,
  "isDistinct": false,
  "data": [
    {
      "name": "Alice",
      "age": 30
    },
    {
      "name": "Bob",
      "age": 25
    }
  ]
}

省略された結果

データを返さない操作 (カタログやデータの更新など) の場合:

{
  "kind": "NOTHING"
}

値の型とエンコード

API では、リッチ型システムを使用して、正確なセマンティクスで GQL 値を表します。 GQL 値の JSON 形式は、判別共用体パターンに従います。

注

表形式の結果の JSON 形式では、 gqlType と value を分離して判別共用体パターンを実現し、よりコンパクトな表現を実現します。テーブルのシリアル化の最適化を参照してください。

値の構造

{
  "gqlType": "TYPE_NAME",
  "value": <type-specific-value>
}

プリミティブ型

GQL 型	Example	Description
`BOOL`	`{"gqlType": "BOOL", "value": true}`	ネイティブ JSON ブール値
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	UTF-8 文字列

数値型

整数型

GQL 型	範囲	JSON シリアル化	Example
`INT64`	-2⁶ 2⁶ ²-1	数値または文字列*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	0 から 2⁶⁴-1	数値または文字列*	`{"gqlType": "UINT64", "value": 18467}`

JavaScript の安全範囲外の大きな整数 (-9,007,199,254,740,991 ~ 9,007,199,254,740,991) は文字列としてシリアル化されます。

{"gqlType": "INT64", "value": "9223372036854775807"}
{"gqlType": "UINT64", "value": "18446744073709551615"}

浮動小数点型

GQL 型	範囲	JSON シリアル化	Example
`FLOAT64`	IEEE 754 binary64	JSON 番号または文字列	`{"gqlType": "FLOAT64", "value": 3.14}`

浮動小数点値は、IEEE 754 の特殊な値をサポートします。

{"gqlType": "FLOAT64", "value": "Inf"}
{"gqlType": "FLOAT64", "value": "-Inf"}
{"gqlType": "FLOAT64", "value": "NaN"}
{"gqlType": "FLOAT64", "value": "-0"}

テンポラル型

サポートされているテンポラル型では、ISO 8601 文字列形式が使用されます。

GQL 型	Format	Example
`ZONED DATETIME`	YYYY-MM-DDTHH:MM:SS[.ffffff]±HH:MM	`{"gqlType": "ZONED DATETIME", "value": "2023-12-25T14:30:00+02:00"}`

Graph 要素の参照型

GQL 型	Description	Example
`NODE`	グラフノードリファレンス	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	グラフエッジリファレンス	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

複合型

複合型は、他の GQL 値で構成されます。

Lists

リストには、一貫性のある要素型を持つ null 許容値の配列が含まれています。

{
  "gqlType": "LIST<INT64>",
  "value": [1, 2, null, 4, 5]
}

特殊なリストの種類:

LIST<ANY> - 混合型 (各要素には完全な型情報が含まれます)
LIST<NULL> - 許容される null 値のみ
LIST<NOTHING> - 常に空の配列

経路

パスは、グラフ要素の参照値のリストとしてエンコードされます。

{
    "gqlType": "PATH",
    "value": ["node1", "edge1", "node2"]
}

テーブルのシリアル化の最適化を参照してください。

テーブルのシリアル化の最適化

テーブルの結果の場合、値のシリアル化は列の型情報に基づいて最適化されます。

既知の型 - 生の値のみがシリアル化されます
ANY 列 - 型識別子を持つ完全な値オブジェクト

{
  "columns": [
    {"name": "name", "gqlType": "STRING", "jsonType": "string"},
    {"name": "mixed", "gqlType": "ANY", "jsonType": "unknown"}
  ],
  "data": [
    {
      "name": "Alice",
      "mixed": {"gqlType": "INT32", "value": 42}
    }
  ]
}

エラー処理

トランスポートエラー

ネットワークおよび HTTP トランスポートエラーの結果、標準の HTTP エラー状態コード (4xx、5xx) が発生します。

アプリケーションエラー

アプリケーションレベルのエラーでは、常に HTTP 200 が返され、ステータスオブジェクトにエラー情報が表示されます。

{
  "status": {
    "code": "42001",
    "description": "error: syntax error or access rule violation",
    "diagnostics": {
      "OPERATION": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_errorLocation": {
        "gqlType": "STRING",
        "value": "line 1, column 15"
      }
    },
    "cause": {
      "code": "22007",
      "description": "error: data exception - invalid date, time, or, datetime
format",
      "diagnostics": {
        "OPERATION": "query",
        "OPERATION_CODE": "0",
        "CURRENT_SCHEMA": "/"
      }
    }
  }
}

状態チェック

成功を確認するには、状態コードを確認します。

00、01、02で始まるコードは、成功を示03 (警告が表示される可能性があります)
その他のコードはすべてエラーを示します

az rest を使用した完全な例

次のように、ベアラートークンを手動で取得する必要がないように、 az rest コマンドを使用してクエリを実行します。

az rest --method post --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels/{GraphModelId}/executeQuery?preview=true" \
--headers "Content-Type=application/json" "Accept=application/json" \
--resource "https://api.fabric.microsoft.com" \
--body '{ 
  "query": "MATCH (n:Person) WHERE n.birthday > 19800101 RETURN n.firstName, n.lastName, n.birthday ORDER BY n.birthday LIMIT 100" 
}'

curl を使用した完全な例

このセクションの例では、シェルからの HTTPS 要求を実行するために curl ツールを使用します。

次のように、シェル変数に格納されている有効なアクセストークンがあることを前提としています。

export ACCESS_TOKEN="your-access-token-here"

ヒント

有効なベアラートークンを取得する方法については、認証に関するセクションを参照してください。

次のようなクエリを実行します。

curl -X POST "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels/{GraphModelId}/executeQuery?preview=true" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "MATCH (n:Person) WHERE n.birthday > 19800101 RETURN n.firstName, n.lastName, n.birthday ORDER BY n.birthday LIMIT 100" 
  }'

ベストプラクティス

GQL クエリ API を使用する場合は、次のベストプラクティスに従ってください。

エラー処理

常に状態コードを確認 する - HTTP 200 に基づいて成功を想定しないでください。
エラーの詳細を解析 する - デバッグに診断と原因チェーンを使用します。

セキュリティ

HTTPS を使用する - 暗号化されていない接続を介して認証トークンを送信しないでください。
トークンのローテーション - 適切なトークン更新と有効期限処理を実装します。
入力を検証 する - クエリに挿入されたユーザー指定のクエリパラメーターをサニタイズし、適切にエスケープします。

値表現

大きな整数値を処理 する - 整数は、JSON 数値としてネイティブに表現できない場合、文字列としてエンコードされます。
特殊な浮動小数点値を処理する - クエリから返される浮動小数点値は、 Infinity、 -Infinity、または NaN (数値ではない) 値にすることができます。
null 値の処理 - JSON null は GQL null を表します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-11-18

次の方法で共有

GQL クエリ API リファレンス

概要

主な機能

[前提条件]

Authentication

ユーザー委任アクセス

アプリケーション アクセス

API エンドポイント

要求ヘッダー

要求の形式

基本的な要求構造

要求フィールド

応答形式

応答構造

Status オブジェクト

状態コード

診断レコード

原因

その他の状態オブジェクト

結果の種類

テーブルの結果

省略された結果

値の型とエンコード

値の構造

プリミティブ型

数値型

整数型

浮動小数点型

テンポラル型

Graph 要素の参照型

複合型

Lists

経路

テーブルのシリアル化の最適化

エラー処理

トランスポート エラー

アプリケーション エラー

状態チェック

az rest を使用した完全な例

curl を使用した完全な例

ベスト プラクティス

エラー処理

セキュリティ

値表現

関連コンテンツ

フィードバック

その他のリソース

アプリケーションアクセス

トランスポートエラー

アプリケーションエラー

ベストプラクティス