Справочник по API запросов GQL

Замечание

Эта функция сейчас доступна в общедоступной предварительной версии. Эта предварительная версия предоставляется без соглашения на уровне обслуживания и не рекомендуется для рабочих нагрузок. Некоторые функции могут не поддерживаться или их возможности могут быть ограничены. Для получения дополнительной информации см. Дополнительные условия использования для предварительных версий Microsoft Azure.

Выполнение запросов GQL к графам свойств в Microsoft Fabric с помощью API RESTful HTTP. В этой ссылке описывается http-контракт: форматы запросов и ответов, проверка подлинности, кодировка результатов JSON и обработка ошибок.

Это важно

В этой статье исключительно используется пример графа социальных сетей.

Обзор

API запросов GQL — это одна конечная точка (RPC по протоколу HTTP), которая принимает запросы GQL в качестве полезных данных JSON и возвращает структурированные, типизированные результаты. API является бессерверным, обрабатывает проверку подлинности и предоставляет комплексные отчеты об ошибках.

Ключевые особенности

Одна конечная точка — все операции используют HTTP POST для одного URL-адреса.
На основе JSON — полезные данные запроса и ответа используют JSON с полнофункциональные кодировки типизированных значений GQL.
Без отслеживания состояния — между запросами не требуется состояние сеанса.
Тип safe — строгий, совместимый с GQL типом с дискриминированными объединениями для представления значений.

Предпосылки

Вам нужен граф в Microsoft Fabric, содержащий данные, включая узлы и края (связи). Краткое руководство по созданию и загрузке примера графа см. в кратком руководстве по созданию и загрузке примера графа.
Вы должны ознакомиться с графами свойств и базовым пониманием GQL, включая структуру результатов выполнения и результатов.
Необходимо установить и настроить средство az для входа в организацию. Примеры командной строки в этой статье предполагают использование командной строки, совместимой с POSIX, например bash.

Authentication

API запросов GQL требует проверки подлинности с помощью маркеров носителя.

Добавьте маркер доступа в заголовок авторизации каждого запроса:

Authorization: Bearer <your-access-token>

Как правило, маркеры носителя можно получить с помощью библиотеки проверки подлинности Майкрософт (MSAL) или других потоков проверки подлинности, совместимых с Microsoft Entra.

Маркеры носителя обычно получаются с помощью двух основных путей:

Делегированный пользователем доступ

Маркеры носителя для вызовов служб, делегированных пользователем, можно получить из командной строки с помощью средства az.

Получите маркер носителя для делегированных пользователем вызовов из командной строки:

Запуск az login
Тогда az account get-access-token --resource https://api.fabric.microsoft.com

Для этого используется средство az.

При выполнении az rest запросов маркеры носителя получаются автоматически.

Доступ к приложению

Маркеры носителя можно получить для приложений, зарегистрированных в Microsoft Entra. Дополнительные сведения см. в кратком руководстве по API Fabric .

Конечная точка 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'] для перечисления только элементов с параметром displayNameMy Workspace.
--query 'value[starts_with(?displayName='My')] для перечисления только элементов, начиная displayName с My.
--query '{query}' для перечисления только элементов, соответствующих предоставленному JMESPath {query}. Сведения о поддерживаемом синтаксисе см. в {query}.
-o table для создания результата таблицы.

Замечание

См. раздел об использовании az-rest или разделе об использовании curl для выполнения запросов через конечную точку API из командной строки.

Заголовки запросов

Header	Ценность	Обязательно
`Content-Type`	`application/json`	Да
`Accept`	`application/json`	Да
`Authorization`	`Bearer <token>`	Да

Формат запроса

Все запросы используют HTTP POST с полезными данными JSON.

Базовая структура запроса

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

Поля запроса

Поле	Тип	Обязательно	Description
`query`	струна	Да	Запрос GQL для выполнения

Формат ответа

Все ответы для успешных запросов используют состояние HTTP 200 с полезными данными JSON, содержащими состояние выполнения и результаты.

Структура ответа

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

Объект Status

Каждый ответ содержит объект состояния со сведениями о выполнении:

Поле	Тип	Description
`code`	струна	Код состояния шести символов (000000 = успешно)
`description`	струна	Сообщение о состоянии, доступное для чтения пользователем
`diagnostics`	объект	Подробные диагностические записи
`cause`	объект	Необязательный объект состояния причины

