Tarefa do Power BI para jobs

info

Visualização

O recurso de tarefa do Power BI está em Prévia Pública.

Embora você possa publicar para Microsoft Power BI online manualmente a partir do seu workspace Databricks, você pode usar uma tarefa do Power BI para orquestrar seus modelos semânticos do Power BI automaticamente.

Para saber mais sobre como publicar no Power BI na interface do usuário do Databricks, consulte Publicar no serviço do Power BI do Databricks.

Requisitos

É preciso seguir os mesmos requisitos que ao publicar no Power BI manualmente. Para detalhes, consulte Publicar para o Power BI Online do Databricks.
Tenha, ou crie, uma conexão do Power BI. Consulte Criar uma conexão do Power BI no Unity Catalog para orquestração.
Você deve ter o privilégio USE CONNECTION no Unity Catalog para essa conexão, bem como privilégios para acessar as tabelas e o SQL warehouse a serem usados. Consulte Gerenciar identidades, permissões e privilégios para Jobs do Lakeflow.

Configurar uma tarefa do Power BI

Após configurar uma conexão do Power BI, é possível criar uma tarefa para automatizar a publicação usando essa conexão.

nota

A interface de usuário de jobs exibe opções dinamicamente com base em outras configurações.

Para iniciar o fluxo para configurar uma tarefa Power BI:

Navegue até a aba Tarefas na IU de Jobs, para o job ao qual você deseja adicionar uma tarefa.
Clique em Adicionar tarefa .
Insira um **Nome da tarefa**.
No menu suspenso Tipo , selecione Power BI .
Configure as propriedades da tarefa (consulte a tabela a seguir para ver as propriedades e seus usos).
(Opcional) Para configurar novas tentativas, duração da execução ou limites de backlog de transmissão, ou notificações, consulte Configurações avançadas de tarefa.
Clique em **Salvar tarefa**.

nota

A Databricks recomenda definir uma entidade de serviço Databricks como a identidade **Executar como** na tarefa. Para as melhores práticas, consulte Melhores práticas para a governança de jobs. A entidade de serviço exigirá os privilégios necessários para acessar as tabelas, esquemas, conexão do Power BI e SQL warehouse do Databricks usados pela tarefa.

Ao editar uma tarefa, as credenciais do usuário atual são usadas, mas quando a tarefa é executada, a identidade Executar como é usada. A identidade deve ter os privilégios corretos para executar a tarefa.

Propriedade da tarefa do Power BI	Descrição
SQL Warehouse	O SQL warehouse que processa os refreshes no modo Importação, ou as queries no modo DirectQuery para o modelo semântico. A tarefa do Power BI requer um SQL warehouse. O compute de uso geral não é compatível.
Conexão do Power BI	A conexão do Power BI para esta tarefa. A tarefa usa esta conexão para buscar workspaces e modelos semânticos do Power BI e para publicar no Power BI. Consulte Criar uma conexão do Power BI no Unity Catalog para orquestração.
Workspace do Power BI	O workspace do Power BI ao qual um modelo semântico é publicado.
Modelo semântico do Power BI	O modelo semântico do Power BI a ser publicado. Selecione um modelo existente ou digite um novo nome de modelo e clique em Publicar novo modelo semântico <name> .
Sobrescrever modelo existente	Por padrão, as atualizações de metadados são apenas anexadas a um modelo existente. Marcar esta caixa garante que todas as atualizações de metadados e dados se propaguem para os modelos semânticos do Power BI quando a tarefa for executada.
Modo de query do Power BI	O modo de query default para as tabelas que estão sendo publicadas. Quando DirectQuery é selecionado, você também pode definir modos de query em tabelas individuais usando a propriedade Configurar modos de query de tabela . Um dos seguintes valores: Importar Os dados do modelo são armazenados em cache no Power BI. Para atualizar os dados, os utilizadores devem refresh o modelo antes de o utilizar, que consulta o SQL warehouse e carrega os dados. DirectQuery Os dados não são armazenados no Power BI. Quando o usuário cria ou carrega um painel, o SQL warehouse é consultado para os dados mais recentes. O modo de consulta do Power BI também é conhecido como modo de armazenamento no Power BI. Para obter mais informações sobre modos de consulta, consulte Modos de modelo semântico no serviço do Power BI.
Tabelas para atualizar	As tabelas e esquemas de origem para o modelo semântico. Se você selecionar um esquema para esta propriedade, então, quando você executa a tarefa, todas as tabelas sob o esquema naquele momento são usadas para a atualização. A tarefa atualiza quaisquer novas tabelas, colunas, comentários e relacionamentos de chave primária/chave estrangeira.
Método de autenticação	Define como o modelo semântico se autentica no SQL warehouse escolhido. Ao usar o OAuth, pode ser necessário configurar credenciais no Power BI após a primeira execução da tarefa. Se você não conseguir definir as credenciais do service principal na interface do usuário do Power BI para sua configuração, consulte Configurar credenciais com uma API REST. Ao usar PAT, ele gera e incorpora um PAT para a identidade execução como .
Configurar modos de query de tabela	Quando DirectQuery for selecionado como o modo de query do Power BI, você pode opcionalmente definir tabelas individuais para usar o modo de armazenamento Dual. As tabelas definidas para o modo de armazenamento Dual podem atuar como modos Import ou DirectQuery dependendo do contexto da query. Para obter mais informação, consulte Modos de modelo semântico no serviço do Power BI.
Refresh após a atualização	Esta opção está disponível se Import for selecionado como o modo de query. Por padrão, apenas os metadados do modelo são atualizados, mas se esta caixa de seleção estiver marcada, então também aciona um refresh de dados (que consulta o SQL warehouse). Este refresh pode ser visto no histórico de refresh no Power BI.

