Atualização aprimorada com a API REST do Power BI

  • Artigo

Você pode usar qualquer linguagem de programação que dê suporte a chamadas REST para fazer operações de atualização de modelo semântico usando a API REST do conjunto de dados de atualização do Power BI.

A atualização otimizada para modelos semânticos particionados grandes e complexos é tradicionalmente invocada com métodos de programação que usam TOM (Modelo de Objeto Tabular), cmdlets do PowerShell ou TMSL (Linguagem de Script de Modelo Tabular). No entanto, esses métodos exigem conexões HTTP de longa execução que podem não ser confiáveis.

A API REST do conjunto de dados de atualização do Power BI pode realizar operações de atualização do modelo semântico de forma assíncrona, portanto, as conexões HTTP de execução longa de aplicativos cliente não são necessárias. Em comparação com as operações de atualização padrão, a atualização aprimorada com a API REST fornece mais opções de personalização e os seguintes recursos que são benéficos para modelos grandes:

  • Confirmações em lote
  • Atualização em nível de tabela e partição
  • Aplicando políticas de atualização incremental
  • GET detalhes da atualização
  • Cancelamento de atualização

Observação

  • Anteriormente, a atualização aprimorada era chamada de atualização assíncrona com a API REST. No entanto, uma atualização padrão que usa a API REST do conjunto de dados de atualização também é executada de forma assíncrona por sua natureza inerente.
  • As operações avançadas de atualização da API REST do Power BI não atualizam automaticamente os caches de blocos. Os caches de blocos são atualizados somente quando um usuário acessa um relatório.

URL base

A URL base está no seguinte formato:

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

Você pode acrescentar recursos e operações à URL base com base em parâmetros. No diagrama a seguir, Grupos, Conjuntos de dados e Atualizações são coleções. Grupo, Conjunto de dados e Atualização são objetos.

Diagram that shows asynchronous refresh flow.

Requisitos

Você precisa dos seguintes requisitos para usar a API REST:

  • Um modelo semântico no Power BI Premium, Premium por usuário ou Power BI Embedded.
  • Uma ID de grupo e uma ID do conjunto de dados a ser usada na URL de solicitação.
  • Escopo de permissão Dataset.ReadWrite.All.

O número de atualizações é limitado de acordo com as limitações gerais para atualizações baseadas em API para modelos Pro e Premium.

Autenticação

Todas as chamadas devem ser autenticadas com um token OAuth 2 do Microsoft Entra ID válido no Cabeçalho de autorização. O token deve atender aos seguintes requisitos:

  • Deve ser um token de usuário ou uma entidade de serviço de aplicativo.
  • Tenha o público-alvo definido corretamente como https://api.powerbi.com.
  • Seja usado por um usuário ou aplicativo que tenha permissões suficientes no modelo.

Observação

As modificações da API REST não alteram as permissões definidas atualmente para atualizações de modelo.

POST /refreshes

Para realizar uma atualização, use o verbo POST na coleção /refreshes para adicionar um novo objeto de atualização à coleção. O cabeçalho Location na resposta inclui a requestId. Como a operação é assíncrona, um aplicativo cliente pode desconectar e use o requestId para verificar o status posteriormente, se necessário.

O código a seguir mostra uma solicitação de exemplo:

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

O corpo da solicitação pode ser semelhante ao seguinte exemplo:

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

Observação

O serviço aceita apenas uma operação de atualização por vez para um modelo. Se houver uma atualização atualmente em execução e outra atualização for enviada, o código de status HTTP 400 Bad Request será retornado.

Parâmetros

Para realizar uma operação de atualização aprimorada, você deve especificar um ou mais parâmetros no corpo da solicitação. Parâmetros especificados podem detalhar o valor padrão ou opcional. Quando a solicitação especifica parâmetros, todos os outros parâmetros se aplicam à operação com seus valores padrão. Se a solicitação não especificar parâmetros, todos os parâmetros usarão seus valores padrão e ocorrerá uma operação de atualização padrão.