Коды состояния

Коды состояния соответствуют иерархической схеме:

00xxxx — Завершение успешного выполнения
01xxxx — успешное выполнение с предупреждениями
02xxxx — успех без данных
03xxxx — успешное выполнение с информацией
04xxxx и выше — ошибки и условия исключения

Дополнительные сведения см. в справочнике по кодам состояния GQL.

Диагностические записи

Диагностические записи могут содержать другие пары "ключ-значение", которые подробно описывают объект состояния. Ключи, начиная с подчеркивания (_) относятся к графу для Microsoft Fabric. Стандарт GQL назначает все остальные ключи.

Замечание

Значения в диагностической записи ключей, относящихся к графу в Microsoft Fabric, — это значения GQL в кодировке JSON. См. типы значений и кодировка.

Причины

Объекты состояния включают необязательное 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 с точной семантикой. Формат JSON значений GQL следует дискриминации в формате объединения.

Замечание

Формат 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⁶ ⁶⁶⁶⁶⁶⁶⁶⁶⁶	Число или строка*	`{"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	Формат	Example
`ZONED DATETIME`	ГГГГ-ММ-DDTHH:ММ:СС[.ff]±HH:MM	`{"gqlType": "ZONED DATETIME", "value": "2023-12-25T14:30:00+02:00"}`

Ссылочные типы элементов Graph

Тип GQL	Description	Example
`NODE`	Справочник по узлам Graph	`{"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> — всегда пустой массив

Paths

Пути кодируются в виде списков ссылочных значений элементов графа.

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

См. статью "Оптимизация сериализации таблиц".

Оптимизация сериализации таблиц

Для результатов таблицы сериализация значений оптимизирована на основе сведений о типе столбца:

Известные типы . Сериализуется только необработанное значение
ЛЮБЫЕ столбцы — объект full value с дискриминационным типом

{
  "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, 0102, 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

В примере в этом разделе используется curl средство для выполнения HTTPS-запросов из оболочки.

Предполагается, что у вас есть допустимый маркер доступа, хранящийся в переменной оболочки, например:

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" 
  }'

Лучшие практики

Следуйте этим рекомендациям при использовании API запросов GQL.

Обработка ошибок

Всегда проверяйте коды состояния. Не предполагайте успешность на основе ПРОТОКОЛА HTTP 200.
Сведения об ошибке синтаксического анализа . Используйте диагностику и вызовите цепочки для отладки.

Безопасность

Используйте протокол HTTPS . Никогда не отправлять маркеры проверки подлинности через незашифрованные подключения.
Смена маркеров — реализация надлежащей обработки обновления и истечения срока действия маркеров.
Проверка входных данных — очистка и правильное экранирование параметров запроса, предоставленных пользователем, введенных в запрос.

Представление значения

Обработка больших целочисленных значений . Целые числа кодируются как строки, если они не могут быть представлены в виде чисел JSON в собственном коде.
Обработка специальных значений с плавающей запятой — значения с плавающей запятой, возвращаемые из запросов, могут быть Infinity, -Infinityили NaN (не число).
Обработка значений NULL — JSON NULL представляет GQL NULL.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-11-18

Поделиться через

Справочник по API запросов GQL

Обзор

Ключевые особенности

Предпосылки

Authentication

Делегированный пользователем доступ

Доступ к приложению

Конечная точка API

Заголовки запросов

Формат запроса

Базовая структура запроса

Поля запроса

Формат ответа

Структура ответа

Объект Status

Коды состояния

Диагностические записи

Причины

Другие объекты состояния

Типы результатов

Результаты таблицы

Опущенные результаты

Типы значений и кодировка

Структура значений

Примитивные типы

Числовые типы

Целые типы

Типы с плавающей запятой

Темпоральные типы

Ссылочные типы элементов Graph

Сложные типы

Lists

Paths

Оптимизация сериализации таблиц

Обработка ошибок

Ошибки транспорта

Ошибки приложения

Проверка состояния

Полный пример с az rest

Полный пример с curl

Лучшие практики

Обработка ошибок

Безопасность

Представление значения

Связанный контент

Обратная связь

Дополнительные ресурсы