Compartilhar via

Gerencie painéis com APIs do Workspace

Este tutorial demonstra como gerenciar dashboards usando a API do Lakeview e a API do Workspace. Cada etapa inclui uma solicitação e uma resposta de exemplo e explicações sobre como usar as ferramentas e propriedades da API juntos. Cada etapa pode ser referenciada por conta própria. Seguir todas as etapas na ordem orienta você por meio de um fluxo de trabalho completo.

Observação

Esse fluxo de trabalho chama a API do Workspace para recuperar um painel de IA/BI como um objeto de workspace genérico. Os painéis de IA/BI eram conhecidos anteriormente como painéis do Lakeview. A API lakeview mantém esse nome.

Pré-requisitos

Etapa 1: Explorar diretório de área de trabalho

A API da lista de espaços de trabalho GET /api/2.0/workspace/list permite que você explore a estrutura de diretórios do seu espaço de trabalho. Por exemplo, você pode recuperar uma lista de todos os arquivos e diretórios em seu workspace atual.

No exemplo a seguir, a path propriedade na solicitação aponta para uma pasta nomeada examples_folder armazenada na pasta inicial de um usuário. O nome de usuário é fornecido no caminho, first.last@example.com.

A resposta mostra que a pasta contém um arquivo de texto, um diretório e um painel de IA/BI.

GET /api/2.0/workspace/list

Query Parameters:
{
"path": "/Users/first.last@example.com/examples_folder"
}

Response:
{
  "objects": [
    {
      "object_type": "FILE",
      "path": "/Users/first.last@example.com/examples_folder/myfile.txt",
      "created_at": 1706822278103,
      "modified_at": 1706822278103,
      "object_id": 3976707922053539,
      "resource_id": "3976707922053539"
  },
  {
      "object_type": "DIRECTORY",
      "path": "/Users/first.last@example.com/examples_folder/another_folder",
      "object_id": 2514959868792596,
      "resource_id": "2514959868792596"
  },
  {
      "object_type": "DASHBOARD",
      "path": "/Users/first.last@example.com/examples_folder/mydashboard.lvdash.json",
      "object_id": 7944020886653361,
      "resource_id": "01eec14769f616949d7a44244a53ed10"
    }
  ]
}

Etapa 2: Exportar um painel

A API de Exportação do Workspace GET /api/2.0/workspace/export permite exportar o conteúdo de um dashboard como um arquivo. Os arquivos de dashboards de IA/BI refletem a versão de rascunho de um dashboard. A resposta nos exemplos a seguir mostra o conteúdo de uma definição mínima do painel. Para explorar e entender mais detalhes de serialização, tente exportar alguns de seus próprios dashboards.

Baixar o arquivo exportado

O exemplo a seguir mostra como baixar um arquivo de painel usando a API.

A propriedade "path" neste exemplo termina com a extensão de tipo de arquivo lvdash.json, um painel de IA/BI. O nome do arquivo, como aparece no workspace, precede essa extensão. Nesse caso, use mydashboard.

Além disso, a propriedade "direct_download" para essa solicitação é definida como true para que a resposta seja o próprio arquivo exportado e a propriedade "format" seja definida como "AUTO".

Observação

A propriedade"displayName", mostrada na propriedade pages da resposta, não reflete o nome visível do painel no espaço de trabalho.

GET /api/2.0/workspace/export

Query parameters:
{
  "path": "/Users/first.last@example.com/examples_folder/mydashboard.lvdash.json",
  "direct_download": true,
  "format": "AUTO"
}

Response:
{
  "pages": [
    {
      "name": "880de22a",
      "displayName": "New Page"
    }
  ]
}

Codificar o arquivo exportado

O código a seguir mostra uma resposta de exemplo em que "direct_download" propriedade é definida como false. A resposta contém conteúdo como uma cadeia de caracteres codificada em base64.

GET /api/2.0/workspace/export

Query parameters:
{
    "path": "/Users/first.last@example.com/examples_folder/mydashboard.lvdash.json",
    "direct_download": false
}

Response:
{
    "content": "IORd/DYYsCNElspwM9XBZS/i5Z9dYgW5SkLpKJs48dR5p5KkIW8OmEHU8lx6CZotiCDS9hkppQG=",
    "file_type": "lvdash.json"
}

Etapa 3: Importar um painel

Você pode usar a API de importação do Workspace POST /api/2.0/workspace/import para importar rascunhos de painéis para um workspace. Por exemplo, depois de exportar um arquivo codificado, como no exemplo anterior, você pode importar esse painel para um novo workspace.

