Структура документа Ключ-АСТРОМ — Блокноты

Структура документа Ключ-АСТРОМ — Блокноты

Блокнот Ключ-АСТРОМ хранится как документ JSON. Понимание структуры помогает создавать и изменять блокноты через API.

Обзор

Документ блокнота состоит из version, defaultTimeframe, defaultSegments и sections. Разделы упорядочены последовательно и располагаются вертикально в том порядке, в котором они идут в массиве. Каждый раздел — это либо блок Markdown, либо запрос DQL с собственными настройками визуализации и запроса.

Структура верхнего уровня

{
  "version": "7",
  "defaultTimeframe": { "from": "now()-2h", "to": "now()" },
  "defaultSegments": [],
  "sections": []
}

Свойство	Тип	Описание
version	string	Версия схемы. Всегда "7". Примечание: это строка, в отличие от версии дашборда, которая является числом.
defaultTimeframe	object	Временной диапазон по умолчанию, применяемый при открытии блокнота. Имеет строковые свойства from и to, использующие выражения времени DQL, такие как "now()-2h". По умолчанию — последние 2 часа.
defaultSegments	array	Фильтры сегментов по умолчанию, применяемые ко всем разделам DQL. Обычно пустой массив.
sections	array	Упорядоченный массив определений разделов. См. Разделы.

Разделы

Разделы хранятся в sections как упорядоченный массив. Порядок в массиве — это порядок отображения в блокноте. Существует три типа разделов: markdown, dql и function.

Разделы располагаются вертикально в порядке массива.

Раздел Markdown

Раздел Markdown отображает статическое текстовое содержимое, отформатированное с помощью Markdown.

{
  "id": "97eae716-f594-4d8a-90ea-bcc00d1c0db4",
  "type": "markdown",
  "markdown": "# Title\n\nSection content."
}

Свойство	Обязательно	Описание
id	Да	Уникальный идентификатор раздела. Используйте UUID.
type	Да	Всегда "markdown".
markdown	Да	Строка содержимого Markdown.
showTitle	Нет	Показывать или скрывать заголовок раздела.

Раздел DQL

Раздел DQL выполняет запрос и отображает результаты в виде визуализации. Свойства запроса и визуализации вложены в объект state.

{
  "id": "5151a253-30a3-4e54-95d4-816e48c7e08f",
  "type": "dql",
  "title": "Query Section",
  "height": 293,
  "showInput": true,
  "filterSegments": [],
  "drilldownPath": [],
  "previousFilterSegments": [],
  "state": {
    "input": {
      "value": "fetch logs | summarize count()",
      "timeframe": { "from": "now()-2h", "to": "now()" }
    },
    "visualization": "table",
    "visualizationSettings": {
      "autoSelectVisualization": true,
      "chartSettings": {}
    },
    "querySettings": {
      "maxResultRecords": 1000,
      "defaultScanLimitGbytes": 500,
      "maxResultMegaBytes": 1,
      "defaultSamplingRatio": 10,
      "enableSampling": false
    }
  }
}

Свойства уровня раздела:

Свойство	Обязательно	Описание
id	Да	Уникальный идентификатор раздела. Используйте UUID.
type	Да	Всегда "dql".
title	Нет	Отображается над разделом.
height	Нет	Высота раздела в пикселях. По умолчанию — примерно 400.
showInput	Нет	Показывать или скрывать редактор запроса. По умолчанию true.
showTitle	Нет	Показывать или скрывать заголовок раздела.
filterSegments	Нет	Фильтры сегментов, применяемые к этому разделу. При установке переопределяет defaultSegments.
drilldownPath	Нет	Активный путь детализации для раздела. Управляется UI.
previousFilterSegments	Нет	Предыдущее состояние фильтра сегментов, используемое для навигации с детализацией. Управляется UI.

Свойства state:

Свойство	Обязательно	Описание
state.input.value	Да	Строка запроса DQL.
state.input.timeframe	Нет	Переопределение временного диапазона для конкретного раздела. Объект со свойствами from и to.
state.visualization	Нет	Тип визуализации. См. Типы визуализаций. Обязательно, когда autoSelectVisualization имеет значение false.
state.visualizationSettings	Да	Объект настроек визуализации. Установите autoSelectVisualization: true, чтобы Ключ-АСТРОМ автоматически выбирал лучший тип.
state.querySettings	Да	Объект настроек выполнения запроса.

Раздел Function

Раздел Function выполняет функцию JavaScript в среде выполнения Astromkey Functions и при необходимости отображает результат в виде визуализации.

{
  "id": "54beb22f-3ef2-4809-93aa-06a3cab3f702",
  "type": "function",
  "title": "Users fetched from API",
  "showTitle": true,
  "showInput": true,
  "drilldownPath": [],
  "state": {
    "input": {
      "value": "export default async function () {\n  const res = await fetch('https://example.com/api/data');\n  return res.json();\n}"
    },
    "visualization": "table",
    "visualizationSettings": {
      "autoSelectVisualization": true
    }
  }
}

Свойство	Обязательно	Описание
id	Да	Уникальный идентификатор. Используйте UUID.
type	Да	Всегда "function".
title	Нет	Отображается над разделом.
showInput	Нет	Показывать или скрывать редактор кода в разделе.
state.input.value	Да	Исходный код JavaScript в виде строки. Экспорт по умолчанию вызывается при запуске раздела.
state.visualization	Нет	Тип визуализации для вывода функции. См. Типы визуализаций.
state.visualizationSettings	Нет	Объект конфигурации визуализации.

Типы визуализаций

Блокноты поддерживают следующие типы визуализаций для разделов DQL:

davis, table, histogram, honeycomb, singleValue, donutChart, pieChart, categoricalBarChart, dotMap, choropleth, bubbleMap, connectionMap, meterBar, gauge, heatmap, lineChart, areaChart, barChart, bandChart, scatterplot, raw, recordView, treemap

Установка "autoSelectVisualization": true в state.visualizationSettings позволяет Ключ-АСТРОМ автоматически выбирать наиболее подходящую визуализацию для результата запроса. Используйте это, если вам не нужен конкретный тип.

Требования к типам полей для каждого типа визуализации см. в разделе Типы визуализаций.