Расширенное обновление с помощью REST API Power BI

Статья
01/08/2025

Вы можете использовать любой язык программирования, поддерживающий вызовы REST для выполнения операций обновления семантической модели с помощью REST API обновления набора данных Power BI.

Оптимизированное обновление для больших и сложных секционированных моделей традиционно вызывается с помощью методов программирования, использующих TOM (табличную объектную модель), командлеты PowerShell или TMSL (язык скриптов табличных моделей). Однако эти методы требуют длительных HTTP-подключений, которые могут быть ненадежными.

REST API обновления набора данных Power BI может выполнять операции обновления модели асинхронно, поэтому длительные HTTP-подключения из клиентских приложений не нужны. По сравнению со стандартными операциями обновления, настраиваемые обновления с помощью REST API предоставляют больше параметров настройки и следующие функции, которые полезны для больших моделей:

Пакетные коммиты
Обновление на уровне таблицы и раздела
Применение политик инкрементного обновления
детали обновления GET
Отмена перезагрузки
Настройка времени ожидания

Заметка

Ранее расширенное обновление называлось асинхронное обновление с помощью REST API. Однако стандартное обновление, использующее REST API обновления набора данных, также выполняется асинхронно по своей природе.
Расширенные операции обновления REST API Power BI не обновляют кэши плиток автоматически. Кэш плиток обновляется только в том случае, если пользователь обращается к отчету.

Базовый URL-адрес

Базовый URL-адрес имеет следующий формат:

https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes

Ресурсы и операции можно добавить в базовый URL-адрес на основе параметров. На следующей схеме группы, данныеи обновления являются коллекциями. Группа , набор данных и обновление - это объекты .

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

Требования

Для использования REST API требуются следующие требования:

Семантическая модель в Power BI Premium, Premium для каждого пользователя или Power BI Embedded.
Идентификатор группы и идентификатор набора данных для использования в URL-адресе запроса.
Область разрешений Dataset.ReadWrite.All.

Количество обновлений ограничено общими ограничениями для обновлений на основе API для моделей Pro и Premium.

Аутентификация

Все вызовы должны проходить проверку подлинности с помощью допустимого токена Microsoft Entra ID OAuth 2 в заголовке авторизации. Маркер должен соответствовать следующим требованиям:

Будьте либо токеном пользователя, либо учетной записью службы приложения.
Убедитесь, что аудитория правильно настроена на https://api.powerbi.com.
Может использоваться пользователем или приложением, обладающим достаточными разрешениями на модель.

Заметка

Изменения REST API в настоящее время не изменяют определенные разрешения для обновлений модели.

POST /refreshes

Чтобы выполнить обновление, используйте команду POST в коллекции /refreshes для добавления нового объекта обновления в коллекцию. Заголовок Location в ответе включает requestId. Так как операция является асинхронной, клиентское приложение может отключиться и использовать requestId для проверки состояния позже при необходимости.

В следующем коде показан пример запроса:

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes

Текст запроса может выглядеть примерно так:

{
    "type": "Full",
    "commitMode": "transactional",
    "maxParallelism": 2,
    "retryCount": 2,
    "timeout": "02:00:00",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Заметка

Служба принимает только одну операцию обновления за раз для модели. Если в данный момент выполняется обновление и отправляется другой запрос, возвращается код состояния HTTP 400 Bad Request.

Параметры

Чтобы выполнить расширенную операцию обновления, необходимо указать один или несколько параметров в тексте запроса. Указанные параметры могут указывать значение по умолчанию или необязательное значение. Когда запрос задает параметры, все остальные параметры применяются к операции со значениями по умолчанию. Если запрос не указывает параметров, все параметры используют значения по умолчанию и происходит стандартная операция обновления.

Имя	Тип	По умолчанию	Описание
`type`	Перечисление	`automatic`	Тип выполняемой обработки. Типы соответствуют типам команд обновления TMSL: `full`, `clearValues`, `calculate`, `dataOnly`, `automatic`и `defragment`. Тип `add` не поддерживается.
`commitMode`	Перечисление	`transactional`	Определяет, следует ли фиксировать объекты в пакетах или только после завершения. Режимы `transactional` и `partialBatch`. При использовании `partialBatch` операция обновления не выполняется в одной транзакции. Каждая команда фиксируется по отдельности. Если произошел сбой, модель может быть пуста или включать только подмножество данных. Чтобы защититься от сбоев и сохранить данные, которые находились в модели перед началом операции, выполните операцию с `commitMode = transactional`.
`maxParallelism`	Int	`10`	Определяет максимальное количество потоков, которые могут выполнять команды обработки параллельно. Это значение соответствует свойству `MaxParallelism`, которое можно задать в команде TMSL `Sequence` или с помощью других методов.
`retryCount`	Int	`0`	Количество повторных попыток операции перед сбоем.
`objects`	Массив	Вся модель	Массив объектов для обработки. Каждый объект включает `table` при обработке всей таблицы или `table` и `partition` при обработке секции. Если объекты не указаны, вся модель обновляется.
`applyRefreshPolicy`	Булев	`true`	Если определена политика добавочного обновления, определяет, следует ли применять политику. Режимы `true` или `false`. Если политика не применяется, полный процесс оставляет определения секций неизменными и полностью обновляет все секции в таблице. Если `commitMode` это `transactional`, то `applyRefreshPolicy` может быть `true` или `false`. Если `commitMode` равно `partialBatch`, `applyRefreshPolicytrue` не поддерживается, и `applyRefreshPolicy` должно быть установлено на `false`.
`effectiveDate`	Дата	Текущая дата	Если применяется добавочная политика обновления, параметр `effectiveDate` переопределяет текущую дату. Если этот параметр не указан, текущий день определяется с помощью конфигурации часового пояса в "Обновить".
`timeout`	Струна	05:00:00 (5 часов)	Если указана `timeout`, каждая попытка обновления данных в семантической модели соответствует времени ожидания. Один запрос обновления может включать более одной попытки при указании `retryCount`, что может привести к превышению общей продолжительности обновления, установленного таймаута. Например, установка значения `timeout` на 1 час и `retryCount` на 2 может привести к общей продолжительности обновления до 3 часов. Пользователи могут настроить `timeout`, чтобы сократить продолжительность обновления для ускорения обнаружения сбоев или продлить его за пределами по умолчанию 5 часов для более сложных обновлений данных. Однако общая длительность обновления, включая повторные попытки, не может превышать 24 часа.

Ответ

202 Accepted

Ответ также содержит поле заголовка ответа Location, чтобы указать вызывающему на выполненную и принятую операцию обновления. Location — это расположение нового ресурса, созданного запросом, которое включает requestId, требуемый для некоторых расширенных операций обновления. Например, в следующем ответе requestId является последним идентификатором в ответе 87f31ef7-1e3a-4006-9b0b-191693e79e9e.

x-ms-request-id: 87f31ef7-1e3a-4006-9b0b-191693e79e9e
Location: https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/87f31ef7-1e3a-4006-9b0b-191693e79e9e

GET /refreshes

Используйте команду GET на коллекции /refreshes для вывода списка исторических, текущих и ожидающих операций обновления.

Текст ответа может выглядеть следующим образом:

[
    {
        "requestId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T02:06:57.1838734Z",
        "endTime": "2020-12-07T02:07:00.4929675Z",
        "status": "Completed",
        "extendedStatus": "Completed"
    },
    {
        "requestId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "refreshType": "ViaEnhancedApi",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

Заметка

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

Свойства ответа

Имя	Тип	Описание
`requestId`	Guid	Идентификатор запроса на обновление. Вам нужно `requestId`, чтобы запрашивать состояние отдельной операции обновления или аннулировать выполнение текущей операции обновления.
`refreshType`	Струна	`OnDemand` указывает, что обновление было активировано интерактивно через портал Power BI. `Scheduled` указывает, что расписание обновления модели активировало обновление. `ViaApi` указывает, что вызов API активировал обновление. `ViaEnhancedApi` указывает, что вызов API вызвал расширенное обновление.
`startTime`	Струна	Дата и время начала обновления.
`endTime`	Струна	Дата и время окончания обновления.
`status`	Струна	`Completed` указывает, что операция обновления успешно завершена. `Failed` указывает, что операция обновления завершилась ошибкой. `Unknown` указывает, что состояние завершения невозможно определить. При этом состоянии `endTime` пуст. `Disabled` указывает, что обновление было отключено путем выборочного обновления. `Cancelled` указывает, что обновление было успешно отменено.
`extendedStatus`	Струна	Расширяет свойство `status`, чтобы предоставить дополнительные сведения.

Заметка

В Azure Analysis Services завершён status, и результат — succeeded. При переносе решения Служб Azure Analysis Services в Power BI может потребоваться изменить свои решения.

Ограничьте количество возвращенных операций обновления

REST API Power BI поддерживает ограничение запрошенного количества записей в журнале обновления с помощью необязательного параметра $top. Если это не указано, значение по умолчанию — это все доступные записи.

GET https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes?$top={$top}

GET /refreshes/<requestId>

Чтобы проверить состояние операции обновления, используйте команду GET в объекте обновления, указав requestId. Если операция выполняется, status возвращает InProgress, как показано в следующем примере текста ответа:

{
    "startTime": "2020-12-07T02:06:57.1838734Z",
    "endTime": "2020-12-07T02:07:00.4929675Z",
    "type": "Full",
    "status": "InProgress",
    "currentRefreshType": "Full",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer",
            "status": "InProgress"
        },
        {
            "table": "DimDate",
            "partition": "DimDate",
            "status": "InProgress"
        }
    ]
}

DELETE /refreshes/<requestId>

Чтобы отменить выполняющуюся операцию расширенного обновления, используйте метод DELETE для объекта обновления, указав requestId.

Например

DELETE https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/1344a272-7893-4afa-a4b3-3fb87222fdac

Рекомендации и ограничения

Операция обновления имеет следующие рекомендации и ограничения.

Стандартные операции обновления

Вы не можете отменить запланированные или по запросу обновления модели, которые были активированы путем нажатия кнопки обновления на портале с помощью DELETE /refreshes/<requestId>.
Запланированные обновления модели и обновления по запросу, которые были активированы путем нажатия кнопки обновления на портале, не поддерживают возможность получения сведений об операции обновления с помощью GET /refreshes/<requestId>.
Операции «Получить сведения» и «Отмена» являются новыми только в расширенном обновлении. Стандартное обновление не поддерживает эти операции.

Power BI Embedded (Встроенный)

Если емкость приостановлена вручную на портале Power BI или с помощью PowerShell, или происходит сбой системы, состояние любой выполняющейся расширенной операции обновления остается InProgress не более шести часов. Если емкость возобновляется в течение шести часов, операция обновления возобновляется автоматически. Если емкость возобновляется после более чем шести часов, операция обновления может вернуть ошибку тайм-аута. Затем необходимо перезапустить операцию обновления.

Вытеснение семантической модели

Power BI использует динамическое управление памятью для оптимизации памяти емкости. Если модель вытесна из памяти во время операции обновления, может вернуться следующая ошибка:

{
    "messages": [
        {
            "code": "0xC11C0020",
            "message": "Session cancelled because it is connected to a database that has been evicted to free up memory for other operations",
            "type": "Error"
        }
    ]
}

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

Ограничения времени операции обновления

Операция обновления может включать несколько попыток при указании retryCount. Каждая попытка имеет время ожидания по умолчанию в течение 5 часов, которое можно настроить с помощью параметра timeout. Общая длительность обновления, включая повторные попытки, не должна превышать 24 часа.

Если retryCount указывает число, новая операция обновления начинается с ограничения времени ожидания. Служба повторяет эту операцию до тех пор, пока она не завершится успешно, достигнет предела retryCount или истечёт 24-часовой максимум с первой попытки.

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

При планировании обновления семантической модели с помощью REST API обновления набора данных рассмотрите ограничения времени и параметр retryCount. Обновление может превысить время ожидания, если начальная попытка завершается ошибкой и значение retryCount установлено на 1 или больше. Если запросить обновление с параметром "retryCount": 1, а первая попытка завершается сбоем через 4 часа, начинается вторая попытка. Если это успешно в течение 3 часов, общее время обновления составляет 7 часов.

Если операции обновления регулярно завершаются сбоем, превышают ограничение времени ожидания или превышают требуемое время успешного обновления, рассмотрите возможность уменьшения объема обновляемых данных из источника данных. Вы можете разделить обновление на несколько запросов, например запрос для каждой таблицы. Можно также указать частичныйbatch в параметре commitMode.

Пример кода

Пример кода C# для начала работы см. в RestApiSample на сайте GitHub.

Чтобы использовать пример кода, выполните следующие действия.

Клонируйте или скачайте репозиторий.
Откройте решение RestApiSample.
Найдите строку и укажите базовый URL-адрес.

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

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

Расширенное обновление с помощью REST API Power BI

Базовый URL-адрес

Требования

Аутентификация

POST /refreshes

Параметры

Ответ

GET /refreshes

Свойства ответа

Ограничьте количество возвращенных операций обновления

GET /refreshes/<requestId>

DELETE /refreshes/<requestId>

Рекомендации и ограничения

Стандартные операции обновления

Power BI Embedded (Встроенный)

Вытеснение семантической модели

Ограничения времени операции обновления

Пример кода

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

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

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

Расширенное обновление с помощью REST API Power BI

Базовый URL-адрес

Требования

Аутентификация

POST /refreshes

Параметры

Ответ

GET /refreshes

Свойства ответа

Ограничьте количество возвращенных операций обновления

GET /refreshes/<requestId>

DELETE /refreshes/<requestId>

Рекомендации и ограничения

Стандартные операции обновления

Power BI Embedded (Встроенный)

Вытеснение семантической модели

Ограничения времени операции обновления

Пример кода

Связанное содержимое

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

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