Tutorial: Administración de paneles con las API del área de trabajo

  • Artículo

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

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