Partilhar via

Gerenciar painéis com APIs de espaço de trabalho

  • Artigo

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

Observação

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

Pré-requisitos

  • Você precisa de um token de acesso pessoal para se conectar ao seu espaço de trabalho. Consulte a autenticação de token de acesso pessoal do Azure Databricks .
  • Você precisa da ID do espaço de trabalho que deseja acessar. Consulte nomes das instâncias, URLs e IDs do espaço de trabalho
  • Familiaridade com a referência da API REST do Databricks.

Etapa 1: Explorar um diretório de espaço de trabalho

A API de Lista de Espaços de Trabalho GET /api/2.0/workspace/list permite explorar 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 espaço de trabalho atual.

No exemplo a seguir, a propriedade path na solicitação aponta para uma pasta chamada examples_folder armazenada na pasta base 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 de espaço de trabalho GET /api/2.0/workspace/export permite exportar o conteúdo de um painel como um arquivo. Os arquivos do painel de IA/BI 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 de painel. Para explorar e entender mais detalhes de serialização, tente exportar alguns de seus próprios painéis.

Baixe 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 do tipo de ficheiro lvdash.json, que é um dashboard de AI/BI. O nome do arquivo, como aparece no espaço de trabalho, precede essa extensão. Neste caso, é 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"
    }
  ]
}

Codifique o arquivo exportado

O código a seguir mostra um exemplo de resposta em que "direct_download" propriedade está 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 espaço de trabalho POST /api/2.0/workspace/import para importar painéis de rascunho para um espaço de trabalho. Por exemplo, depois de exportar um arquivo codificado, como no exemplo anterior, você pode importar esse painel para um novo espaço de trabalho.

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

  • "format": "AUTO" - esta configuração permitirá que o sistema detete 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 normal.

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: Sobrescrever na Importação (Opcional)

A tentativa de reemitir a 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 espaço de trabalho, incluindo um painel de IA/BI. Consulte GET /api/2.0/workspace/get-status.

O exemplo a seguir mostra uma solicitação de 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 de espaço de trabalho, permitindo o trabalho com painéis de IA/BI como objetos de espaço de trabalho 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. Consulte 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" é definido como true para que as credenciais do editor sejam incorporadas no painel. O editor, neste caso, é o usuário que está fazendo a solicitação de API autorizada. O editor não pode incorporar credenciais de usuário diferentes. Consulte para saber como a configuração de incorporar credenciais funciona ao Publicar um painel.

A propriedade "warehouse_id" define o armazém a ser usado para o painel publicado. Se especificado, esta propriedade substitui o armazém especificado para o painel de esboço, 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 a partir do seu navegador quando o comando estiver concluído. O exemplo a seguir mostra como construir o link para seu painel publicado.

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

Para construir o seu link exclusivo:

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

Etapa 7: Eliminar um painel

Para eliminar um painel, utilize a API do Espaço de Trabalho. Consulte POST /api/2.0/workspace/delete.

Importante

Esta é uma exclusão difícil. 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óximos passos

  • Para saber mais sobre painéis, consulte Painéis.
  • Para saber mais sobre a API REST, consulte a referência da API REST do Databricks .