Обзор работы с Yandex Query HTTP API
С помощью Query HTTP API можно выполнять разовые операции, а также автоматизировать рутинные действия, например, выполнять запросы к данным из скриптов или программ по расписанию.
Методы Query HTTP API позволяют создавать и запускать запросы к данным, получать статусы выполнения запросов и их результаты, останавливать запросы. Для выполнения запросов к API необходимо аутентифицироваться.
Ниже приведены общие подходы к работе с Query HTTP API:
Заголовки
При работе с HTTP API часть заголовков является обязательной, а часть — нет.
Обязательные заголовки
| Название | Описание |
|---|---|
Authorization |
Параметры аутентификации. Тип: строка. Пример: Authorization: Bearer <IAM-токен>. |
Необязательные заголовки
| Название | Описание |
|---|---|
x-request-id |
Используется для диагностики запросов. В качестве значения можно указывать произвольное строковое значение. Рекомендуем указывать высокоуникальные значения (например, Guid) для избежания коллизий с идентификаторами диагностики других запросов. Тип: строка. Пример: c8b4c0aa-8fc2-4159-8870-f4cb********. |
Idempotency-Key |
Ключ идемпотентности. Используется в модифицирующих операциях. Рекомендуем указывать этот параметр для избежания неожиданных ситуаций. Тип: строка, UUID. Пример: Idempotency-Key: c1700de3-b8cb-4d8a-9990-e4eb********. |
Ошибки
При возникновении ошибок Yandex Query возвращает детальное описание ошибки в Json-объекте:
{
"message": "Failed to parse query",
"details": [
{
"position": {
"row": 0,
"column": 0
},
"message": "string",
"end_position": {
"row": 0,
"column": 0
},
"issue_code": 0,
"severity": "FATAL",
"issues": [
"string"
]
}
]
}
Поля Json-объекта с ошибками:
| Название | Тип | Описание | Пример |
|---|---|---|---|
message |
Строка | Общее описание ошибки | "Failed to parse query" |
details |
Массив объектов Issue |
Детальное описание строки с ошибкой |
Объект Issue
При возникновении ошибки Yandex Query возвращает детальную информацию о месте возникновения ошибки, контексте и номерах строк SQL-запроса, содержащих ошибку. Результат возвращается в виде экземпляра объекта Issue.
Информация об ошибках может быть иерархической, то есть более общая Issue может содержать несколько детальных Issue с более подробным описанием и так далее.
Пример иерархических ошибок
{
"issues": [
{
"issues": [
{
"position": {
"column": 1,
"row": 1
},
"severity": 1,
"endPosition": {
"column": 1,
"row": 1
},
"message": "Column references are not allowed without FROM"
},
{
"position": {
"column": 8,
"row": 1
},
"severity": 1,
"endPosition": {
"column": 8,
"row": 1
},
"message": "Column reference 'x'"
}
],
"severity": 1,
"message": "Parse Sql"
},
{
"issues": [
{
"position": {
"column": 1,
"row": 1
},
"severity": 1,
"endPosition": {
"column": 1,
"row": 1
},
"message": "Column references are not allowed without FROM"
},
{
"position": {
"column": 8,
"row": 1
},
"severity": 1,
"endPosition": {
"column": 8,
"row": 1
},
"message": "Column reference 'x'"
}
],
"severity": 1,
"message": "Parse Sql"
}
],
"severity": 1,
"message": "Failed to parse query"
}
Поля объекта Issue:
| Название | Тип | Описание | Пример |
|---|---|---|---|
message |
Строка | Общее описание ошибки | "Failed to parse query" |
severity |
Число | Критичность ошибки. Возможные значения: Info, Warn, Error, Fatal |
Warn |
position.row |
Число | Номер строки начала блока кода, вызвавшего ошибку | 1 |
position.column |
Число | Номер символа в строке position.row |
1 |
endPosition.row |
Число | Номер строки конца блока кода, вызвавшего ошибку | 1 |
endPosition.column |
Число | Номер символа в строке endPosition.row |
1 |
Issues |
Массив | Массив вложенных Issue с детализацией ошибок |