Administración de paneles con las API de áreas 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. Seguir todos los pasos en orden le guía 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 Lakeview como un objeto de área de trabajo genérico.
Requisitos previos
- Necesita un token de acceso personal para conectarse con el área de trabajo. Consulta Autenticación de token de acceso personal de Azure Databricks.
- Necesita el identificador del área de trabajo a la 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 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"
}
]
}
Paso 2: exportar un panel
La API de Workspace Export GET /api/2.0/workspace/export le permite exportar el contenido de un panel como un archivo. Los archivos del panel de Lakeview reflejan la versión de borrador de un 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 Lakeview. 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"
de esta solicitud se establece en true
para que la respuesta sea el propio archivo exportado.
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
}
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
Puede 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 Lakeview, 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 desea 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 metadatos para cualquier objeto de área de trabajo, incluido un panel de Lakeview. 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 Lakeview 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 Lakeview. 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 construir el vínculo al panel publicado.
https://<deployment-url>/dashboardsv3/<resource_id>/published
Para construir el vínculo ú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. - Reemplace
<resource_id>
por el valor de la propiedad"resource_id"
que identificó en recuperar metadatos.
Paso 7: eliminar un panel
Para eliminar un panel, use la API de Workspace. 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 más información sobre los paneles, consulte Paneles.
- Para obtener más información sobre la API de REST, consulte Referencia de la API de REST de Databricks.
Comentarios
https://aka.ms/ContentUserFeedback.
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea:Enviar y ver comentarios de