Compartir a través de

Actualización mejorada con la API REST de Power BI

  • Artículo

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

Nota

  • Anteriormente, la actualización mejorada se llamaba actualización asincrónica con la API REST. Sin embargo, una actualización estándar que usa la API REST Refresh Dataset también se ejecuta de forma asincrónica por su naturaleza inherente.
  • Las operaciones mejoradas de actualización de la API REST de Power BI no actualizan automáticamente las cachés de iconos. Las cachés de iconos solo se actualizan cuando un usuario accede a un informe.

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 .

Diagrama que muestra el flujo de actualización asincrónico.

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.

Nota

Las modificaciones de la API REST no cambian los permisos definidos actualmente para las actualizaciones del 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"
        }
    ]
}

Nota

El servicio solo acepta una operación de actualización a la vez para un modelo. Si hay una actualización en ejecución actual y se envía otra solicitud, se devuelve un 400 Bad Request código de estado HTTP.

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.

Nombre Tipo Predeterminado Descripción
type Enumeración automatic Tipo de procesamiento que se va a realizar. Los tipos se alinean con los tipos de comandos de actualización de TMSL: full, clearValues, calculate, dataOnly, automaticy defragment. El tipo add no es soportado.
commitMode Enumeración transactional Determina si se deben confirmar los objetos en lotes o únicamente cuando estén completamente listos. Los modos son transactional y partialBatch. Cuando se usa partialBatch la operación de actualización no se produce dentro de una transacción. Cada comando se confirma individualmente. Si se produce un error, el modelo podría estar vacío o incluir solo un subconjunto de los datos. Para proteger contra errores y mantener los datos que se encontraban en el modelo antes de iniciar la operación, ejecute la operación con commitMode = transactional.
maxParallelism Int 10 Determina el número máximo de subprocesos que pueden ejecutar los comandos de procesamiento en paralelo. Este valor se alinea con la propiedad MaxParallelism que se puede establecer en el comando tmSL Sequence o mediante otros métodos.
retryCount Int 0 Número de veces que se reintenta la operación antes de fallar.
objects Matriz Modelo completo Matriz de objetos que se van a procesar. Cada objeto incluye table al procesar una tabla completa o table y partition al procesar una partición. Si no se especifica ningún objeto, se actualiza todo el modelo.
applyRefreshPolicy Booleano true Si se define una directiva de actualización incremental, determina si se debe aplicar la directiva. Los modos son true o false. Si no se aplica la directiva, el proceso completo deja sin cambios las definiciones de partición y actualiza completamente todas las particiones de la tabla.

Si commitMode es transactional, applyRefreshPolicy puede ser true o false. Si commitMode es partialBatch, no se admite applyRefreshPolicy de true y applyRefreshPolicy debe establecerse en false.
effectiveDate Fecha Fecha actual Si se aplica una directiva de actualización incremental, el parámetro effectiveDate invalida la fecha actual. Si no se especifica, el día actual se determina mediante la configuración de zona horaria en "Actualizar".
timeout Cuerda 05:00:00 (5 horas) Si se especifica un timeout, cada intento de actualización de datos en el modelo semántico se adhiere a ese tiempo de espera. Una única solicitud de actualización puede incluir varios intentos si se especifica retryCount, lo que puede hacer que la duración total de la actualización supere el tiempo de espera especificado. Por ejemplo, establecer un timeout de 1 hora con un retryCount de 2 podría dar lugar a una duración total de actualización de hasta 3 horas. Los usuarios pueden 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. Sin embargo, la duración total de la actualización, incluidos los reintentos, no puede superar las 24 horas.

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

Nota

Power BI podría quitar solicitudes si hay demasiadas solicitudes en un breve período de tiempo. Power BI realiza una actualización, pone en cola la siguiente solicitud y quita todos los demás. Por diseño, no se puede consultar el estado de las solicitudes eliminadas.

Propiedades de respuesta

Nombre Tipo Descripción
requestId GUID Identificador de la solicitud de actualización. Necesita utilizar requestId para consultar el estado de la operación de actualización individual o cancelar una operación de actualización en curso.
refreshType Cuerda OnDemand indica que la actualización se desencadenó de forma interactiva a través del portal de Power BI.
Scheduled indica que una programación de actualización del modelo desencadenó la actualización.
ViaApi indica que una llamada API desencadenó la actualización.
ViaEnhancedApi indica que una llamada API desencadenó una actualización mejorada.
startTime Cuerda Fecha y hora de inicio de la actualización.
endTime Cuerda Fecha y hora de finalización de la actualización.
status Cuerda Completed indica que la operación de actualización se completó correctamente.
Failed indica que se produjo un error en la operación de actualización.
Unknown indica que no se puede determinar el estado de finalización. Con este estado, endTime está vacío.
Disabled indica que la actualización se ha deshabilitado mediante la actualización selectiva.
Cancelled indica que la actualización se canceló correctamente.
extendedStatus Cuerda Aumenta la propiedad status para proporcionar más información.

Nota

En Azure Analysis Services, el resultado de status completado es succeeded. Si migra una solución de Azure Analysis Services a Power BI, es posible que tenga que modificar las soluciones.

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