Работа с Deneb в PBIR

Формат Power BI Enhanced Report Format (PBIR) становится стандартным для отчётов Power BI. Это руководство объясняет, что нужно для работы возможностей Deneb, если вы вручную редактируете или программно создаёте визуалы, используете языковую модель или другой инструмент для создания отчётов либо сама языковая модель читает эту страницу как инструкцию.

Помимо PBIR, сведения помогут понять внутреннее устройство Deneb и создавать темы отчётов, содержащие его визуалы.

Краткая справка

Рекомендуется прочитать руководство целиком. Если нужны только минимальные свойства для работающего визуала Deneb в PBIR, они приведены ниже.

Минимальное определение визуала Deneb

В файле visual.json экземпляра визуала:

Проверка конфигурации PBIR

Перед загрузкой отчёта:

1. Убедитесь, что все строки JSON правильно экранированы.
2. Проверьте суффикс D у целочисленных значений.
3. Убедитесь, что текстовые значения заключены в одинарные кавычки внутри поля Value.
4. Проверьте, что логические значения заданы литералами true или false.

Подробнее о типах см. в разделе «Задание свойств».

GUID визуала

Каждый визуал Power BI имеет уникальный идентификатор GUID, определяющий его тип. Для сертифицированной версии Deneb из AppSource это:

deneb7E15AEF80B9E4D4F8E12924291ECE89A

GUID также указывает Power BI, где искать обновления. Если идентификатор совпадает с опубликованным визуалом AppSource, Power BI попытается обновить его при появлении новой версии. При использовании PBIR/PBIP код визуала не нужно включать в ресурсы PBIP и хранить под контролем версий: Power BI может получить его непосредственно из AppSource.

Другие варианты визуала

Для других вариантов Deneb используются следующие GUID:

• Standalone: STANDALONEdeneb7E15AEF80B9E4D4F8E12924291ECE89A.
• Alpha Channel: ALPHAdeneb7E15AEF80B9E4D4F8E12924291ECE89A.
• Beta Channel: BETAdeneb7E15AEF80B9E4D4F8E12924291ECE89A.

Эти варианты не связаны с AppSource и требуют дополнительной настройки: код .pbiviz нужно включить в ресурсы PBIP.

Подобно прежнему формату .pbix для отчётов Power BI, файл .pbiviz — сжатая папка. Её можно открыть, например, в 7-Zip и извлечь содержимое для просмотра. Распаковка .pbiviz в /CustomVisuals/{GUID}/ создаёт необходимую структуру для включения визуала в PBIR/PBIP.

Описание возможностей визуала

Capabilities — специальные метаданные, фактически задающие соглашение визуала с Power BI: поддерживаемые роли данных и их организация, параметры форматирования и интерактивные возможности. В PBIR это описание имеет формат JSON. Power BI обращается к нему при добавлении визуала в отчёт, чтобы определить, как интегрировать его в среду отчёта.

Когда вы добавляете и настраиваете визуал, в JSON его экземпляра сохраняются сведения, связанные с этим описанием. Они позволяют восстановить визуал из сохранённого состояния при повторном открытии страницы или отчёта.

Легко предположить, как работают эти свойства, но у визуалов часто есть собственная логика обработки сохранённых значений. Поэтому здесь объясняется, какие свойства задаются и как они влияют на создаваемые визуалы Deneb. Это позволяет работать с ними осознанно, без догадок, которые в некоторых случаях приводят к ошибкам.

Простейший случай: визуал Deneb, добавленный вручную

Посмотрим, что происходит при добавлении Deneb на холст отчёта без данных и дополнительных настроек. Базовое определение может выглядеть так:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/visualContainer/2.4.0/schema.json",
  "name": "2c2722561a0b6c3deded",
  "position": {
    "x": 80,
    "y": 56,
    "z": 0,
    "height": 280,
    "width": 280,
    "tabOrder": 0
  },
  "visual": {
    "visualType": "deneb7E15AEF80B9E4D4F8E12924291ECE89A",
    "objects": {
      "stateManagement": [
        {
          "properties": {
            "viewportHeight": {
              "expr": {
                "Literal": {
                  "Value": "270D"
                }
              }
            },
            "viewportWidth": {
              "expr": {
                "Literal": {
                  "Value": "270D"
                }
              }
            }
          }
        }
      ]
    },
    "drillFilterOtherVisuals": true
  }
}

