Samouczek: zarządzanie pulpitami nawigacyjnymi za pomocą interfejsów API obszaru roboczego

Artykuł
04/27/2024

W tym samouczku pokazano, jak zarządzać pulpitami nawigacyjnymi przy użyciu interfejsu API usługi Lakeview i interfejsu API obszaru roboczego. Każdy krok zawiera przykładowe żądanie i odpowiedź oraz wyjaśnienia dotyczące sposobu używania narzędzi interfejsu API i właściwości razem. Każdy krok można odwoływać się samodzielnie. Wykonanie wszystkich kroków w kolejności przeprowadzi Cię przez kompletny przepływ pracy.

Uwaga

Ten przepływ pracy wywołuje interfejs API obszaru roboczego w celu pobrania pulpitu nawigacyjnego usługi Lakeview jako ogólnego obiektu obszaru roboczego.

Wymagania wstępne

Do nawiązania połączenia z obszarem roboczym potrzebny jest osobisty token dostępu. Zobacz Uwierzytelnianie osobistego tokenu dostępu w usłudze Azure Databricks.
Potrzebny jest identyfikator obszaru roboczego obszaru roboczego, do którego chcesz uzyskać dostęp. Zobacz Nazwy, adresy URL i identyfikatory wystąpień obszaru roboczego
Znajomość dokumentacji interfejsu API REST usługi Databricks.

Krok 1. Eksplorowanie katalogu obszaru roboczego

Interfejs API listy obszarów roboczych GET /api/2.0/workspace/list umożliwia eksplorowanie struktury katalogów obszaru roboczego. Możesz na przykład pobrać listę wszystkich plików i katalogów w bieżącym obszarze roboczym.

W poniższym przykładzie path właściwość w żądaniu wskazuje folder o nazwie examples_folder przechowywanej w folderze głównym użytkownika. Nazwa użytkownika jest podana w ścieżce first.last@example.com.

Odpowiedź pokazuje, że folder zawiera plik tekstowy, katalog i pulpit nawigacyjny usługi 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"
    }
  ]
}

Krok 2. Eksportowanie pulpitu nawigacyjnego

Interfejs API eksportu obszaru roboczego GET /api/2.0/workspace/export umożliwia wyeksportowanie zawartości pulpitu nawigacyjnego jako pliku. Pliki pulpitu nawigacyjnego usługi Lakeview odzwierciedlają wersję roboczą pulpitu nawigacyjnego. Odpowiedź w poniższych przykładach przedstawia zawartość minimalnej definicji pulpitu nawigacyjnego. Aby zapoznać się z bardziej szczegółowymi informacjami o serializacji, spróbuj wyeksportować niektóre własne pulpity nawigacyjne.

Pobieranie wyeksportowanego pliku

W poniższym przykładzie pokazano, jak pobrać plik pulpitu nawigacyjnego przy użyciu interfejsu API.

Właściwość "path" w tym przykładzie kończy się rozszerzeniem lvdash.jsontypu pliku , pulpitem nawigacyjnym usługi Lakeview. Nazwa pliku wyświetlana w obszarze roboczym poprzedza to rozszerzenie. W tym przypadku jest to mydashboard.

"direct_download" Ponadto właściwość tego żądania jest ustawiona na true wartość , więc odpowiedź jest eksportowanym plikiem.

Uwaga

Właściwość "displayName" wyświetlana we właściwości pages odpowiedzi nie odzwierciedla widocznej nazwy pulpitu nawigacyjnego w obszarze roboczym.

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

Kodowanie wyeksportowanego pliku

Poniższy kod przedstawia przykładową odpowiedź, w której "direct_download" właściwość jest ustawiona na false. Odpowiedź zawiera zawartość jako ciąg zakodowany w formacie 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"
}

Krok 3. Importowanie pulpitu nawigacyjnego

Możesz użyć interfejsu API importu obszaru roboczego POST /api/2.0/workspace/import , aby zaimportować robocze pulpity nawigacyjne do obszaru roboczego. Na przykład po wyeksportowaniu zakodowanego pliku, tak jak w poprzednim przykładzie, możesz zaimportować ten pulpit nawigacyjny do nowego obszaru roboczego.