Nome Tipo Padrão Descrição
type Enumeração automatic O tipo de processamento a ser executado. Os tipos são alinhados com os tipos de comandos de atualização da TMSL: full, clearValues, calculate, dataOnly, automatic e defragment. O tipo add não é compatível.
commitMode Enumeração transactional Determina se os objetos devem ser confirmados em lotes ou somente quando concluídos. Os modos são transactional ou partialBatch. Ao usar partialBatch, a operação de atualização não ocorre em uma única transação. Cada comando é confirmado individualmente. Se houver uma falha, o modelo poderá ficar vazio ou incluir apenas um subconjunto dos dados. Para se proteger contra falhas e manter os dados que estavam no modelo antes do início da operação, execute a operação com commitMode = transactional.
maxParallelism Int 10 Determina o número máximo de threads que podem executar comandos de processamento em paralelo. Esse valor é alinhado com a propriedadeMaxParallelism, que pode ser definida no comando Sequence da TMSL ou usando outros métodos.
retryCount int 0 Número de vezes que a operação é repetida antes de acusar falha.
objects Array Modelo inteiro Uma matriz de objetos para processar. Cada objeto inclui: table ao processar a tabela inteira ou table e partition ao processar uma partição. Se nenhum objeto for especificado, todo o modelo será atualizado.
applyRefreshPolicy Boolean true Se uma política de atualização incremental for definida, determinará se a política deve ser aplicada. Os modos são true ou false. Se a política não for aplicada, o processo completo deixará as definições de partição inalteradas e atualizará completamente todas as partições na tabela.

Se commitMode for transactional, applyRefreshPolicy pode ser true ou false. Se commitMode for partialBatch, applyRefreshPolicy de true não tem suporte e applyRefreshPolicy deve ser definido como false.
effectiveDate Data Data atual Se uma política de atualização incremental for aplicada, o parâmetro effectiveDate substituirá a data atual. Se não for especificado, o UTC será usado para determinar o dia atual.

Response

202 Accepted

A resposta também inclui um campo de cabeçalho de resposta do Location para apontar o chamador para a operação de atualização que foi criada e aceita. O Location é o local do novo recurso que a solicitação criou, que inclui o requestId que algumas operações de atualização aprimoradas exigem. Por exemplo, na resposta a seguir, requestId é o último identificador na resposta 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 o verbo GET na coleção /refreshes para listar operações de atualização históricas, atuais e pendentes.

O corpo da resposta pode ser semelhante ao seguinte exemplo:

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

Observação

O Power BI poderá descartar solicitações se houver muitas solicitações em um curto período. O Power BI realizará uma atualização, colocará a próxima solicitação na fila e descartará todas as outras. Por design, você não pode consultar o status em solicitações descartadas.

Propriedades de resposta

Nome Tipo Descrição
requestId Guid O identificador da solicitação de atualização. Você precisará de requestId para consultar o status da operação de atualização individual ou cancelar uma operação de atualização em andamento.
refreshType String OnDemand indica que a atualização foi disparada interativamente por meio do portal do Power BI.
Scheduled indica que um agendamento de atualização do modelo disparou a atualização.
ViaApi indica que uma chamada à API disparou a atualização.
ViaEnhancedApi indica que uma chamada à API disparou uma atualização aprimorada.
startTime String Data e hora de início da atualização.
endTime String Data e hora de fim da atualização.
status String Completed indica que a operação de atualização foi concluída com êxito.
Failed indica que a operação de atualização falhou.
Unknown indica que o estado de conclusão não pode ser determinado. Com esse status, endTime está vazio.
Disabled indica que a atualização foi desabilitada por atualização seletiva.
Cancelled indica que a atualização foi cancelada com êxito.
extendedStatus String Aumenta a propriedade status para fornecer mais informações.

Observação

No Azure Analysis Services, o resultado concluído status é succeeded. Se migrar uma solução do Azure Analysis Services para o Power BI, talvez seja necessário modificar suas soluções.

Limitar o número de operações de atualização retornadas