В разделе visual.objects Deneb сохраняет свою конфигурацию.

Уже присутствует visual.objects.stateManagement. Это внутренние настройки, которые Deneb создаёт при каждом обновлении сведений от Power BI, например при изменении размеров визуала или данных. Они нужны, чтобы при открытии редактора размеры предварительного просмотра соответствовали визуалу в отчёте. Задавать их вручную не нужно: Deneb управляет ими самостоятельно. Подробнее см. в справочнике свойств.

Эквивалентное минимальное определение

Если добавлять собственный визуал через PBIR, следующий пример функционально эквивалентен предыдущему:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/visualContainer/2.4.0/schema.json",
  "name": "2c2722561a0b6c3deded",
  "position": {
    "x": 80,
    "y": 56,
    "z": 0,
    "height": 280,
    "width": 280,
    "tabOrder": 0
  },
  "visual": {
    "visualType": "deneb7E15AEF80B9E4D4F8E12924291ECE89A",
    "drillFilterOtherVisuals": true
  }
}

На холсте появится визуал Deneb со стартовой страницей, поскольку активного проекта ещё нет.

Добавление данных в визуал

Теперь добавим данные: столбец Product из таблицы Product и меру $ Sales из таблицы Financials. После добавления полей определение выглядит так:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/visualContainer/2.4.0/schema.json",
  "name": "2c2722561a0b6c3deded",
  "position": {
    /* как в предыдущем примере */
  },
  "visual": {
    "visualType": "deneb7E15AEF80B9E4D4F8E12924291ECE89A",
    "query": {
      "queryState": {
        "dataset": {
          "projections": [
            {
              "field": {
                "Column": {
                  "Expression": {
                    "SourceRef": {
                      "Entity": "Product"
                    }
                  },
                  "Property": "Product"
                }
              },
              "queryRef": "Product.Product",
              "nativeQueryRef": "Product"
            },
            {
              "field": {
                "Measure": {
                  "Expression": {
                    "SourceRef": {
                      "Entity": "Financials"
                    }
                  },
                  "Property": "$ Sales"
                }
              },
              "queryRef": "Financials.$ Sales",
              "nativeQueryRef": "$ Sales"
            }
          ]
        }
      },
      "sortDefinition": {
        "sort": [
          {
            "field": {
              "Column": {
                "Expression": {
                  "SourceRef": {
                    "Entity": "Product"
                  }
                },
                "Property": "Product"
              }
            },
            "direction": "Ascending"
          }
        ],
        "isDefaultSort": true
      }
    },
    "drillFilterOtherVisuals": true
  }
}

Это стандартная структура для любого визуала PBIR. Рассмотрим части, важные для Deneb.

• visual.query.queryState.dataset представляет столбцы и меры, добавленные в область данных Values. Во внутреннем описании возможностей эта роль называется dataset, что соответствует сопоставлению и назначению данных в спецификации Deneb.
• Поля dataset создаются и используются под отображаемыми именами из области данных. Если поле не переименовано, имя совпадает с именем столбца или меры в модели. Иначе метаданные поля содержат displayName. Например, после переименования $ Sales в Total Sales в области данных определение будет таким:

{
  "field": {
    "Measure": {
      "Expression": {
        "SourceRef": {
          "Entity": "Financials"
        }
      },
      "Property": "$ Sales"
    }
  },
  "queryRef": "Financials.$ Sales",
  "nativeQueryRef": "$ Sales", // <-- Используется, если имя не изменено в области Values
  "displayName": "Total Sales" // <-- Если задано, Deneb использует это имя при создании набора данных
}

