Actualización mejorada con la API REST de Power BI

Puede usar cualquier lenguaje de programación que admita llamadas REST para realizar operaciones de actualización de modelos semánticas mediante la API REST de actualización del conjunto de datos de Power BI.

La actualización optimizada para modelos con particiones grandes y complejas se invoca tradicionalmente con métodos de programación que usan TOM (modelo de objetos tabulares), cmdlets de PowerShell o TMSL (lenguaje de scripting de modelos tabulares). Sin embargo, estos métodos requieren conexiones HTTP de larga duración que pueden no ser confiables.

La API REST de Power BI para refrescar conjuntos de datos puede llevar a cabo operaciones de actualización de modelos asincrónicamente, por lo que no se necesitan conexiones HTTP de larga duración desde aplicaciones cliente. En comparación con las operaciones estándar de actualización, la actualización mejorada con la API REST proporciona más opciones de personalización y las siguientes características que son útiles para los modelos grandes:

• Confirmaciones por lotes
• Actualización de nivel de tabla y partición
• Aplicación de directivas de actualización incremental
• Detalles de la actualización de GET
• Cancelación de actualización
• Configuración de tiempo de espera

Base URL

La dirección URL base tiene el formato siguiente:

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

Puede anexar recursos y operaciones a la dirección URL base en función de los parámetros. En el diagrama siguiente, los grupos, los conjuntos de datos y las actualizaciones son colecciones. Grupo, Conjunto de datosy Actualización son objetos .

Requisitos

Necesita los siguientes requisitos para usar la API REST:

• Un modelo semántico en Power BI Premium, Premium por usuario o Power BI Embedded.
• Un identificador de grupo y un identificador de conjunto de datos que se van a usar en la dirección URL de solicitud.
• Ámbito de permiso Dataset.ReadWrite.All.

El número de actualizaciones se limita según las limitaciones generales de las actualizaciones basadas en API para los modelos Pro y Premium.

Autenticación

Todas las llamadas deben autenticarse con un token de OAuth 2 válido de Microsoft Entra ID en el encabezado autorización. El token debe cumplir los siguientes requisitos:

• Ser un token de usuario o una entidad de servicio de aplicación.
• Establecer correctamente el público en https://api.powerbi.com.
• Use un usuario o una aplicación que tenga permisos suficientes en el modelo.

POST/actualizaciones

Para realizar una actualización, use el verbo POST de la colección /refreshes para agregar un nuevo objeto de actualización a la colección. El encabezado Ubicación de la respuesta incluye el requestId. Dado que la operación es asincrónica, una aplicación cliente puede desconectar y usar el requestId para comprobar el estado más adelante si es necesario.

El código siguiente muestra una solicitud de ejemplo:

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

El cuerpo de la solicitud podría parecerse al ejemplo siguiente:

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

Parámetros

Para realizar una operación de actualización mejorada, debe especificar uno o varios parámetros en el cuerpo de la solicitud. Los parámetros especificados pueden especificar el valor predeterminado o opcional. Cuando la solicitud especifica parámetros, todos los demás parámetros se aplican a la operación con sus valores predeterminados. Si la solicitud no especifica ningún parámetro, todos los parámetros usan sus valores predeterminados y se produce una operación de actualización estándar.

Respuesta

202 Accepted

La respuesta también incluye un campo de encabezado de respuesta Location para dirigir al autor de la llamada a la operación de actualización que se ha creado y aceptado. Location es la ubicación del nuevo recurso que ha creado la solicitud, que incluye el requestId que algunas operaciones de actualización mejoradas requieren. Por ejemplo, en la siguiente respuesta, requestId es el último identificador de la respuesta 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/actualizaciones

Use el verbo GET en la colección /refreshes para enumerar las operaciones históricas, actuales y pendientes de actualización.

El cuerpo de la respuesta podría tener un aspecto similar al del ejemplo siguiente:

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

Propiedades de respuesta

Limitar el número de operaciones de actualización devueltas

La API rest de Power BI admite la limitación del número solicitado de entradas en el historial de actualizaciones mediante el parámetro opcional $top. Si no se especifica, el valor predeterminado es todas las entradas disponibles.

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

