Partilhar via

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

  • Artigo

Você pode usar qualquer linguagem de programação que ofereça 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 particionados grandes e complexos é tradicionalmente invocada com métodos de programação que usam TOM (Tabular Object Model), cmdlets do PowerShell ou TMSL (Tabular Model Scripting Language). 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 de modelo de forma assíncrona, portanto, conexões HTTP de longa execução 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 úteis para modelos grandes:

  • Confirmações em lote
  • Atualização em nível de tabela e partição
  • Aplicação de políticas de atualização incremental
  • GET atualizar detalhes
  • Atualizar cancelamento

Nota

  • 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 de atualização aprimoradas da API REST do Power BI não atualizam automaticamente os caches de bloco. Os caches de bloco são atualizados somente quando um usuário acessa um relatório.

URL Base

O 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. Group, Dataset e Refresh 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.
  • Um ID de grupo e um ID de conjunto de dados a serem usados na URL de solicitação.
  • Escopo de permissão Dataset.ReadWrite.All .

O número de atualizações é limitado pelas 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 válido do Microsoft Entra ID no cabeçalho Authorization. O token deve atender aos seguintes requisitos:

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

Nota

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

POST /atualiza

Para fazer uma atualização, use o verbo POST na coleção /refreshes para adicionar um novo objeto refresh à coleção. O cabeçalho Location na resposta inclui o requestId. Como a operação é assíncrona, um aplicativo cliente pode desconectar e usar o para verificar o requestId 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"
        }
    ]
}

Nota

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

Parâmetros

Para fazer uma operação de atualização avançada, você deve especificar um ou mais parâmetros no corpo da solicitação. Os parâmetros especificados podem especificar 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 Type Predefinido Description
type Enumerar automatic O tipo de processamento a ser executado. Os tipos se alinham com os tipos de comando de atualização TMSL: full, , , , dataOnlyautomaticclearValuescalculatee .defragment O add tipo não é suportado.
commitMode Enumerar transactional Determina se os objetos devem ser confirmados em lotes ou somente quando concluídos. Os modos são transactional e partialBatch. Ao usar partialBatch a operação de atualização não ocorre dentro de uma transação. Cada comando é cometido individualmente. Se houver uma falha, o modelo pode estar 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 os comandos de processamento em paralelo. Esse valor se alinha com a MaxParallelism propriedade que pode ser definida no comando TMSL Sequence ou usando outros métodos.
retryCount Int 0 Número de vezes que a operação tenta novamente antes de falhar.
objects Matriz Modelo completo Uma matriz de objetos a serem processados. Cada objeto inclui table ao processar uma tabela inteira ou table ao partition 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á totalmente todas as partições na tabela.

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

Response

202 Accepted

A resposta também inclui um Location campo de cabeçalho de resposta 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 se parecer com o exemplo a seguir:

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

O Power BI pode descartar solicitações se houver muitas solicitações em um curto período de tempo. O Power BI faz uma atualização, enfileira a próxima solicitação e descarta todas as outras. Por design, você não pode consultar o status em solicitações descartadas.

Propriedades da resposta

Nome Tipo Description
requestId GUID O identificador da solicitação de atualização. Você precisa consultar o status da requestId 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 acionada interativamente por meio do portal do Power BI.
Scheduled Indica que uma agenda de atualização do modelo acionou a atualização.
ViaApi indica que uma chamada de API disparou a atualização.
ViaEnhancedApi indica que uma chamada de API disparou uma atualização aprimorada.
startTime String Data e hora do início da atualização.
endTime String Data e hora do fim da atualização.
status String Completed Indica a operação de atualização 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 pela atualização seletiva.
Cancelled indica que a atualização foi cancelada com êxito.
extendedStatus String Aumenta a status propriedade para fornecer mais informações.

Nota

No Azure Analysis Services, o resultado concluído status é succeeded. Se você 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 oferece 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 é 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 refresh especificando o requestId. Se a operação estiver em andamento, retorna InProgress, status como no seguinte exemplo de corpo de resposta:

{
    "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 refresh especificando o 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

  • Não é possível cancelar atualizações manuais de modelo agendadas ou sob demanda usando DELETE /refreshes/<requestId>o .
  • As atualizações manuais de modelo agendadas e sob demanda não suportam a obtenção de detalhes da operação de atualização usando GET /refreshes/<requestId>o .
  • Obter detalhes e Cancelar são novas operações apenas para atualização aprimorada. A atualização padrão não suporta essas operações.

Power BI Embedded

Se a capacidade for pausada manualmente no portal do Power BI ou usando o PowerShell, ou se 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. Em seguida, reinicie a operação de atualização.

Despejo do 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 pode retornar:

{
    "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 de memória dinâmica e remoção de modelo, consulte Remoção de modelo.

Atualizar os limites de tempo de operação

O tempo máximo 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á a repetir a operação de atualização até o maior número de tentativas especificadas retryCount ou o limite de tempo de processamento de atualização aprimorado de 24 horas a partir do início da primeira solicitação de atualização.

Ao planejar sua solução aprimorada de atualização de modelo com a API REST do conjunto de dados de atualização, é importante considerar esses limites de tempo e o retryCount parâmetro. Uma conclusão de atualização bem-sucedida pode 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": 1o , e a operação de repetição inicial falhar quatro horas após a 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 desejado da operação de atualização bem-sucedida, considere reduzir 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 commitMode parâmetro.

Exemplo de código

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

Para usar o exemplo de código:

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

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

Conteúdos relacionados