Para que uma importação seja reconhecida como um painel de IA/BI, dois parâmetros devem ser definidos:

  • "format": "AUTO" – essa configuração permitirá que o sistema detecte o tipo de ativo automaticamente.
  • "path": deve incluir um caminho de arquivo que termine com ".lvdash.json".

Importante

Se essas configurações não estiverem configuradas corretamente, a importação poderá ser bem-sucedida, mas o painel será tratado como um arquivo regular.

O exemplo a seguir mostra uma solicitação de importação configurada corretamente.


POST /api/2.0/workspace/import

Request body parameters:
{
        "path": "/Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json",
        "content": "IORd/DYYsCNElspwM9XBZS/i5Z9dYgW5SkLpKJs48dR5p5KkIW8OmEHU8lx6CZotiCDS9hkppQG=",
        "format": "AUTO"
}

Response:
{}

Etapa 4: Substituir na importação (opcional)

A tentativa de reemissão da mesma solicitação de API resulta no seguinte erro:

{
        "error_code": "RESOURCE_ALREADY_EXISTS",
        "message": "Path (/Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json) already exists."
}

Se você quiser substituir a solicitação duplicada, defina a propriedade "overwrite" como true como no exemplo a seguir.


POST /api/2.0/workspace/import

Request body parameters:
{
        "path": /Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json",
        "content": "IORd/DYYsCNElspwM9XBZS/i5Z9dYgW5SkLpKJs48dR5p5KkIW8OmEHU8lx6CZotiCDS9hkppQG=",
        "format": "AUTO",
        "overwrite": true
}

Response:
{}

Etapa 5: Recuperar metadados

Você pode recuperar metadados para qualquer objeto de workspace, incluindo um painel de IA/BI. Veja GET /api/2.0/workspace/get-status.

O exemplo a seguir mostra uma solicitação get-status para o painel importado do exemplo anterior. A resposta inclui detalhes afirmando que o arquivo foi importado com êxito como um "DASHBOARD". Além disso, ele consiste em uma propriedade "resource_id" que você pode usar como um identificador com a API lakeview.

GET /api/2.0/workspace/get-status

Query parameters:
{
        "path": "/Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json"
}

Response:
{
        "object_type": "DASHBOARD",
        "path": "/Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json",
        "object_id": 7616304051637820,
        "resource_id": "9c1fbf4ad3449be67d6cb64c8acc730b"
}

Etapa 6: Publicar um painel

Os exemplos anteriores usavam a API do Workspace, habilitando o trabalho com painéis de IA/BI como objetos de workspace genéricos. O exemplo a seguir usa a API lakeview para executar uma operação de publicação específica para painéis de IA/BI. Veja POST /api/2.0/lakeview/dashboards/{dashboard_id}/published.

O caminho para o ponto de extremidade da API inclui a propriedade "resource_id" retornada no exemplo anterior. Nos parâmetros de solicitação, "embed_credentials" é configurado como true para que as credenciais do editor sejam inseridas no painel. O editor, nesse caso, é o usuário que está fazendo a solicitação de API autorizada. O publicador não pode inserir credenciais de usuários diferentes. Veja Publicar um painel para saber como funciona a configuração Incorporar credenciais.

A propriedade "warehouse_id" define o warehouse a ser usado para o painel publicado. Se especificado, essa propriedade substitui o warehouse especificado para o painel de rascunho, se houver.

POST /api/2.0/lakeview/dashboards/9c1fbf4ad3449be67d6cb64c8acc730b/published

Request parameters
{
  "embed_credentials": true,
  "warehouse_id": "1234567890ABCD12"
}

Response:
{}

O painel publicado pode ser acessado do navegador quando o comando é concluído. O exemplo a seguir mostra como montar um link para o seu painel publicado.

https://<deployment-url>/dashboardsv3/<resource_id>/published

Para construir seu link exclusivo:

  • Substitua <deployment-url> pela URL de implantação. Esse link é o endereço na barra de endereços do navegador quando você estiver na página inicial do workspace do Azure Databricks.
  • Substitua <resource_id> pelo valor da propriedade "resource_id" que você identificou em recuperar metadados.

Etapa 7: Excluir um painel

Para excluir um painel, use a interface de programação de aplicativos do Workspace. Veja POST /api/2.0/workspace/delete.

Importante

Essa é uma exclusão definitiva. Quando o comando é concluído, o painel é excluído permanentemente.

No exemplo a seguir, a solicitação inclui o caminho para o arquivo criado nas etapas anteriores.

POST /api/2.0/workspace/delete

Query parameters:
{
        "path": "/Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json"
}

Response:
{}

Próximas etapas