tutorial: gerenciar painéis de controle com o site Databricks REST API

Este site tutorial demonstra como gerenciar dashboards usando os sites Lakeview API e workspace 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 workspace API para recuperar um dashboard Lakeview como um objeto genérico workspace.

Pré-requisitos

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

A API da lista workspace 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 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"
    }
  ]
}

o passo 2: Exportar um dashboard

O workspace Export API GET /api/2.0/workspace /export permite que o senhor exporte o conteúdo de um painel como um arquivo. Os arquivos de painel do Lakeview 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 dashboard. Para explorar e entender mais detalhes da serialização, tente exportar alguns de seus próprios painéis.

faz 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 do Lakeview. 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 para que a resposta seja 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 site 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 um exemplo de resposta em que a propriedade "direct_download" é 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 workspace POST /api/2.0/workspace/import da API de importação para importar painéis de rascunho para um espaço de trabalho. 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 do Lakeview, 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 feitas 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: Opcionalmente sobrescrever na importação

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, em vez disso, o senhor 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, incluindo um painel do Lakeview. Consulte GET /api/2.0/workspace/get-status.

O exemplo a seguir mostra uma solicitação get-status para o dashboard 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 a API workspace, que permite trabalhar com painéis do Lakeview como objetos workspace genéricos. O exemplo a seguir usa a API do Lakeview para executar uma operação de publicação específica para os painéis do Lakeview. 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ários diferentes.

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. Consulte Publicar um painel para saber como funciona a configuração de credenciais incorporadas.

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 construir o link para seu painel publicado.

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

Para criar seu link exclusivo:

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

  • Substitua <resource_id> pelo valor da propriedade "resource_id" que o senhor identificou na recuperação de metadados.

o passo 7: Excluir um dashboard

Para excluir um painel, use a API workspace. Consulte POST /api/2.0/workspace/delete.

Importante

Essa é 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 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