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

Статья
05/09/2023

Вы можете использовать любой язык программирования, поддерживающий вызовы 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-адресу можно добавлять ресурсы и операции на основе параметров. На следующей схеме группы, наборы данных и обновления — это коллекции. Group, Dataset и Refresh являются объектами.

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

Требования

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

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

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

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

Все вызовы должны проходить проверку подлинности с помощью допустимого маркера OAuth 2 Azure Active Directory (Azure AD) в заголовке авторизации. Маркер должен соответствовать следующим требованиям:

Быть маркером пользователя или субъектом-службой приложения.
Задайте для аудитории правильное значение 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,
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Примечание

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

Параметры

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

Имя	Тип	По умолчанию	Описание
`type`	Перечисление	`automatic`	Тип выполняемой обработки. Типы соответствуют типам команд обновления TMSL: `full`, `clearValues`, `calculate`, `dataOnlyautomatic`, и `defragment`. Тип `add` не поддерживается.
`commitMode`	Перечисление	`transactional`	Определяет, следует ли фиксировать объекты в пакетах или только по завершении. Режимы: `transactional` и `partialBatch`.
`maxParallelism`	Int	`10`	Определяет максимальное количество потоков, которые могут выполнять команды обработки параллельно. Это значение соответствует свойству `MaxParallelism` , которое можно задать в команде TMSL `Sequence` или с помощью других методов.
`retryCount`	Int	`0`	Количество повторных попыток операции перед сбоем.
`objects`	Array	Весь набор данных	Массив объектов для обработки. Каждый объект включает при `table` обработке всей таблицы или `table` при обработке секции и `partition` . Если объекты не указаны, обновляется весь набор данных.
`applyRefreshPolicy`	Логическое	`true`	Если определена политика добавочного обновления, определяет, следует ли применять политику. Режимы: `true` или `false`. Если политика не применяется, полный процесс оставляет определения секций без изменений и полностью обновляет все секции в таблице. Если `commitMode` имеет значение `transactional`, `applyRefreshPolicy` может иметь значение `true` или `false`. Если `commitMode` имеет значение `partialBatch`, `trueapplyRefreshPolicy` для не поддерживается, и `applyRefreshPolicy` ей необходимо присвоить значение `false`.
`effectiveDate`	Дата	Текущая дата	Если применяется политика добавочного обновления, `effectiveDate` параметр переопределяет текущую дату.

Ответ

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",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown",
        "extendedStatus": "InProgress"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "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 для объекта refresh, указав 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 для объекта refresh, указав 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 не указана или указана как 0 (по умолчанию) в тексте запроса, возвращается ошибка времени ожидания.

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

При планировании расширенного решения для обновления набора данных с помощью REST API обновления набора данных важно учитывать эти ограничения времени и retryCount параметр . Успешное завершение обновления может превышать пять часов, если начальная операция обновления завершается сбоем и retryCount указывает или более 1 .

Например, если вы запрашиваете операцию обновления с "retryCount": 1помощью , а начальная повторная операция завершается сбоем через четыре часа с момента начала, начинается вторая операция обновления для этого запроса. Если вторая операция обновления завершается успешно через три часа, общее время успешного выполнения запроса на обновление составляет семь часов.

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

Пример кода

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

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

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

В примере кода используется аутентификация субъекта-службы.

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

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

Требования

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

POST для /refreshes

Параметры

Ответ

GET для /refreshes

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

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

GET /refreshes/<requestId>

DELETE /refreshes/<requestId>

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

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

Power BI Embedded

Исключение наборов данных

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

Пример кода

См. также раздел

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