Usar APIs de painel para criar e gerenciar painéis

A API REST do Databricks inclui ferramentas de gerenciamento específicas para gerenciar painéis de IA/BI. Este artigo demonstra como criar um novo painel de IA/BI a partir de um painel herdado existente. Em seguida, ele mostra como usar ferramentas de API para gerenciar o painel.

Observação

Os painéis de IA/BI eram anteriormente conhecidos como painéis Lakeview. A API Lakeview ainda mantém esse nome.

Pré-requisitos

Configure a autenticação para acessar os recursos do Azure Databricks. Para saber mais sobre as opções de autenticação e obter instruções de configuração, consulte Autorizar o acesso aos recursos do Azure Databricks.
Você precisa do(s) URL(s) do espaço de trabalho que deseja acessar. Consulte os Nomes de instância, URLs e IDs do espaço de trabalho.
Familiaridade com a API REST do Databricks, de referência .

Migrar um painel de controlo

Você pode criar um novo painel de IA/BI a partir de um painel herdado existente. O endpoint Migrate na API do Lakeview requer o source_dashboard_id. Opcionalmente, você pode incluir um nome para exibição e um caminho onde deseja que o novo painel seja armazenado.

Obtenha painéis legados

Para obter o source_dashboard_id, utilize a API dos painéis legados para obter uma listagem de todos os painéis na sua área de trabalho. Cada objeto de painel na lista results inclui um UUID que você pode usar para fazer referência ao painel herdado nos serviços de API REST do Azure Databricks.

O exemplo a seguir mostra um exemplo de um pedido e resposta para o obter objetos do dashboard ponto de acesso. Alguns detalhes da resposta foram omitidos para maior clareza. Consulte GET /api/2.0/preview/sql/dashboards para obter uma descrição completa deste ponto de extremidade e exemplo de resposta.

O UUID de um painel legado é o id do nível superior da lista de objetos retornados em results. Para painéis herdados, o UUID é semelhante a 4e443c27-9f61-4f2e-a12d-ea5668460bf1.

GET /api/2.0/preview/sql/dashboards

Query Parameters:

{
"page_size": <optional>,
"page": <optional>,
"order": <optional>
"q": <optional>
}

Response:

{
  "count": 1,
  "page": 1,
  "page_size": 25,
  "results": [
    {
      "id": "4e443c27-9f61-4f2e-a12d-ea5668460bf1",
      "slug": "sales-dashboard",
      "parent": "folders/2025532471912059",
      ...
    }
  ]
}

Migrar painel herdado

Use o UUID associado ao painel herdado para criar uma cópia que é convertida automaticamente em um novo painel de IA/BI. Isso funciona como a ferramenta Clone to AI/BI dashboard disponível na interface do utilizador. Consulte clonar um painel legado em um painel de IA/BI para saber como executar esta operação usando a interface do utilizador do Azure Databricks.

O UUID do painel herdado que você deseja converter é necessário no corpo da solicitação. Opcionalmente, você pode incluir um novo valor de display_name e um parent_path que identifique o caminho do espaço de trabalho da pasta onde você deseja que o painel convertido seja armazenado.

A resposta inclui um dashboard_id, o UUID para o novo painel de controlo. O UUID para um painel de IA/BI é um valor alfanumérico de 32 dígitos como 04aab30f99ea444490c10c85852f216c. Você pode usá-lo para identificar esse painel no namespace Lakeview e em diferentes serviços de API REST do Azure Databricks.

O exemplo a seguir mostra um exemplo de solicitação e resposta. Consulte POST /api/2.0/lakeview/dashboards/migrate.

POST /api/2.0/lakeview/dashboards/migrate

Request body parameters:
{
  "source_dashboard_id": "4e443c27-9f61-4f2e-a12d-ea5668460bf1",
  "display_name": "Monthly Traffic Report",
  "parent_path": "/path/to/dir"
}

