Руководство по управлению панелями мониторинга с помощью API рабочих областей

В этом руководстве показано, как управлять панелями мониторинга с помощью API Lakeview и API рабочей области. Каждый шаг включает пример запроса и ответа, а также объяснения того, как использовать инструменты и свойства API вместе. Каждый шаг можно ссылаться самостоятельно. Следуя всем шагам по порядку, вы можете пройти полный рабочий процесс.

Примечание.

Этот рабочий процесс вызывает API рабочей области для получения панели мониторинга Lakeview в качестве универсального объекта рабочей области.

Необходимые компоненты

• Для подключения к рабочей области требуется личный маркер доступа. См . проверку подлинности маркера личного доступа Azure Databricks.
• Вам нужен идентификатор рабочей области рабочей области, к которой вы хотите получить доступ. См. имена экземпляров рабочей области, URL-адреса и идентификаторы
• Знакомство со справочником по REST API Databricks.

Шаг 1. Изучение каталога рабочей области

API списка рабочих областей GET /api/2.0/workspace/list позволяет изучить структуру каталогов рабочей области. Например, можно получить список всех файлов и каталогов в текущей рабочей области.

В следующем примере path свойство в запросе указывает на папку с именем, examples_folder хранящейся в домашней папке пользователя. Имя пользователя указывается в пути. first.last@example.com

В ответе показано, что папка содержит текстовый файл, каталог и панель мониторинга 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"
    }
  ]
}

Шаг 2. Экспорт панели мониторинга

API экспорта рабочей области GET /api/2.0/workspace/export позволяет экспортировать содержимое панели мониторинга в виде файла. Файлы панели мониторинга Lakeview отражают черновую версию панели мониторинга. В ответе в следующих примерах показано содержимое минимального определения панели мониторинга. Чтобы изучить и понять больше сведений о сериализации, попробуйте экспортировать некоторые из собственных панелей мониторинга.

Скачивание экспортированного файла

В следующем примере показано, как скачать файл панели мониторинга с помощью API.

Свойство "path" в этом примере заканчивается расширением lvdash.jsonтипа файла , панелью мониторинга Lakeview. Имя файла, отображаемое в рабочей области, предшествует этому расширению. В этом случае это mydashboard.

Кроме того, для этого запроса задано true свойство, "direct_download" чтобы ответ был экспортированным файлом.

Примечание.

Свойство "displayName" , показанное в свойстве страниц ответа, не отражает видимое имя панели мониторинга в рабочей области.

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"
    }
  ]
}

Кодирование экспортированного файла

В следующем коде показан пример ответа, в котором "direct_download" свойству присвоено значение false. Ответ содержит содержимое в виде строки в кодировке 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"
}

Шаг 3. Импорт панели мониторинга

С помощью API импорта рабочей области POST /api /2.0/workspace/import можно импортировать черновики панелей мониторинга в рабочую область. Например, после экспорта закодированного файла, как и в предыдущем примере, можно импортировать эту панель мониторинга в новую рабочую область.

Чтобы импортировать как панель мониторинга Lakeview, необходимо задать два параметра:

• "format": AUTO — этот параметр позволит системе автоматически обнаруживать тип ресурса.
  • "path": должен содержать путь к файлу, заканчивающийся ".lvdash.json".

Внимание

Если эти параметры настроены неправильно, импорт может завершиться успешно, но панель мониторинга будет рассматриваться как обычный файл.

В следующем примере показан правильно настроенный запрос на импорт.

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:
{}

Шаг 4. Перезапись при импорте (необязательно)

Попытка повторного получения одного запроса API приводит к следующей ошибке:

{
        "error_code": "RESOURCE_ALREADY_EXISTS",
        "message": "Path (/Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json) already exists."
}

Если вы хотите перезаписать повторяющийся запрос, задайте "overwrite" для true свойства значение, как показано в следующем примере.

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:
{}

Шаг 5. Получение метаданных

Вы можете получить метаданные для любого объекта рабочей области, включая панель мониторинга Lakeview. См. статью GET /api/2.0/workspace/get-status.

В следующем примере показан запрос на get-status импортированную панель мониторинга из предыдущего примера. В ответе содержатся сведения о том, что файл успешно импортирован в виде "DASHBOARD". Кроме того, он состоит из "resource_id" свойства, которое можно использовать в качестве идентификатора с API 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"
}

Шаг 6. Публикация панели мониторинга

В предыдущих примерах использовался API рабочей области, что позволяет работать с панелями мониторинга Lakeview в качестве универсальных объектов рабочей области. В следующем примере API Lakeview используется для выполнения операции публикации, относящегося к панелям мониторинга Lakeview. См. раздел POST /api/2.0/lakeview/dashboards/{dashboard_id}/published.

Путь к конечной точке API включает "resource_id" свойство, возвращаемое в предыдущем примере. В параметрах запроса задано true значение, "embed_credentials" чтобы учетные данные издателя были внедрены на панель мониторинга. В этом случае издатель — это пользователь, выполняющий авторизованный запрос API. Издатель не может внедрить разные учетные данные пользователя. См. статью "Публикация панели мониторинга ", чтобы узнать, как работает параметр "Внедрить учетные данные".

Свойство "warehouse_id" задает хранилище, которое будет использоваться для опубликованной панели мониторинга. Если задано, это свойство переопределяет хранилище, указанное для черновика панели мониторинга, если таковой есть.

POST /api/2.0/lakeview/dashboards/9c1fbf4ad3449be67d6cb64c8acc730b/published

Request parameters
{
  "embed_credentials": true,
  "warehouse_id": "1234567890ABCD12"
}

Response:
{}

После завершения команды доступ к опубликованной панели мониторинга можно получить из браузера. В следующем примере показано, как создать ссылку на опубликованную панель мониторинга.

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

Чтобы создать уникальную ссылку, выполните приведенные выше действия.

• Замените <deployment-url> URL-адрес развертывания. Эта ссылка — это адрес в адресной строке браузера, когда вы находитесь на домашней странице рабочей области Azure Databricks.
• Замените <resource_id> значением "resource_id" свойства, которое вы определили в извлекаемых метаданных.

Шаг 7. Удаление панели мониторинга

Чтобы удалить панель мониторинга, используйте API рабочей области. См. раздел POST /api/2.0/workspace/delete.

Внимание

Это жесткое удаление. По завершении команды панель мониторинга удаляется безвозвратно.

В следующем примере запрос содержит путь к файлу, созданному на предыдущих шагах.

POST /api/2.0/workspace/delete

Query parameters:
{
        "path": "/Users/first.last@example.com/examples_folder/myseconddashboard.lvdash.json"
}

Response:
{}

Следующие шаги

• Дополнительные сведения о панелях мониторинга см. в разделе "Панели мониторинга".
• Дополнительные сведения о REST API см . в справочнике по REST API Databricks.