Udostępnij za pośrednictwem

Zarządzanie pulpitami nawigacyjnymi za pomocą interfejsów API Workspace

  • Artykuł

W tym samouczku pokazano, jak zarządzać kokpitami przy użyciu interfejsu API Lakeview i interfejsu API Workspace. 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 odnieść samodzielnie. Wykonanie wszystkich kroków w kolejności przeprowadzi Cię przez kompletny przepływ pracy.

Notatka

Ten przepływ pracy wywołuje interfejs API obszaru roboczego w celu pobrania pulpitu nawigacyjnego AI/BI jako ogólnego obiektu obszaru roboczego. Kokpity AI/BI były wcześniej znane jako kokpity Lakeview. Interfejs API usługi Lakeview zachowuje tę nazwę.

Warunki wstępne

Krok 1. Eksplorowanie katalogu obszarów roboczych

API listy obszaru roboczego 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 właściwość path w żądaniu wskazuje folder o nazwie examples_folder przechowywany 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 AI/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"
    }
  ]
}

Krok 2. Eksportowanie pulpitu nawigacyjnego

Interfejs API eksportu obszaru roboczego GET /api/2.0/workspace/export umożliwia eksportowanie zawartości pulpitu nawigacyjnego jako pliku. Pliki pulpitu nawigacyjnego AI/BI odzwierciedlają wersję roboczą pulpitu nawigacyjnego. Odpowiedź w poniższych przykładach przedstawia zawartość minimalnej definicji pulpitu nawigacyjnego. Aby zapoznać się z większą liczbą szczegółów dotyczących serializacji, spróbuj wyeksportować niektóre z własnych pulpitów nawigacyjnych.

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 typu pliku lvdash.json, pulpit nawigacyjny AI/BI. Nazwa pliku wyświetlana w obszarze roboczym poprzedza to rozszerzenie. W tym przypadku jest to mydashboard.

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

Notatka

Właściwość "displayName" wyświetlana we właściwości 'pages' w odpowiedzi nie odzwierciedla widocznej nazwy dashboardu 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,
  "format": "AUTO"
}

Response:
{
  "pages": [
    {
      "name": "880de22a",
      "displayName": "New Page"
    }
  ]
}

Kodowanie wyeksportowanego pliku

Poniższy kod przedstawia przykładową odpowiedź, w której właściwość "direct_download" jest ustawiona na wartość 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

Do zaimportowania roboczych pulpitów nawigacyjnych do obszaru roboczego można użyć interfejsu API importu POST /api/2.0/workspace/import. 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 AI/BI, 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żny

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: Nadpisz podczas importu (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 właściwość "overwrite" na true, 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

Możesz pobrać metadane dla dowolnego obiektu obszaru roboczego, w tym pulpit nawigacyjny AI/BI. Zobacz GET /api/2.0/workspace/get-status.

Poniższy przykład przedstawia żądanie get-status dotyczące pulpitu nawigacyjnego zaimportowanego z początkowego przykładu. Odpowiedź zawiera szczegółowe informacje potwierdzające, że plik został pomyślnie zaimportowany jako "DASHBOARD". Ponadto zawiera właściwość "resource_id", której można użyć jako identyfikatora w interfejsie 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"
}

Krok 6. Publikowanie pulpitu nawigacyjnego

W poprzednich przykładach użyto interfejsu API obszaru roboczego, umożliwiając pracę z pulpitami nawigacyjnymi sztucznej inteligencji/analizy biznesowej 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 sztucznej inteligencji/analizy biznesowej. Zobacz POST /api/2.0/lakeview/dashboards/{dashboard_id}/published.

Ścieżka do punktu końcowego API zawiera właściwość "resource_id" zwróconą w poprzednim przykładzie. W parametrach żądania wartość "embed_credentials" jest ustawiona na true, aby poświadczenia wydawcy były osadzone w 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" określa magazyn, który ma być użyty dla opublikowanego pulpitu nawigacyjnego. Jeśli została określona, ta właściwość zastąpi magazyn wskazany dla szkicowego pulpitu, o ile taki 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> 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> wartością właściwości "resource_id", którą zidentyfikowano w , aby pobrać metadane.

Krok 7. Usuwanie pulpitu nawigacyjnego

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

Ważny

Jest to definitywne usunięcie. Po zakończeniu wykonywania polecenia pulpit nawigacyjny zostanie trwale usunięty.

W poniższym przykładzie żądanie zawiera ścieżkę do pliku utworzonego w poprzednich krokach.

POST /api/2.0/workspace/delete

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

Response:
{}

Następne kroki