Propriedade da tarefa do Power BI	Descrição
SQL Warehouse	O SQL warehouse que processa os refreshes no modo Importação, ou as queries no modo DirectQuery para o modelo semântico. A tarefa do Power BI requer um SQL warehouse. O compute de uso geral não é compatível.
Conexão do Power BI	A conexão do Power BI para esta tarefa. A tarefa usa esta conexão para buscar workspaces e modelos semânticos do Power BI e para publicar no Power BI. Consulte Criar uma conexão do Power BI no Unity Catalog para orquestração.
Workspace do Power BI	O workspace do Power BI ao qual um modelo semântico é publicado.
Modelo semântico do Power BI	O modelo semântico do Power BI a ser publicado. Selecione um modelo existente ou digite um novo nome de modelo e clique em Publicar novo modelo semântico <name> .
Sobrescrever modelo existente	Por padrão, as atualizações de metadados são apenas anexadas a um modelo existente. Marcar esta caixa garante que todas as atualizações de metadados e dados se propaguem para os modelos semânticos do Power BI quando a tarefa for executada.
Modo de query do Power BI	O modo de query default para as tabelas que estão sendo publicadas. Quando DirectQuery é selecionado, você também pode definir modos de query em tabelas individuais usando a propriedade Configurar modos de query de tabela . Um dos seguintes valores: Importar Os dados do modelo são armazenados em cache no Power BI. Para atualizar os dados, os utilizadores devem refresh o modelo antes de o utilizar, que consulta o SQL warehouse e carrega os dados. DirectQuery Os dados não são armazenados no Power BI. Quando o usuário cria ou carrega um painel, o SQL warehouse é consultado para os dados mais recentes. O modo de consulta do Power BI também é conhecido como modo de armazenamento no Power BI. Para obter mais informações sobre modos de consulta, consulte Modos de modelo semântico no serviço do Power BI.
Tabelas para atualizar	As tabelas e esquemas de origem para o modelo semântico. Se você selecionar um esquema para esta propriedade, então, quando você executa a tarefa, todas as tabelas sob o esquema naquele momento são usadas para a atualização. A tarefa atualiza quaisquer novas tabelas, colunas, comentários e relacionamentos de chave primária/chave estrangeira.
Método de autenticação	Define como o modelo semântico se autentica no SQL warehouse escolhido. Ao usar o OAuth, pode ser necessário configurar credenciais no Power BI após a primeira execução da tarefa. Se você não conseguir definir as credenciais do service principal na interface do usuário do Power BI para sua configuração, consulte Configurar credenciais com uma API REST. Ao usar PAT, ele gera e incorpora um PAT para a identidade execução como .
Configurar modos de query de tabela	Quando DirectQuery for selecionado como o modo de query do Power BI, você pode opcionalmente definir tabelas individuais para usar o modo de armazenamento Dual. As tabelas definidas para o modo de armazenamento Dual podem atuar como modos Import ou DirectQuery dependendo do contexto da query. Para obter mais informação, consulte Modos de modelo semântico no serviço do Power BI.
Refresh após a atualização	Esta opção está disponível se Import for selecionado como o modo de query. Por padrão, apenas os metadados do modelo são atualizados, mas se esta caixa de seleção estiver marcada, então também aciona um refresh de dados (que consulta o SQL warehouse). Este refresh pode ser visto no histórico de refresh no Power BI.

