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

Este tutorial demonstra como gerenciar dashboards usando o Lakeview API e o espaço de trabalho API. Cada passo inclui um exemplo de solicitação e resposta e explicações sobre como usar as ferramentas e propriedades do API em conjunto. Cada o passo pode ser referenciado por si só. Seguir todos os passos para guiá-lo por um fluxo de trabalho completo.

Observação

Esse fluxo de trabalho chama o espaço de trabalho API para recuperar um painel AI/BI como um objeto workspace genérico. AI/BI Os painéis eram conhecidos anteriormente como Lakeview dashboards. O Lakeview API ainda mantém esse nome.

Pré-requisitos

o passo 1: Explorar um diretório workspace

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

No exemplo a seguir, a propriedade path na solicitação aponta para uma pasta chamada examples_folder armazenada na pasta home do 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 controle AI/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"
    }
  ]
}

o passo 2: Exportar um dashboard

O espaço de trabalho Export API GET /api/2.0/workspace /export permite exportar o conteúdo de um painel como um arquivo. Os arquivos de painel AI/BI refletem a versão preliminar 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 da serialização, tente exportar alguns de seus próprios painéis.

Faça o download do arquivo exportado

O exemplo a seguir mostra como fazer o download de 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 AI/BI. O nome do arquivo, como aparece no site workspace, precede essa extensão. Nesse caso, é mydashboard.

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

Observação

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

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 um exemplo de resposta em que a propriedade "direct_download" está definida como false. A resposta contém o 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"
}

o passo 3: Importar um dashboard

O senhor pode usar o espaço de trabalho Import API 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, o senhor pode importar esse painel para um novo workspace.

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

  • "format": "AUTO" - essa configuração permitirá que o sistema detecte o tipo de ativo automaticamente.

  • "path"O senhor deve incluir um caminho de arquivo que termine com ".lvdash.JSON".

Importante

Se essas configurações não forem definidas 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:
{}

o passo 4: Overwrite on import (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:
{}

o passo 5: Recuperar metadados

O senhor pode recuperar metadados de qualquer objeto do site workspace, inclusive um painel do site AI/BI. Consulte 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 que afirmam que o arquivo foi importado com sucesso como "DASHBOARD". Além disso, ele consiste em uma propriedade "resource_id" que o senhor pode usar como 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"
}

o passo 6: Publicar um painel

Os exemplos anteriores usaram o espaço de trabalho API, permitindo trabalhar com painéis AI/BI como objetos workspace genéricos. O exemplo a seguir usa o endereço Lakeview API para realizar operações de publicação específicas para os painéis AI/BI. Consulte POST /api/2.0/Lakeview/dashboards/{dashboard_id}/published.

O caminho para o endpoint da API inclui a propriedade "resource_id" retornada no exemplo anterior. Nos parâmetros da solicitação, "embed_credentials" é definido como true para que as credenciais do editor sejam incorporadas ao painel. O editor, nesse 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 Publicar um painel para saber como a configuração de credenciais de incorporação funciona.

A propriedade "warehouse_id" define o depósito a ser usado para o painel publicado. Se especificada, essa propriedade substitui o depósito 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 no seu navegador quando o comando for concluído. O exemplo a seguir mostra como criar o link para seu painel publicado.

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

Para criar seu link exclusivo:

  • Substitua <deployment-url> pelo seu URL de implantação. Esse link é o endereço na barra de endereços do navegador quando o senhor está na página inicial do Databricks workspace .

  • Substitua <resource_id> pelo valor da propriedade "resource_id" que você identificou nos metadados de recuperação.

o passo 7: Excluir um dashboard

Para excluir um dashboard, use o espaço de trabalho API. Consulte POST /api/2.0/workspace/delete.

Importante

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

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

POST /api/2.0/workspace/delete

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

Response:
{}

Próximos passos