Usar APIs de painel para criar e gerenciar dashboards

A API REST do Databricks inclui ferramentas de gerenciamento especificamente para gerenciar painéis de IA/BI. Este artigo demonstra como criar um novo painel de IA/BI 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 conhecidos anteriormente como painéis do 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 instalação, consulte Autorizar o acesso aos recursos do Azure Databricks.
Você precisará das URLs do espaço de trabalho aos quais deseja acessar. Veja Nomes de instâncias de espaço de trabalho, URLs e IDs.
Familiaridade com a Referência da API REST do Databricks.

Migrar um painel

Você pode criar um novo painel de IA/BI a partir de um painel herdado existente. O ponto de extremidade Migrar painel na API Lakeview requer osource_dashboard_id. Opcionalmente, você pode incluir um nome de exibição e um caminho em que deseja que o novo painel seja armazenado.

Obtenha painéis legados

Para obter o source_dashboard_id, use a API de painéis legados para obter uma lista de todos os painéis no seu espaço de trabalho. Cada objeto de painel na lista results inclui uma UUID que você pode usar para se referir ao painel herdado nos serviços da API REST do Azure Databricks.

O exemplo a seguir mostra uma solicitação e uma resposta de exemplo para o ponto de extremidade Obter objetos do painel. Alguns detalhes de resposta foram omitidos para maior clareza. Consulte GET /api/2.0/preview/sql/dashboards para obter uma descrição completa desse ponto de extremidade e resposta de exemplo.

O UUID para um painel legado é o id do nível superior da lista de objetos retornados em results. Para painéis herdados, a UUID parece 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 legado

Use a UUID associada ao painel herdado para criar uma cópia convertida automaticamente em um novo painel de IA/BI. Isso funciona como a ferramenta Clonar para painel de IA/BI disponível na interface do usuário. Veja Clone um painel legado em um painel de IA/BI para saber como executar essa operação usando a interface do usuário do Azure Databricks.

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

A resposta inclui um dashboard_id, o UUID para o novo painel. A 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 uma solicitação e uma resposta de exemplo. Veja 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 rascunho

Você pode usar o dashboard_id para efetuar pull dos detalhes do painel de um painel de 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 acompanha 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

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 uma solicitação e uma resposta de exemplo. O dashboard_id do exemplo anterior é incluído como um parâmetro de caminho.

O display_name e warehouse_id foram alterados. O painel atualizado tem um novo nome e um armazém 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 ponto de extremidade Criar painel na API do Lakeview para mover seu painel entre espaços de trabalho. O exemplo a seguir inclui um exemplo de corpo de solicitação e uma resposta que cria um novo dashboard. 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 armazém no novo espaço. Veja 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 painéis novos em branco.

Publicar um painel

Você pode usar o ponto de extremidade Publicar painel para publicar um painel, definir credenciais para visualizadores e substituir o warehouse_id definido no painel de rascunho. Você deve incluir a 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 comotrue. A inserção de credenciais permite que os usuários no nível da conta exibam dados do painel. Veja Publicar um painel. Um novo warehouse_idvalor é omitido, então o painel publicado usa o mesmo warehouse 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"
}

Publicar um painel com as credenciais do principal de serviço

Você pode publicar um dashboard com credenciais de principal de serviço inseridas, autenticando-se como um principal de serviço ao fazer a chamada à API. Quando você publica usando o token de uma entidade de serviço, o painel é publicado com os dados e as permissões de computação dessa entidade de serviço, permitindo que os usuários sem acesso direto a dados exibam o painel.

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 armazém de dados. Para obter detalhes sobre como criar entidades de serviço e gerar segredos OAuth, consulte Entidades de Serviço e Autorizar o acesso da entidade de serviço ao Azure Databricks com OAuth.

Primeiro, autentique-se como a entidade 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
}

Em seguida, use o token de acesso para publicar o painel com as credenciais do principal de 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 definido como true, os visualizadores do painel usam as permissões da entidade de serviço para acessar dados e recursos de computação. Os usuários só precisam de permissões para acessar o próprio objeto de painel. Todas as consultas de painel são executadas usando a identidade da entidade de serviço, portanto, os logs de auditoria mostram a entidade de serviço como o executor de consulta.

Obtenha o painel publicado

A resposta de GET /api/2.0/lakeview/dashboards/{dashboard_id}/publicado é 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 publicação de um painel

O rascunho do painel é 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 há nenhum corpo de resposta.

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

Painel de lixo

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