Aby import był rozpoznawany jako pulpit nawigacyjny usługi Lakeview, należy ustawić dwa parametry:

"format": "AUTO" — to ustawienie umożliwi systemowi automatyczne wykrywanie typu zasobu.
- "path": musi zawierać ścieżkę pliku kończącą się ciągiem ".lvdash.json".

Ważne

Jeśli te ustawienia nie są prawidłowo skonfigurowane, importowanie może zakończyć się powodzeniem, ale pulpit nawigacyjny będzie traktowany jak zwykły plik.

W poniższym przykładzie przedstawiono prawidłowo skonfigurowane żądanie importu.


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

Krok 4. Zastępowanie przy importowaniu (opcjonalnie)

Próba ponownego zainicjowania tego samego żądania interfejsu API powoduje następujący błąd:

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

Jeśli zamiast tego chcesz zastąpić zduplikowane żądanie, ustaw "overwrite" właściwość na true tak, jak w poniższym przykładzie.


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

Krok 5. Pobieranie metadanych

Metadane dla dowolnego obiektu obszaru roboczego, w tym pulpit nawigacyjny usługi Lakeview, można pobrać. Zobacz GET /api/2.0/workspace/get-status.

Poniższy przykład przedstawia get-status żądanie zaimportowanego pulpitu nawigacyjnego z poprzedniego przykładu. Odpowiedź zawiera szczegóły potwierdzające, że plik został pomyślnie zaimportowany jako "DASHBOARD". Ponadto składa się z "resource_id" właściwości, której można użyć jako identyfikatora z interfejsem API usługi 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"
}

Krok 6. Publikowanie pulpitu nawigacyjnego

W poprzednich przykładach użyto interfejsu API obszaru roboczego, umożliwiając pracę z pulpitami nawigacyjnymi usługi Lakeview jako ogólnymi obiektami obszaru roboczego. W poniższym przykładzie użyto interfejsu API usługi Lakeview do wykonania operacji publikowania specyficznej dla pulpitów nawigacyjnych usługi Lakeview. Zobacz POST /api/2.0/lakeview/dashboards/{dashboard_id}/published.

Ścieżka do punktu końcowego interfejsu API zawiera "resource_id" właściwość zwróconą w poprzednim przykładzie. W parametrach żądania jest ustawiona na true wartość , "embed_credentials" aby poświadczenia wydawcy zostały osadzone na pulpicie nawigacyjnym. W tym przypadku wydawcą jest użytkownik, który wysyła autoryzowane żądanie interfejsu API. Wydawca nie może osadzić poświadczeń innego użytkownika. Zobacz Publikowanie pulpitu nawigacyjnego , aby dowiedzieć się, jak działa ustawienie Osadzanie poświadczeń.

Właściwość "warehouse_id" ustawia magazyn do użycia dla opublikowanego pulpitu nawigacyjnego. Jeśli ta właściwość zostanie określona, zastąpi magazyn określony dla roboczego pulpitu nawigacyjnego, jeśli istnieje.

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

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

Response:
{}

Po zakończeniu wykonywania polecenia można uzyskać dostęp do opublikowanego pulpitu nawigacyjnego z przeglądarki. W poniższym przykładzie pokazano, jak utworzyć link do opublikowanego pulpitu nawigacyjnego.

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

Aby utworzyć unikatowy link:

Zastąp <deployment-url> ciąg adresem URL wdrożenia. Ten link jest adresem na pasku adresu przeglądarki, gdy jesteś na stronie głównej obszaru roboczego usługi Azure Databricks.
Zastąp <resource_id> element wartością "resource_id" właściwości zidentyfikowanej podczas pobierania metadanych.

Krok 7. Usuwanie pulpitu nawigacyjnego

Aby usunąć pulpit nawigacyjny, użyj interfejsu API obszaru roboczego. Zobacz POST /api/2.0/workspace/delete.