Gerenciar dashboards com APIs do Workspace
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 de IA/BI como um objeto de workspace genérico.
Pré-requisitos
- Você precisa de um token de acesso pessoal para se conectar ao seu workspace. Confira Autenticação com tokens de acesso pessoal do Azure Databricks.
- Você precisa da ID do workspace que deseja acessar. Confira Nomes, URLs e IDs de instância do workspace
- Familiaridade com a referência da API REST do Databricks.
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 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 workspace 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 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 de IA/BI. 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 de IA/BI, 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 de IA/BI. 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 de IA/BI 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 de IA/BI. 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
- Para saber mais sobre paineis, consulte Paineis.
- Para saber mais sobre a API REST, confira a referência da API REST do Databricks.