Tutorial: Gerenciar painéis com APIs do Workspace

  • Artigo

Este tutorial demonstra como gerenciar painéis do Lakeview 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ê em um fluxo de trabalho completo.

Observação

Esse fluxo de trabalho chama a API do workspace para recuperar um painel do Lakeview como um objeto de workspace genérico.

Pré-requisitos

Etapa 1: Explorar um diretório de workspace

A lista de workspaces da API GET /api/2.0/workspace/list permite explorar a estrutura de diretório do seu workspace. Por exemplo, você pode recuperar uma lista de todos os arquivos e diretórios em seu workspace atual.

No exemplo a seguir, a propriedade path 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 do Lakeview.

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 de workspace GET /api/2.0/workspace/export permite exportar o conteúdo de um painel como um arquivo. Os arquivos de painel do Lakeview refletem a versão de rascunho de um painel. 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 painéis.

Baixar o arquivo exportado

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

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

Além disso, a propriedade "direct_download" desta solicitação é definida como true, portanto, a resposta é o próprio arquivo exportado.

Observação

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

GET /api/2.0/workspace/export

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

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

Codificar o arquivo exportado

O código a seguir mostra uma resposta de exemplo em que a propriedade "direct_download" é 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 de workspace POST /api/2.0/workspace/import para importar painéis de rascunho 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 do Lakeview, dois parâmetros devem ser definidos:

  • "format": "AUTO" – esta 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 do Lakeview. Confira 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 do 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 do Lakeview como objetos de workspace genéricos. O exemplo a seguir usa a API do Lakeview para executar uma operação de publicação específica aos painéis do Lakeview. Confira POST /api/2.0/lakeview/dashboards/{dashboard_id}/publicado.

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" é definido 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. Confira Publicar um painel para saber como funciona a configuração de Inserção de credenciais.

A propriedade "warehouse_id" define o warehouse a ser usado para o painel publicado. Se especificada, essa propriedade substituirá 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 construir o link para o painel publicado.

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

Para construir o 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 API do workspace. Confira POST /api/2.0/workspace/delete.

Importante

Esta é uma exclusão difícil. Quando o comando for concluído, o painel será 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