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 auxiliam 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
  • Configuração de tempo limite

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

Base URL

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 Dadose Atualizações são coleções. Grupo, Datasete Refresh são objetos .

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

Requerimentos

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.
  • Dataset.ReadWrite.All âmbito de permissão.

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:

  • Pode ser um token de usuário ou um principal de serviço da aplicação.
  • Assegure que o público esteja corretamente definido para https://api.powerbi.com.
  • Ser 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 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 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"
        }
    ]
}

Observação

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

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 Tipo Padrão Descrição
type Enum 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. O tipo add não é suportado.
commitMode Enum 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 em 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 propriedade MaxParallelism 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 e partition ao processar uma partição. Se nenhum objeto for especificado, todo o modelo será atualizado.
applyRefreshPolicy Booleano 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 pode ser true ou false. Se commitMode for partialBatch, applyRefreshPolicy de true não é suportado 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 é determinado usando a configuração de fuso horário em 'Atualizar'.
timeout String 05:00:00 (5 horas) Se um timeout for especificado, cada tentativa de atualização de dados no modelo semântico aderirá a 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 o timeout para encurtar a duração da atualização para uma deteção de falha 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 tentativas, não pode exceder 24 horas.

Resposta

202 Accepted

A resposta também inclui um campo de cabeçalho de resposta Location para orientar o utilizador para a operação de atualização que foi criada e aceite. 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",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

Observação

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 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 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 propriedade status para fornecer mais informações.

Observação

No Azure Analysis Services, o resultado do 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 suporta a 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 é 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, status retornará InProgress, 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 de modelo agendadas ou sob demanda que foram acionadas selecionando o botão de atualização no portal, usando DELETE /refreshes/<requestId>.
  • As atualizações de modelo agendadas e sob demanda que foram acionadas ao selecionar o botão de atualização no portal não suportam a obtenção de detalhes da operação de atualização usando GET /refreshes/<requestId>.
  • Obter Detalhes e Cancelar são operações novas disponíveis apenas para a atualização melhorada. A atualização padrão não suporta essas operações.

Power BI incorporado

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 a gestão dinâmica de memória e a remoção de modelos, consulte remoção de modelos.

Atualizar os limites de tempo de operação

Uma operação de atualização pode 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 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 esta operação até que ela tenha sucesso, atinja o limite de retryCount ou atinja o máximo de 24 horas a partir da primeira tentativa.

Você pode ajustar o timeout para reduzir a duração da atualização para uma deteçã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 do modelo semântico com a API REST do conjunto de dados Refresh, considere os limites de tempo e o parâmetro retryCount. Uma atualização pode exceder o tempo limite se a tentativa inicial falhar e retryCount estiver definido 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 é de 7 horas.

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

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 seu URL base .

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

Conteúdo relacionado