• Кроме того, Deneb заменяет специальные символы в именах полей, если они недопустимы в спецификации Vega или Vega-Lite. На этом шаге это ещё не существенно, но важно при создании спецификации, обращающейся к полям. Подробнее см. в соответствующих разделах.

Создание минимальной спецификации

Допустим, у нас есть простая спецификация столбчатой диаграммы Vega-Lite:

{
  "data": {
    "name": "dataset"
  },
  "mark": {
    "type": "bar"
  },
  "encoding": {
    "y": {
      "field": "Product",
      "type": "nominal"
    },
    "x": {
      "field": "$ Sales",
      "type": "quantitative"
    }
  }
}

Система свойств Power BI требует, чтобы JSON спецификации и конфигурации перед сохранением в свойствах визуала был сериализован в строку с экранированием — например, как при вызове JSON.stringify. Поскольку конфигурация визуала пуста ({}), подготовим свойства так:

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/visualContainer/2.4.0/schema.json",
  "name": "2c2722561a0b6c3deded",
  "position": {
    /* как в предыдущем примере */
  },
  "visual": {
    "visualType": "deneb7E15AEF80B9E4D4F8E12924291ECE89A",
    "query": {
      /* как в предыдущем примере */
    },
    "objects": {
      "vega": [
        {
          "properties": {
            "jsonSpec": {
              "expr": {
                "Literal": {
                  "Value": "'{\n  \"data\": {\n    \"name\": \"dataset\"\n  },\n  \"mark\": {\n    \"type\": \"bar\"\n  },\n  \"encoding\": {\n    \"y\": {\n      \"field\": \"Product\",\n      \"type\": \"nominal\"\n    },\n    \"x\": {\n      \"field\": \"$ Sales\",\n      \"type\": \"quantitative\"\n    }\n  }\n}'"
                }
              }
            },
            "jsonConfig": {
              "expr": {
                "Literal": {
                  "Value": "'{}'"
                }
              }
            }
          }
        }
      ]
    },
    "drillFilterOtherVisuals": true
  }
}

Спецификация и конфигурация теперь хранятся в visual.objects.vega, соответственно в свойствах jsonSpec и jsonConfig. При загрузке визуала в Power BI Deneb восстановит и разберёт их, затем отрисует результат. Достаточно, чтобы строка JSON была допустимой; она может содержать комментарии, поскольку Deneb разбирает её как JSONC.

По умолчанию поставщик в Deneb — Vega-Lite, поэтому достаточно задать саму спецификацию. Ниже приведён справочник каждого раздела objects, позволяющий собирать более сложные конфигурации под свои задачи.

Открыв отчёт с этой конфигурацией, мы увидим столбчатую диаграмму:

Справочник свойств

Ниже описаны объекты objects, используемые Deneb для сохранения конфигурации и состояния. Для каждого свойства по возможности объясняется его назначение и влияние на работу визуала.

objects.vega

Свойства этой группы определяют спецификацию и конфигурацию среды выполнения Vega или Vega-Lite в экземпляре визуала Deneb.

objects.display

Свойства этой группы находятся в меню Rendered visual панели форматирования. Они управляют дополнительной обработкой результата Deneb поверх представления Vega.

objects.dataLimit

Свойства этой группы находятся в меню Data management. Они определяют обработку ограничений числа строк Power BI и настройки непрерывного представления.

objects.developer

Свойства этой группы предназначены для внутреннего использования.

objects.stateManagement

Свойства этой группы предназначены для внутреннего использования и сохранения временного состояния между сеансами.

objects.editor

Свойства этой группы находятся в меню Advanced Editor панели форматирования и относятся к работе и оформлению редактора. Они позволяют заранее настроить редактор для пользователей, но не влияют на отрисовку и работу визуала за его пределами.

Задание свойств

Документация PBIR недостаточно подробно описывает особенности свойств. Следующие сведения о типах помогут работать с ними в Deneb. Здесь рассматривается только поддержка Deneb, а не вся система свойств PBIR.

