Actualización mejorada mediante la API REST de Power BI

  • Artículo

Puede usar cualquier lenguaje de programación que sea compatible con las llamadas de REST para llevar a cabo operaciones de actualización de modelo semántico mediante la API de REST de actualización de 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 mediante 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 ejecución que pueden ser poco fiables.

La API de REST de actualización de conjunto de datos de Power BI puede llevar a cabo operaciones de actualización de modelo semántico de forma asincrónica, por lo que las conexiones HTTP de larga ejecución de las aplicaciones cliente no son necesarias. En comparación con las operaciones de actualización estándar, la actualización mejorada con la API REST proporciona más opciones de personalización y las siguientes características, las cuales son útiles para 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

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 de actualización de conjunto de datos también se ejecuta de forma asincrónica por su naturaleza inherente.
  • Las operaciones de actualización de la API REST de Power BI mejoradas no actualizan automáticamente las cachés de iconos. Las cachés de iconos solo se actualizan cuando un usuario accede a un informe.

URL base

La URL base tiene el siguiente formato:

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

Puede anexar recursos y operaciones a la URL base en función de los parámetros. En el diagrama siguiente, los grupos, los conjuntos de datos y las actualizaciones son colecciones. El grupo, el conjunto de datos y la actualización son objetos.

Diagram that shows asynchronous refresh flow.

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.
  • Identificadores de grupo y conjunto de datos que se van a usar en la dirección URL de la solicitud.
  • Ámbito de permiso Dataset.ReadWrite.All.

El número de actualizaciones está limitado por las limitaciones generales de las actualizaciones basadas en API para modelo 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 requisitos siguientes:

  • Ser un token de usuario o una entidad de servicio de aplicación.
  • Establecer correctamente el público en https://api.powerbi.com.
  • Que lo 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 actualizaciones de modelos.

POST /refreshes

Para realizar una actualización, utilice el verbo POST en la colección /refreshes para agregar un nuevo objeto refresh a la colección. El encabezado de ubicación de la respuesta incluye requestId. Como la operación es asincrónica, una aplicación cliente se puede desconectar y usar requestId para consultar el estado más tarde, si es necesario.

El siguiente código 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 ser similar al ejemplo siguiente:

{
    "type": "Full",
    "commitMode": "transactional",
    "maxParallelism": 2,
    "retryCount": 2,
    "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 en estos momentos hay una actualización en curso y se envía otra, se devolverá un código de estado HTTP 400 Bad Request.

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 un valor predeterminado u 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 realiza una operación de actualización estándar.

Nombre Tipo Valor predeterminado Descripción
type Enum automatic El tipo de procesamiento que desea realizar. Los tipos se alinean con los tipos de comandos de actualización de TMSL: full, clearValues, calculate, dataOnly, automatic y defragment. No se admite el tipo add.
commitMode Enumeración transactional Determina si se deben confirmar objetos en lotes o solo al completarse. 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 de 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 Sequence de TMSL o mediante otros métodos.
retryCount Int 0 Número de veces que la operación se vuelve a intentar antes de que se produzca un error.
objects Matriz Modelo completo Matriz de objetos que se va a procesar. Cada objeto incluye table al procesar una tabla completa, o bien table y partition al procesar una partición. Si no se especifica ningún objeto, se actualizará todo el modelo.
applyRefreshPolicy Booleano true Si se define una directiva de actualización incremental, determina si se aplica la directiva. Los modos son true o false. Si no se aplica la directiva, el proceso completo deja las definiciones de partición sin cambios y actualiza por completo todas las particiones de la tabla.

Si commitMode es transactional, applyRefreshPolicy puede ser true o false. Si commitMode es partialBatch, applyRefreshPolicy de true no se admite y applyRefreshPolicy debe establecerse en false.
effectiveDate Date Fecha actual Si se aplica una directiva de actualización incremental, el parámetro effectiveDate invalidará la fecha actual. Si no se especifica, se usa UTC para determinar el día actual.

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 /refreshes

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

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

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

Nota

Power BI puede anular las solicitudes si hay demasiadas en un breve período de tiempo. Power BI lleva a cabo una actualización, pone la siguiente solicitud en la cola y anula todas las otras. Por diseño, no se puede consultar el estado de las solicitudes anuladas.

Propiedades de respuesta

Nombre Tipo Descripción
requestId Guid Identificador de la solicitud de actualización. Necesita requestId para consultar el estado de la operación de actualización individual o cancelar una operación de actualización en curso.
refreshType String OnDemand indica que la actualización se ha desencadenado de forma interactiva a través del portal de Power BI.
Scheduled indica que una programación de actualización del modelo ha desencadenado la actualización.
ViaApi indica que una llamada API ha desencadenado la actualización.
ViaEnhancedApi indica que una llamada API ha desencadenado una actualización mejorada.
startTime String Fecha y hora de inicio de la actualización.
endTime String Fecha y hora de finalización de la actualización.
status String Completed indica que la operación de actualización se ha completado correctamente.
Failed indica que no se ha podido realizar la operación de actualización.
Unknown indica que el estado de conclusión no se puede determinar. Con este estado, el valor 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 ha cancelado correctamente.
extendedStatus String 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, puede que tenga que modificar sus soluciones.

Limitación del número de operaciones de actualización devueltas

La API REST de Power BI es compatible con la limitación del número de entradas solicitado en el historial de actualización mediante el parámetro opcional $top. Si no se especifica, la opción predeterminada son todas las entradas disponibles.

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

GET /refreshes/<requestId>

Para consultar el estado de una operación de actualización, utilice el verbo GET en el objeto de actualización especificando el valor 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, utilice el verbo DELETE en el objeto de actualización especificando el valor 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 puede cancelar las actualizaciones programadas o a petición manuales de modelos mediante DELETE /refreshes/<requestId>.
  • Las actualizaciones programadas y a petición manuales de modelos no son compatibles con 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 una capacidad se pausa de forma manual en el portal de Power BI o mediante PowerShell, o bien si se produce una interrupción del sistema, el estado de cualquier operación de actualización mejorada en curso sigue siendo InProgress durante un máximo de seis horas. Si la capacidad se reanuda antes de que hayan pasado seis horas, la operación de actualización se reanudará de forma automática. Si la capacidad se reanuda después de más de seis horas, puede que la operación de actualización devuelva 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 utiliza una administración de memoria dinámica para optimizar la memoria de las capacidades. Si el modelo se expulsa de la memoria durante una operación de actualización, puede que se devuelva el error siguiente:

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

La cantidad máxima de tiempo de una sola operación de actualización es de cinco horas. Si la operación de actualización no se completa correctamente dentro del límite de cinco horas y retryCount no se especifica o se especifica como 0 (valor predeterminado) en el cuerpo de la solicitud, se devuelve un error de tiempo de espera.

Si retryCount especifica 1 u otro número, se inicia una nueva operación de actualización con un límite de cinco horas. Si se produce un error en esta operación de reintento, el servicio continúa reintentando la operación de actualización hasta alcanzar el mayor número de reintentos que retryCount especifica o el límite de tiempo de procesamiento de la actualización mejorado de 24 horas desde el principio de la primera solicitud de actualización.

Al planear la solución de actualización del modelo mejorada con la API de REST de actualización de conjunto de datos, es importante tener en cuenta estos límites de tiempo y el parámetro retryCount. La finalización de una actualización correcta puede superar las cinco horas si se produce un error en una operación de actualización inicial y retryCount especifica 1 o más.

Por ejemplo, si solicita una operación de actualización con "retryCount": 1 y se produce un error en la operación de reintento inicial cuatro horas después de la hora de inicio, comienza una segunda operación de actualización para esa solicitud. Si esa segunda operación de actualización se realiza correctamente en tres horas, el tiempo total para la ejecución correcta de la solicitud de actualización es de siete horas.

Si se produce un error en las operaciones de actualización periódicamente, superan el límite de tiempo de cinco horas o el tiempo de la operación de actualización correcta 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

A fin de ver un ejemplo de código de C# para comenzar, consulte RestApiSample en GitHub.

Para usar el código de ejemplo:

  1. Clone o descargue 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 autenticación de entidad de servicio.

Contenido relacionado