Para editar, clonar, desabilitar ou excluir esta tarefa, consulte Configurar e editar tarefas em Jobs do LakeFlow.

Configurar credenciais com uma API REST

Para definir as credenciais do Service Principal do modelo semântico com uma API REST em vez da IU do Power BI, use a API de conexões do Microsoft Fabric ou a API REST do Power BI:

A API de conexões do Microsoft Fabric define credenciais na conexão e funciona para todos os tipos de conexão: cloud, gateway de dados on-premises e gateway de dados VNet.
A API REST do Microsoft Power BI define credenciais em uma fonte de dados. Isso funciona para conexões de gateway de dados on-premises e fontes de dados em cloud.

Para autenticar com um Service Principal do Databricks, use o tipo de credencial Basic com a ID do aplicativo do Service Principal como nome de usuário e seu segredo como senha.

API de conexões do Microsoft Fabric

Use a API de conexões do Microsoft Fabric para atualizar as credenciais na conexão que o modelo semântico usa. A API do Fabric requer um access token do Microsoft Entra ID, e a identidade que você usa deve ter permissão para a conexão (ou permissão de administrador de gateway do Power BI para uma conexão de gateway). Para saber como adquirir um token, consulte a documentação da API REST do Microsoft Fabric.

Os passos dependem se o Power BI se conecta por meio de uma conexão cloud ou de um gateway de dados on-premises.

Conexão com a cloud

Liste as conexões que a identidade pode acessar e encontre a conexão ShareableCloud para o seu warehouse do Databricks SQL. Anote o id dele.
HTTP
```
GET https://api.fabric.microsoft.com/v1/connections
```
Para obter detalhes, consulte a documentação da Microsoft sobre List Connections.

Atualize as credenciais da conexão, usando a conexão id. Passe as credenciais do Service Principal diretamente:

HTTP
PATCH https://api.fabric.microsoft.com/v1/connections/{connectionId}

JSON
{
  "connectivityType": "ShareableCloud",
  "credentialDetails": {
    "credentials": {
      "credentialType": "Basic",
      "username": "<service-principal-application-id>",
      "password": "<service-principal-secret>"
    }
  }
}

Para obter detalhes, consulte a documentação da Microsoft sobre Update Connection.

On-premises data gateway

Liste as conexões que a identidade pode acessar e encontre a conexão OnPremisesGateway para o seu warehouse do Databricks SQL. Anote o id e o gatewayId dele.
HTTP
```
GET https://api.fabric.microsoft.com/v1/connections
```
Para obter detalhes, consulte a documentação da Microsoft sobre List Connections.
Obtenha a key pública do gateway, usando o gatewayId da conexão:
HTTP
```
GET https://api.fabric.microsoft.com/v1/gateways/{gatewayId}
```
Para obter detalhes, consulte a documentação da Microsoft sobre Get Gateway.
Criptografe as credenciais do Service Principal com a key pública do gateway. Para obter detalhes, consulte a documentação da Microsoft sobre Configure credentials programmatically.

Atualize a conexão, usando a conexão id do primeiro passo. Envie uma entrada values por membro do gateway:

HTTP
PATCH https://api.fabric.microsoft.com/v1/connections/{connectionId}