A API REST do Power BI dá suporte à limitação do número solicitado de entradas no histórico de atualizações usando o parâmetro opcional $top. Se não for especificado, o padrão será todas as entradas disponíveis.

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

GET /refreshes/<requestId>

Para verificar o status de uma operação de atualização, use o verbo GET no objeto da atualização especificando a requestId. Se a operação estiver em andamento, status retornará InProgress, como no seguinte corpo de resposta de exemplo:

{
    "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 uma operação de atualização aprimorada em andamento, use o verbo DELETE no objeto da atualização especificando requestId.

Por exemplo,

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

Considerações e limitações

A operação de atualização tem as seguintes considerações e limitações:

Operações de atualização padrão

  • Você não pode cancelar atualizações de modelo manuais agendadas ou sob demanda usando DELETE /refreshes/<requestId>.
  • As atualizações de modelo agendadas e sob demanda não dão suporte para obter detalhes da operação de atualização usando GET /refreshes/<requestId>.
  • Obter detalhes e Cancelar são novas operações somente para atualização aprimorada. A atualização padrão não dá suporte a essas operações.

Power BI Embedded

Se a capacidade for pausada manualmente no portal do Power BI ou usando o PowerShell ou ocorrer uma interrupção do sistema, o status de qualquer operação de atualização aprimorada em andamento permanecerá InProgress por no máximo seis horas. Se a capacidade for retomada dentro de seis horas, a operação de atualização será retomada automaticamente. Se a capacidade for retomada após mais de seis horas, a operação de atualização poderá retornar um erro de tempo limite excedido. Em seguida, você deve reiniciar a operação de atualização.

Remoção de modelo semântico

O Power BI usa o gerenciamento dinâmico de memória para otimizar a memória de capacidade. Se o modelo for removido da memória durante uma operação de atualização, o seguinte erro poderá ser retornado:

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

A solução é executar novamente a operação de atualização. Para saber mais sobre gerenciamento dinâmico de memória e remoção de modelo, consulte Remoção de modelo.

Limites de tempo de operação de atualização

A quantidade máxima de tempo para uma única operação de atualização é de cinco horas. Se a operação de atualização não for concluída com êxito dentro do limite de cinco horas e retryCount não for especificada ou for especificada como 0 (o padrão) no corpo da solicitação, um erro de tempo limite retornará.

Se retryCount especificar 1 ou outro número, uma nova operação de atualização com um limite de cinco horas será iniciada. Se essa operação de repetição falhar, o serviço continuará repetindo a operação de atualização até o maior número de repetições que retryCount especificar ou o limite de tempo de processamento de atualização aprimorado de 24 horas desde o início da primeira solicitação de atualização.

Ao planejar sua solução de atualização de modelo aprimorada com a API REST do conjunto de dados de atualização, é importante considerar esses limites de tempo e o parâmetro retryCount. Uma conclusão de atualização bem-sucedida poderá exceder cinco horas se uma operação de atualização inicial falhar e retryCount especificar 1 ou mais.

Por exemplo, se você solicitar uma operação de atualização com "retryCount": 1 e a operação de repetição inicial falhar quatro horas a partir da hora de início, uma segunda operação de atualização para essa solicitação será iniciada. Se essa segunda operação de atualização for bem-sucedida em três horas, o tempo total para a execução bem-sucedida da solicitação de atualização será de sete horas.

Se as operações de atualização falharem regularmente, excederem o limite de tempo de cinco horas ou excederem o tempo de operação de atualização bem-sucedido desejado, reduza a quantidade de dados que estão sendo atualizados da fonte de dados. Você pode dividir a atualização em várias solicitações, por exemplo, uma solicitação para cada tabela. Você também pode especificar partialBatch no parâmetro commitMode.

Exemplo de código

Para um exemplo de código em C# para você começar, confira RestApiSample no GitHub.

Para usar o exemplo de código:

  1. Clone ou baixe o repositório.
  2. Abra a solução RestApiSample.
  3. Encontre a linha client.BaseAddress = … e forneça a URL de base.

Este código de exemplo usa a autenticação da entidade de serviço.

Conteúdo relacionado