GET /refreshes/<requestId>

Para comprobar el estado de una operación de actualización, use el verbo GET en el objeto refresh especificando el requestId. Si la operación está en curso, status devuelve InProgress, como en el cuerpo de la respuesta de ejemplo siguiente:

{
    "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>

Para cancelar una operación de actualización mejorada en curso, use el verbo DELETE en el objeto refresh especificando el requestId.

Por ejemplo

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

Consideraciones y limitaciones

La operación de actualización tiene las siguientes consideraciones y limitaciones:

Operaciones de actualización estándar

• No se pueden cancelar las actualizaciones programadas o bajo demanda del modelo que se desencadenaron al seleccionar el botón Actualizar en el portal mediante DELETE /refreshes/<requestId>.
• Las actualizaciones programadas y a petición del modelo que se desencadenaron seleccionando el botón Actualizar en el portal, no admiten la obtención de detalles de la operación de actualización mediante GET /refreshes/<requestId>.
• Más información y Cancelar son operaciones nuevas solo para la actualización mejorada. La actualización estándar no admite estas operaciones.

Power BI Embedded

Si la capacidad se pausa manualmente en el portal de Power BI o mediante PowerShell, o se produce una interrupción del sistema, el estado de cualquier operación de actualización mejorada en curso permanece InProgress durante un máximo de seis horas. Si la capacidad se reanuda en un plazo de seis horas, la operación de actualización se reanuda automáticamente. Si la capacidad se reanuda después de más de seis horas, la operación de actualización podría devolver un error de tiempo de espera. A continuación, debe reiniciar la operación de actualización.

Expulsión del modelo semántico

Power BI usa la administración dinámica de memoria para optimizar la memoria de capacidad. Si el modelo se expulsa de la memoria durante una operación de actualización, es posible que se devuelva el siguiente error:

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

La solución consiste en volver a ejecutar la operación de actualización. Para obtener más información sobre la administración dinámica de memoria y la expulsión de modelos, consulte expulsión de modelos.

Límites de tiempo de la operación de actualización

Una operación de actualización puede incluir varios intentos si se especifica retryCount. Cada intento tiene un tiempo de espera predeterminado de 5 horas, que se puede ajustar mediante el parámetro timeout. La duración total de la actualización, incluidos los reintentos, no debe superar las 24 horas.

Si retryCount especifica un número, una nueva operación de actualización comienza con el límite de tiempo de espera. El servicio reintenta esta operación hasta que tiene éxito, llega al límite de retryCount, o alcanza el máximo de 24 horas desde el primer intento.

Puede ajustar el timeout para acortar la duración de la actualización para una detección de errores más rápida o ampliarla más allá de las 5 horas predeterminadas para las actualizaciones de datos más complejas.

Al planear la actualización del modelo semántico con la API REST Refresh Dataset, considere los límites de tiempo y el parámetro retryCount. Una actualización puede superar el tiempo de espera si se produce un error en el intento inicial y retryCount está establecido en 1 o más. Si solicita una actualización con "retryCount": 1 y el primer intento produce un error después de 4 horas, comienza un segundo intento. Si esto se realiza correctamente en 3 horas, el tiempo total de la actualización es de 7 horas.

Si se produce un error en las operaciones de actualización periódicamente, supere el límite de tiempo de espera o supere el tiempo de operación de actualización correcto deseado, considere la posibilidad de reducir la cantidad de datos que se actualizan desde el origen de datos. Puede dividir la actualización en varias solicitudes, por ejemplo, una solicitud para cada tabla. También puede especificar partialBatch en el parámetro commitMode.

Ejemplo de código

Para obtener un ejemplo de código de C# para empezar, consulte restApiSample en GitHub.

Para usar el ejemplo de código:

1. Clona o descarga el repositorio.
2. Abra la solución RestApiSample.
3. Busque la línea client.BaseAddress = … y proporcione su URL base .

El ejemplo de código usa la autenticación de entidad de servicio.

Contenido relacionado

• API REST de actualización del conjunto de datos de Power BI
• Usar las API REST de Power BI