Response:
{
  "dashboard_id": "04aab30f99ea444490c10c85852f216c",
  "display_name": "Monthly Traffic Report",
  "path": "/path/to/dir/Monthly Traffic Report.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "47bb1c472649e711",
  "etag": "80611980",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

Obter um painel de esboço

Você pode usar o dashboard_id para extrair detalhes do painel de um painel de controlo em rascunho. O exemplo de solicitação e resposta a seguir inclui detalhes para a versão atual do painel de rascunho no espaço de trabalho.

O campo etag rastreia a versão mais recente do painel. Você pode usar isso para verificar a versão antes de fazer atualizações adicionais.

GET /api/2.0/lakeview/dashboards/04aab30f99ea444490c10c85852f216c

Response:

{
  "dashboard_id": "04aab30f99ea444490c10c85852f216c",
  "display_name": "Monthly Traffic Report",
  "path": "/path/to/dir/Monthly Traffic Report.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "47bb1c472649e711",
  "etag": "80611980",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

Atualizar um painel de controle

Você pode usar o dashboard_id na resposta anterior para atualizar o novo painel de IA/BI criado com essa operação. O exemplo a seguir mostra um exemplo de solicitação e resposta. O dashboard_id do exemplo anterior é incluído como um parâmetro path.

display_name e warehouse_id foram alterados. O painel atualizado tem um novo nome e um depósito padrão atribuído, conforme mostrado na resposta. O campo etag é opcional. Se a versão especificada no etag não corresponder à versão atual, a atualização será rejeitada.

PATCH /api/2.0/lakeview/dashboards/04aab30f99ea444490c10c85852f216c

Request body:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "c03a4f8a7162bc9f",
  "etag": "80611980"
}

Response:

{
  "dashboard_id": "04aab30f99ea444490c10c85852f216c",
  "display_name": "Monthly Traffic Report 2",
  "path": "/path/to/dir/Monthly Traffic Report 2.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "c03a4f8a7162bc9f",
  "etag": "80611981",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

Criar um painel

Você pode usar o endpoint Criar painel de controlo na API do Lakeview para mover o seu painel de controlo entre espaços de trabalho. O exemplo a seguir inclui um conteúdo de solicitação de exemplo e uma resposta que cria um novo painel de controlo. A chave serialized_dashboard do exemplo anterior contém todos os detalhes necessários para criar um painel de rascunho duplicado.

O exemplo inclui um novo valor de warehouse_id correspondente a um depósito no novo espaço de trabalho. Consulte POST /api/2.0/lakeview/dashboards.

POST /api/2.0/lakeview/dashboards

Request body:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "parent_path": "/path/to/dir"
}

Response:

{
  "dashboard_id": "1e23fd84b6ac7894e2b053907dca9b2f",
  "display_name": "Monthly Traffic Report 2",
  "path": "/path/to/dir/Monthly Traffic Report 2.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "5e2f98ab3476cfd0",
  "etag": "14350695",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

A única propriedade necessária no corpo da solicitação é um display_name. Essa ferramenta pode copiar o conteúdo do painel ou criar novos painéis em branco.

Publicar um painel

Você pode usar o endpoint do Publish dashboard para publicar um painel, definir credenciais para os visualizadores e substituir o warehouse_id definido no painel de rascunho. Você deve incluir o UUID do painel como um parâmetro de caminho.

O corpo da solicitação define a propriedade embed_credentials como false. Por padrão, embed_credentials é definido como true. A incorporação de credenciais permite que os usuários no nível da conta visualizem os dados do painel. Veja Publicar um painel. Um novo valor para warehouse_id é omitido, por isso, o painel publicado utiliza o mesmo armazém atribuído ao painel de rascunho.

POST /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Request body:

{
  "embed_credentials": false
}

Response:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "embed_credentials": false,
  "revision_create_time": "2019-08-24T14:15:22Z"
}

Publique um painel com credenciais de principal de serviço

Pode publicar um painel com credenciais de principal de serviço incorporadas, autenticando-se como principal de serviço ao fazer a chamada à API. Quando publica usando o token de um principal de serviço, o dashboard é publicado com os dados e permissões de computação desse principal de serviço, permitindo que utilizadores sem acesso direto a dados vejam o dashboard.

Antes de publicar, o principal de serviço deve ter pelo menos permissões CAN MANAGE no dashboard, SELECT privilégios em todas as fontes de dados usadas no dashboard e permissões CAN USE no warehouse. Para detalhes sobre a criação de entidades de serviço e a geração de segredos OAuth, consulte Entidades de serviço e Autorizar o acesso da entidade de serviço ao Azure Databricks com OAuth.

Primeiro, autentifique como principal de serviço para obter um token de acesso:

POST https://<databricks-instance>/oidc/v1/token

Request body (form-urlencoded):

grant_type=client_credentials&scope=all-apis

Authorization header:

Basic <base64-encoded-client-id:client-secret>

Response:

{
  "access_token": "eyJraWQiOiJkYTA4ZTVjZ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Depois, use o token de acesso para publicar o dashboard com as credenciais do principal do serviço:

POST /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Authorization header:

Bearer <service-principal-access-token>

Request body:

{
  "embed_credentials": true,
  "warehouse_id": "5e2f98ab3476cfd0"
}

Response:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "embed_credentials": true,
  "revision_create_time": "2019-08-24T14:15:22Z"
}

Quando embed_credentials está definido para true, os visualizadores do painel de controlo usam as permissões do principal do serviço para aceder a dados e computar recursos. Os utilizadores só precisam de permissões para aceder ao objeto do painel em si. Todas as consultas ao painel são executadas usando a identidade do principal do serviço, pelo que os registos de auditoria mostram o principal do serviço como executor da consulta.

Aceda ao painel publicado

A resposta de GET /api/2.0/lakeview/dashboards/{dashboard_id}/published é semelhante à resposta fornecida no exemplo anterior. O dashboard_id é incluído como um parâmetro de caminho.

GET /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Response:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "embed_credentials": false,
  "revision_create_time": "2019-08-24T14:15:22Z"
}

Cancelar a publicação de um painel

O painel de rascunho é mantido quando você usa a API do Lakeview para cancelar a publicação de um painel. Essa solicitação exclui a versão publicada do painel.

O exemplo a seguir usa o dashboard_id do exemplo anterior. Uma solicitação bem-sucedida produz um código de status 200. Não existe um organismo de resposta.

DELETE /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Painel de Controlo da Lixeira

Utilize DELETE /api/2.0/lakeview/dashboards/{dashboard_id} para mover um painel de rascunho para a lixeira. O painel ainda pode ser recuperado.