Тип ссылочной переменной элемента (предварительная версия)

Чтобы повысить гибкость и масштабируемость, мы представляем расширенные переменные вместе с существующими базовыми типами переменных. Эти расширенные переменные предназначены для удовлетворения ключевых требований, таких как параметризация внешних и внутренних подключений (например, Snowflake, AWS, OneLake).

Переменная типа ссылка на элемент — это расширенный тип переменной, используемый в библиотеке переменных Fabric для хранения ссылки на существующий элемент Fabric, такой как lakehouse, notebook или конвейер данных, с сохранением идентификатора рабочей области и идентификатора элемента. Этот тип переменной позволяет параметризации внутреннего подключения, позволяя разработчикам динамически связывать элементы с определенными элементами Fabric на основе этапа развертывания или контекста рабочей области.

Использование

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

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

6. После выбора, на странице varlib будет отображаться следующим образом: как компонент только для чтения, показывающий название элемента.

Если необходимо изменить ссылку на элемент или необходимо дважды проверить значение:

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

Принцип работы

Значение переменной "Ссылка на элемент" по сути является статическим указателем на элемент Fabric, определяемый Workspace ID + Item ID. Значение хранится в виде пары идентификаторов GUID, соответствующих рабочей области целевого элемента и самому элементу. Например, ссылка может храниться внутри как:

WorkspaceID = aaaaaa-0000-1111-2222-bbbbbbbb
ItemID = 00aa00aa-bb11-cc22-dd33-44ee44ee44ee

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

Помните следующее при работе со ссылками на элементы:

Ссылки на элементы позволяют параметризации внутреннего подключения, позволяя разработчикам динамически связывать элементы с определенными Fabric ресурсами на основе этапа развертывания или контекста рабочей области.
Ссылка статическая, ссылается на конкретный элемент и не корректируется автоматически в разных средах.
Для вариантов для конкретных этапов используйте наборы значений, где каждый набор может указывать на другой статический элемент (например, разные лейкхаусы на каждом этапе).
Все значения в наборах значений должны иметь одинаковый тип элемента, чтобы обеспечить совместимость и предотвратить ошибки среды выполнения. Однако мы не требуем одинакового типа элементов в различных наборах значений.

Представление в Git и API

Библиотека переменных управляется как код. С помощью Git или REST API переменные ссылки на элементы имеют четкий формат JSON. Все переменные отображаются в файле определения библиотеки переменных (хранящиеся в Git, обычно .json), перечисляя такие свойства, как имя, тип и значение.

Для переменной "Ссылка на элементы" (статическая) значение представляет собой структурированные данные для идентификаторов рабочих областей и элементов. Пример:


{
 "name": "MyDataLake",
 "note": "",
 "type": "ItemReference",
 "value": {
  "itemId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "workspaceId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
 }
}

Помните следующее при работе с API:

Хранятся только идентификаторы; имена и метаданные извлекаются во время выполнения или кэшируются в Fabric.
При создании или обновлении через API вы указываете идентификаторы рабочих областей и элементов. Недопустимые идентификаторы вызывают ошибки.

Поддерживаемые элементы

Ниже приведен список элементов, которые в настоящее время поддерживаются с помощью ссылки на элементы:

Замечание

Записная книжка через %%configure не поддерживается.

пример кода Python

В следующем примере кода показано, как использовать ссылку на элемент в скрипте Python.

var_ref = "$(/**/VarLibItem/itemReference)"
var_obj = notebookutils.variableLibrary.get(var_ref)
workspace_id = var_obj.get("workspaceId").value()
item_id = var_obj.get("itemId").value()
print(workspace_id)
print(item_id)

Этот код выполняет следующие действия:

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

Разрешения, необходимые для создания и использования ссылочных переменных элементов

Использование ссылочных переменных элементов включает два уровня разрешений:

Создание и изменение ссылочной переменной элемента: Пользователи с ролями участника или выше в рабочей области могут создавать и изменять переменные в библиотеке, а наблюдатели имеют доступ только для чтения.
Доступ к переменной ссылки на элемент. Помимо прав в библиотеке переменных, необходимо иметь как минимум разрешение на чтение переменной ссылки на элемент, на которую вы планируете ссылаться.

Дополнительные сведения о разрешениях и проверке разрешений см. в разделе "Разрешения библиотеки переменных"

Ограничения

В настоящее время можно ссылаться только на элементы структуры и семантические модели. Другие Power BI элементы, такие как поток данных 1-го поколения, в настоящее время не поддерживаются.

Дополнительные сведения

Библиотека переменных включает в себя возможности CI/CD для содержимого Fabric в различных средах (Dev, Test, Prod) с помощью переменных ссылок на элементы для конфигураций конкретных этапов. Помните следующее:

Ссылки на элементы привязаны к определенной рабочей области и идентификатору элемента.
При развертывании на новый этап эти ссылки по-прежнему указывают на исходную рабочую область, если не обновить вручную.
Используйте несколько Value-Sets для каждого этапа и активируйте правильный набор вручную или с помощью скриптов API.

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

Общие сведения о библиотеке переменных
Типы переменных
Наборы значений
Разрешения библиотеки переменных](./variable-library-permissions.md)

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

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

Last updated on 2026-03-13