JSON
{
  "connectivityType": "OnPremisesGateway",
  "credentialDetails": {
    "credentials": {
      "credentialType": "Basic",
      "values": [
        {
          "gatewayId": "<gateway-id>",
          "encryptedCredentials": "<encrypted credential data>"
        }
      ]
    }
  }
}

Para obter detalhes, consulte a documentação da Microsoft sobre Update Connection.

Outros tipos de conectividade, como um gateway de dados VNet (VirtualNetworkGateway), usam o mesmo endpoint com a carga útil de credencial para esse tipo. Para o esquema de solicitação completo, consulte a documentação da Microsoft em Update Connection.

API REST do Power BI

Você também pode usar a API REST do Power BI para atualizar as credenciais da fonte de dados. A API REST do Power BI requer um access token do Microsoft Entra ID. Os passos são os mesmos, independentemente de o Power BI se conectar por meio de uma fonte de dados cloud ou de um gateway de dados on-premises, mas os requisitos diferem:

Fonte de dados cloud (sem gateway) : Você deve ser o proprietário do modelo semântico. Envie as credenciais diretamente e defina encryptionAlgorithm como None.
On-premises data gateway : Você deve ter permissão de administrador de gateway. Criptografe as credenciais com a key pública do gateway e defina encryptionAlgorithm como RSA-OAEP.

Obtenha as fontes de dados do modelo semântico e encontre a fonte de dados Databricks. Observe seus datasourceId e gatewayId. O Power BI vincula uma fonte de dados em cloud a um gateway em cloud provisionado automaticamente, portanto, um gatewayId está presente mesmo sem um gateway on-premises.
HTTP
```
GET https://api.powerbi.com/v1.0/myorg/datasets/{datasetId}/datasources
```
Para obter detalhes, consulte a documentação da Microsoft sobre Get Datasources.
Atualize as credenciais para essa fonte de dados, definindo encryptionAlgorithm para o seu tipo de conexão. O exemplo a seguir é para uma fonte de dados cloud, com encryptionAlgorithm definido como None:
HTTP
```
PATCH https://api.powerbi.com/v1.0/myorg/gateways/{gatewayId}/datasources/{datasourceId}
```
JSON
```
{
  "credentialDetails": {
    "credentialType": "Basic",
    "credentials": "{\"credentialData\":[{\"name\":\"username\",\"value\":\"<service-principal-application-id>\"},{\"name\":\"password\",\"value\":\"<service-principal-secret>\"}]}",
    "encryptedConnection": "Encrypted",
    "encryptionAlgorithm": "None",
    "privacyLevel": "None"
  }
}
```
Para um gateway de dados on-premises, criptografe as credenciais com a key pública do gateway, substitua o valor credentials pelos dados criptografados e defina encryptionAlgorithm como RSA-OAEP.

Para obter detalhes, consulte a documentação da Microsoft sobre Update Datasource. Para um exemplo de PowerShell que recupera a key pública do gateway e criptografa as credenciais, consulte o Databricks M2M OAuth credentials management sample. Para obter detalhes sobre a criptografia de credenciais, consulte a documentação da Microsoft sobre Configure credentials programmatically.

Solução de problemas

Não edite um modelo semântico no serviço do Power BI enquanto uma tarefa do Power BI o atualiza. Fazer isso pode deixar o modelo preso em **Alterações pendentes**.

Para informação sobre como solucionar problemas de publicação no Power BI, consulte Solucionar problemas de publicação no Power BI. Se ainda houver problemas, é possível enviar feedback do produto. Consulte Enviar feedback do produto.

Recursos adicionais

Tarefa do Power BI: defina uma tarefa do Power BI como código com Declarative Automation Bundles.
Publicar no serviço Power BI a partir do Databricks: Configure o Power BI com o Unity Catalog.
Práticas recomendadas para governança de jobs: siga as práticas recomendadas de governança de jobs.

Requisitos​

Configurar uma tarefa do Power BI​

Configurar credenciais com uma API REST​

API de conexões do Microsoft Fabric​

API REST do Power BI​

Solução de problemas​

Recursos adicionais​