Administración de tableros de control con API de Área de Trabajo
En este tutorial, se muestra cómo administrar paneles mediante la API de Lakeview y de Workspace. Cada paso incluye una solicitud y respuesta de ejemplo, así como explicaciones sobre cómo usar las propiedades y las herramientas de API juntas. Se puede hacer referencia a cada paso de manera individual. Siguiendo todos los pasos en orden, se le guiará a través de un flujo de trabajo completo.
Nota:
Este flujo de trabajo llama a la API de Workspace para recuperar un panel de IA/BI como un objeto de área de trabajo genérico. Los paneles de IA/BI se conocían anteriormente como paneles de Lakeview. Lakeview API conserva ese nombre.
Requisitos previos
- Configure la autenticación para acceder a los recursos de Azure Databricks. Para obtener información sobre las opciones de autenticación y obtener instrucciones de configuración, consulte Autorización del acceso a los recursos de Azure Databricks.
- Necesita las direcciones URL del área de trabajo a las que desea acceder. Consulte Nombres, direcciones URL e identificadores de instancias de áreas de trabajo.
- Familiaridad con la referencia de la API de REST de Databricks.
Paso 1: Explorar un directorio del área de trabajo
La API de Workspace List GET /api/2.0/workspace/list le permite explorar la estructura de los directorios del área de trabajo. Por ejemplo, puede recuperar una lista de todos los archivos y directorios del área de trabajo actual.
En el ejemplo siguiente, la propiedad path
de la solicitud apunta a una carpeta denominada examples_folder
almacenada en la carpeta principal de un usuario. El nombre de usuario se proporciona en la ruta de acceso, first.last@example.com
.
La respuesta muestra que la carpeta contiene un archivo de texto, un directorio y un panel 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"
}
]
}
Paso 2: Exportar un panel
La API Workspace Export GET /api/2.0/workspace/export permite exportar el contenido de un panel como un archivo. Los archivos de panel de IA/BI reflejan la versión preliminar del panel. La respuesta de los ejemplos siguientes muestra el contenido de una definición de panel mínima. Para explorar y comprender más detalles de serialización, intente exportar algunos de sus propios paneles.
Descargar el archivo exportado
En el ejemplo siguiente, se muestra cómo descargar un archivo de panel mediante la API.
La propiedad "path"
de este ejemplo termina con la extensión de tipo de archivo lvdash.json
, un panel de IA/BI. El nombre de archivo, como aparece en el área de trabajo, precede a esa extensión. En este caso, es mydashboard
.
Además, la propiedad "direct_download"
para esta solicitud se establece en true
, por lo que la respuesta es el propio archivo exportado y la propiedad "format"
se establece en "AUTO"
.
Nota:
La propiedad "displayName"
, que se muestra en la propiedad pages de la respuesta, no refleja el nombre visible del panel en el área de trabajo.
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 el archivo exportado
En el código siguiente se muestra una respuesta de ejemplo en la que la propiedad "direct_download"
está establecida en false. La respuesta incluye contenido como una cadena codificada en 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"
}
Paso 3: Importar un panel
Puedes usar la API de Workspace Import POST /api/2.0/workspace/import para importar paneles de borrador en un área de trabajo. Por ejemplo, después de exportar un archivo codificado, como en el ejemplo anterior, puede importar ese panel a una nueva área de trabajo.
Para que una importación se reconozca como un panel de IA/BI, se deben establecer dos parámetros:
"format"
: "AUTO": este valor permitirá al sistema detectar automáticamente el tipo de recurso."path"
: debe incluir una ruta de acceso de archivo que termine con ".lvdash.json".
Importante
Si estos valores no están configurados correctamente, la importación podría realizarse correctamente, pero el panel se trataría como un archivo normal.
En el ejemplo siguiente se muestra una solicitud de importación configurada correctamente.
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:
{}
Paso 4: Sobrescribir en la importación (opcional)
Si se intenta volver a emitir la misma solicitud de API, se produce el siguiente error:
{
"error_code": "RESOURCE_ALREADY_EXISTS",
"message": "Path (/Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json) already exists."
}
Si quiere sobrescribir la solicitud duplicada en su lugar, establezca la propiedad "overwrite"
en true
como en el ejemplo siguiente.
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:
{}
Paso 5: Recuperar metadatos
Puede recuperar los metadatos de cualquier objeto de área de trabajo, incluido un panel de IA/BI. Consulte GET /api/2.0/workspace/get-status.
En el ejemplo siguiente se muestra una solicitud get-status
para el panel importado del ejemplo anterior. La respuesta incluye detalles que afirman que el archivo se ha importado correctamente como "DASHBOARD"
. Además, consta de una propiedad "resource_id"
que se puede usar como identificador con la API de 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"
}
Paso 6: Publicar un panel
En los ejemplos anteriores se usaba la API de Workspace, lo que habilitaba el trabajo con paneles de IA/BI como objetos de área de trabajo genéricos. En el ejemplo siguiente se usa la API de Lakeview para realizar una operación de publicación específica de los paneles de IA/BI. Consulte POST /api/2.0/lakeview/dashboards/{dashboard_id}/published.
La ruta de acceso al punto de conexión de la API incluye la propiedad "resource_id"
devuelta en el ejemplo anterior. En los parámetros de solicitud, "embed_credentials"
se establece en true
para que las credenciales del publicador se inserten en el panel. El publicador, en este caso, es el usuario que realiza la solicitud de API autorizada. El publicador no puede insertar credenciales de usuario diferentes. Consulte Publicación de un panel para obtener información sobre cómo funciona el valor Insertar credenciales.
La propiedad "warehouse_id"
establece el almacenamiento que se usará para el panel publicado. Si se especifica, esta propiedad invalida el almacén especificado para el panel de borrador, si existe.
POST /api/2.0/lakeview/dashboards/9c1fbf4ad3449be67d6cb64c8acc730b/published
Request parameters
{
"embed_credentials": true,
"warehouse_id": "1234567890ABCD12"
}
Response:
{}
Se puede acceder al panel publicado desde el explorador cuando se complete el comando. En el ejemplo siguiente se muestra cómo crear el enlace a su tablero de mandos publicado.
https://<deployment-url>/dashboardsv3/<resource_id>/published
Para construir tu enlace único:
- Reemplace
<deployment-url>
por la dirección URL de implementación. Este vínculo es la dirección de la barra de direcciones del explorador cuando se encuentra en la página principal del área de trabajo de Azure Databricks. - Reemplaza
<resource_id>
por el valor de la propiedad"resource_id"
que identificaste en recuperar metadatos.
Paso 7: Eliminar un panel
Para eliminar un panel, use la API de espacio de trabajo. Consulte POST /api/2.0/workspace/delete.
Importante
Se trata de una eliminación permanente. Cuando se completa el comando, el panel se elimina permanentemente.
En el ejemplo siguiente, la solicitud incluye la ruta de acceso al archivo creado en los pasos anteriores.
POST /api/2.0/workspace/delete
Query parameters:
{
"path": "/Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json"
}
Response:
{}
Pasos siguientes
- Para obtener más información sobre los paneles, consulte Paneles.
- Para obtener más información sobre la API REST, consulta Referencia de la API REST de Databricks.