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 semânticas de atualização de modelo 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 (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 execução prolongada 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 execução longa de aplicativos cliente não são necessárias. Em comparação com as operações de atualização padrão, 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
  • Aplicando políticas de atualização incremental
  • Detalhes da atualização do GET
  • Cancelamento de atualização
  • Configuração de tempo limite

Nota

  • Anteriormente, a atualização aprimorada era conhecida como 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.

Diagrama que mostra o fluxo de atualização assíncrono.

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 válido do Microsoft Entra ID 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.
  • 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 definidas no momento para atualizações de modelo.

POST /refreshes

Para fazer uma atualização, use o verbo POST na coleção /refreshes para adicionar um novo objeto de atualização à coleção. O cabeçalho de Localização na resposta inclui o requestId. Como a operação é assíncrona, um aplicativo cliente pode se desconectar e usar 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,
    "timeout": "02:00:00",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Nota

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

Parâmetros

Para fazer uma operação de atualização aprimorada, 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 Tipo Padrão Descrição
type Enumeração automatic O tipo de processamento a ser executado. Os tipos se alinham com os tipos de comando de atualização TMSL: full, clearValues, calculate, dataOnly, automatice defragment. Não há suporte para o tipo de add.
commitMode Enumeração 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 é confirmado individualmente. Se houver uma falha, o modelo poderá estar vazio ou incluir apenas um subconjunto dos dados. Para 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 à propriedade MaxParallelism que pode ser definida no comando Sequence TMSL 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 e partition ao processar uma partição. Se nenhum objeto for especificado, todo o modelo será atualizado.
applyRefreshPolicy Booliano 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 for transactional, applyRefreshPolicy poderá ser true ou false. Se commitMode for partialBatch, não há suporte para applyRefreshPolicy de true 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 dia atual será determinado usando a configuração de fuso horário em "Atualizar".
timeout Cadeia de caracteres 05:00:00 (5 horas) Se um timeout for especificado, cada tentativa de atualização de dados no modelo semântico cumprirá esse tempo limite. Uma única solicitação de atualização pode incluir várias tentativas se retryCount for especificado, o que pode fazer com que a duração total da atualização exceda o tempo limite especificado. Por exemplo, definir um timeout de 1 hora com um retryCount de 2 pode resultar em uma duração total de atualização de até 3 horas. Os usuários podem ajustar a timeout para reduzir a duração da atualização para detecção de falhas mais rápida ou estendê-la além das 5 horas padrão para atualizações de dados mais complexas. No entanto, a duração total da atualização, incluindo novas tentativas, não pode exceder 24 horas.

Resposta

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 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",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

Nota

O Power BI poderá remover 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 de resposta

Nome Tipo Descrição
requestId GUID O identificador da solicitação de atualização. Você precisa requestId para consultar o status da operação de atualização individual ou cancelar uma operação de atualização em andamento.
refreshType Cadeia de caracteres OnDemand indica que a atualização foi disparada interativamente por meio do portal do Power BI.
Scheduled indica que um agendamento de atualização de 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 Cadeia de caracteres Data e hora do início da atualização.
endTime Cadeia de caracteres Data e hora do fim da atualização.
status Cadeia de caracteres 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 pela atualização seletiva.
Cancelled indica que a atualização foi cancelada com êxito.
extendedStatus Cadeia de caracteres Aumenta a propriedade status para fornecer mais informações.

Nota

No Azure Analysis Services, o resultado status concluído é 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 dá suporte à limitação do número solicitado de entradas no histórico de atualizações usando o parâmetro $top opcional. 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 de atualização especificando o 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 de atualização 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 de modelo agendadas ou sob demanda que foram disparadas selecionando o botão atualizar no portal, usando DELETE /refreshes/<requestId>.
  • As atualizações de modelos agendadas e sob demanda que foram disparadas selecionando o botão Atualizar no portal, 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. 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á 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 dinâmico de memória e remoção de modelo, consulte a seção Remoção de modelo.

Atualizar limites de tempo de operação

Uma operação de atualização poderá incluir várias tentativas se retryCount for especificado. Cada tentativa tem um tempo limite padrão de 5 horas, que pode ser ajustado usando o parâmetro timeout. A duração total da atualização, incluindo novas tentativas, não deve exceder 24 horas.

Se retryCount especificar um número, uma nova operação de atualização começará com o limite de tempo. O serviço tenta novamente essa operação até que ela seja bem-sucedida, atinja o limite de retryCount ou atinja o máximo de 24 horas da primeira tentativa.

Você pode ajustar a timeout para reduzir a duração da atualização para uma detecção de falha mais rápida ou estendê-la além das 5 horas padrão para atualizações de dados mais complexas.

Ao planejar a atualização semântica do modelo com a API REST do Conjunto de Dados de Atualização, considere os limites de tempo e o parâmetro retryCount. Uma atualização poderá exceder o tempo limite se a tentativa inicial falhar e retryCount estiver definida como 1 ou mais. Se você solicitar uma atualização com "retryCount": 1 e a primeira tentativa falhar após 4 horas, uma segunda tentativa será iniciada. Se isso for bem-sucedido em 3 horas, o tempo total para a atualização será de 7 horas.

Se as operações de atualização falharem regularmente, exceder o limite de tempo limite ou exceder o tempo de operação de atualização bem-sucedido desejado, 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 parâmetro commitMode.

Exemplo de código

Para obter um exemplo de código C# para começar, consulte 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 sua URL base .

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

Conteúdo relacionado