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

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

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

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

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

Базовый 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.
• Используется пользователем или приложением с достаточными разрешениями для набора данных.

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"
        }
    ]
}

Параметры

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

Ответ

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"
    }
]

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

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

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.

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

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

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

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

• REST API для обновления набора данных Power BI
• Использование REST API Power BI