Распространённые ошибки

1. Отсутствие суффикса D у числовых значений: Power BI не сможет разобрать их.
2. Двойное экранирование JSON в jsonSpec: приводит к ошибкам разбора.
3. Двойные кавычки вместо одинарных для текстовых литералов.
4. Отсутствие обёртки expr.Literal.Value: свойство не распознаётся.

boolean

Логические свойства используют литералы true или false. Например, свойство со значением true задаётся так:

{
  "enableTooltips": {
    "expr": {
      "Literal": {
        "Value": "true"
      }
    }
  }
}

color

Свойства цвета соответствуют структуре #/definitions/fill в опубликованной Microsoft JSON-схеме тем отчётов. Сейчас Deneb использует и поддерживает только solid.

Цвет можно задать значением Literal в любом известном формате HTML/CSS. Синтаксис немного отличается от обычных текстовых свойств. Цвет заключают в одинарные кавычки, поскольку он хранится как текстовый литерал внутри JSON. Например, красный цвет задаётся так:

{
  "scrollbarColor": {
    "solid": {
      "color": {
        "expr": {
          "Literal": {
            "Value": "'#FF0000'" // или "'red'", "'rgb(255,0,0)'" и другие форматы
          }
        }
      }
    }
  }
}

Для привязки к теме можно использовать ThemeDataColor:

{
  "scrollbarColor": {
    "solid": {
      "color": {
        "expr": {
          "ThemeDataColor": {
            "ColorId": 1,
            "Percent": 0
          }
        }
      }
    }
  }
}

integer

Целочисленные значения имеют суффикс D, обозначающий числовой литерал. Например, чтобы задать значение 50:

{
  "selectionMaxDataPoints": {
    "expr": {
      "Literal": {
        "Value": "50D"
      }
    }
  }
}

text

Текстовые свойства заключают в одинарные кавычки ('), обозначающие строковый литерал. Например, значение vegaLite задаётся так:

{
  "provider": {
    "expr": {
      "Literal": {
        "Value": "'vegaLite'"
      }
    }
  }
}

JSON-объекты и массивы, которые нужно хранить как текст, например спецификацию Vega, необходимо преобразовать в строку и экранировать, как показано выше.

supportFieldConfiguration

Свойство supportFieldConfiguration объекта objects.stateManagement хранится как text, но содержит сериализованную в JSON карту флагов вспомогательных полей. Deneb управляет ею при настройке раздела Supporting Fields: dataset панели Project setup. Структура описана для программного создания визуалов и инструментов работы с шаблонами.

В сериализованном JSON:

• Ключи верхнего уровня — отображаемые имена столбцов и мер в области данных Values.
• Значения — объекты, описывающие состояние флагов для соответствующего поля.
• Карта содержит только поля с изменённой конфигурацией: запись добавляется, если настройки отличаются от значений по умолчанию для роли поля. Если записи нет, значения по умолчанию применяются при загрузке. Подробнее см. справочник Supporting Fields.
• При наличии записи все пять основных флагов — highlight, highlightStatus, highlightComparator, format, formatted — должны явно иметь значение true или false. Флаги параметров names и treatAsParameter необязательны и обычно присутствуют только для полей, помеченных как параметры полей.

Например, чтобы включить вспомогательное поле Format string для столбца [Product] и Highlight value для меры [$ Sales]:

{
  "supportFieldConfiguration": {
    "expr": {
      "Literal": {
        "Value": "'{\"Product\":{\"highlight\":false,\"highlightStatus\":false,\"highlightComparator\":false,\"format\":true,\"formatted\":false},\"$ Sales\":{\"highlight\":true,\"highlightStatus\":false,\"highlightComparator\":false,\"format\":false,\"formatted\":false}}'"
      }
    }
  }
}

Обратите внимание на внешние одинарные кавычки вокруг строки JSON и экранирование внутренних двойных кавычек. Это стандартный способ PBIR записывать структурированное содержимое в текстовых литералах.