Użyj interfejsów API pulpitów nawigacyjnych do tworzenia i zarządzania pulpitami nawigacyjnymi

Interfejs API REST usługi Databricks zawiera narzędzia do zarządzania przeznaczone specjalnie do zarządzania pulpitami nawigacyjnymi sztucznej inteligencji/analizy biznesowej. W tym artykule pokazano, jak utworzyć nowy pulpit nawigacyjny sztucznej inteligencji/analizy biznesowej na podstawie istniejącego starszego pulpitu nawigacyjnego. Następnie pokazuje, jak zarządzać pulpitem nawigacyjnym za pomocą narzędzi interfejsu API.

Notatka

Pulpity nawigacyjne sztucznej inteligencji/analizy biznesowej były wcześniej znane jako pulpity nawigacyjne usługi Lakeview. Interfejs API usługi Lakeview nadal zachowuje tę nazwę.

Warunki wstępne

Konfigurowanie uwierzytelniania w celu uzyskania dostępu do zasobów usługi Azure Databricks. Aby dowiedzieć się więcej na temat opcji uwierzytelniania i uzyskać instrukcje dotyczące konfiguracji, zobacz Autoryzowanie dostępu do zasobów usługi Azure Databricks.
Potrzebne są adresy URL obszaru roboczego, do których chcesz uzyskać dostęp. Zobacz nazwy wystąpień obszaru roboczego, adresy URL i identyfikatory.
Znajomość referencji interfejsu API REST Databricks.

Migrowanie pulpitu nawigacyjnego

Nowy pulpit nawigacyjny sztucznej inteligencji/analizy biznesowej można utworzyć na podstawie istniejącego starszego pulpitu nawigacyjnego. Końcowy punkt Migrate dashboard w interfejsie API Lakeview wymaga source_dashboard_id. Opcjonalnie możesz dołączyć nazwę wyświetlaną i ścieżkę, w której ma być przechowywany nowy pulpit nawigacyjny.

Uzyskaj klasyczne pulpity nawigacyjne

Aby uzyskać source_dashboard_id, użyj starszego interfejsu API pulpitów nawigacyjnych, aby uzyskać listę wszystkich pulpitów nawigacyjnych w obszarze roboczym. Każdy obiekt pulpitu nawigacyjnego na liście results zawiera identyfikator UUID, którego można użyć do odwoływania się do starszego pulpitu nawigacyjnego w usługach interfejsu API REST usługi Azure Databricks.

W następującym przykładzie przedstawiono żądanie i odpowiedź dla punktu końcowego Uzyskaj obiekty pulpitu nawigacyjnego. Niektóre szczegóły odpowiedzi zostały pominięte w celu uzyskania jasności. Zobacz GET /api/2.0/preview/sql/dashboards, aby uzyskać pełny opis tego punktu końcowego i przykładowej odpowiedzi.

Identyfikator UUID dla starszego panelu to id z najwyższego poziomu listy obiektów zwracanych w results. W przypadku starszych pulpitów nawigacyjnych identyfikator UUID wygląda następująco: 4e443c27-9f61-4f2e-a12d-ea5668460bf1.

GET /api/2.0/preview/sql/dashboards

Query Parameters:

{
"page_size": <optional>,
"page": <optional>,
"order": <optional>
"q": <optional>
}

Response:

{
  "count": 1,
  "page": 1,
  "page_size": 25,
  "results": [
    {
      "id": "4e443c27-9f61-4f2e-a12d-ea5668460bf1",
      "slug": "sales-dashboard",
      "parent": "folders/2025532471912059",
      ...
    }
  ]
}

Migrowanie starszego pulpitu nawigacyjnego

Użyj identyfikatora UUID skojarzonego ze starszym pulpitem nawigacyjnym, aby utworzyć kopię, która jest automatycznie konwertowana na nowy pulpit nawigacyjny AI/BI. Działa to podobnie jak narzędzie Clone to AI/BI dashboard dostępne w interfejsie użytkownika (Klonowanie do pulpitu nawigacyjnego sztucznej inteligencji/analizy biznesowej). Zobacz Klonowanie starszego pulpitu nawigacyjnego do pulpitu nawigacyjnego usługi AI/BI, aby dowiedzieć się, jak wykonać tę operację przy użyciu interfejsu użytkownika usługi Azure Databricks.

Identyfikator UUID starszego pulpitu nawigacyjnego, który chcesz przekonwertować, jest wymagany w treści żądania. Opcjonalnie możesz dołączyć nową wartość display_name i parent_path identyfikującą ścieżkę obszaru roboczego folderu, w którym ma być przechowywany przekonwertowany pulpit nawigacyjny.

Odpowiedź zawiera dashboard_id, identyfikator UUID nowego pulpitu nawigacyjnego. Identyfikator UUID dla panelu AI/BI to 32-znakowa wartość alfanumeryczna, na przykład 04aab30f99ea444490c10c85852f216c. Możesz go użyć do identyfikacji tego pulpitu nawigacyjnego w przestrzeni nazw Lakeview i w ramach różnych usług interfejsu API REST dla Azure Databricks.

W poniższym przykładzie przedstawiono przykładowe żądanie i odpowiedź. Zapoznaj się z POST /api/2.0/lakeview/dashboards/migrate.

POST /api/2.0/lakeview/dashboards/migrate

Request body parameters:
{
  "source_dashboard_id": "4e443c27-9f61-4f2e-a12d-ea5668460bf1",
  "display_name": "Monthly Traffic Report",
  "parent_path": "/path/to/dir"
}

Response:
{
  "dashboard_id": "04aab30f99ea444490c10c85852f216c",
  "display_name": "Monthly Traffic Report",
  "path": "/path/to/dir/Monthly Traffic Report.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "47bb1c472649e711",
  "etag": "80611980",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

Uzyskaj dostęp do roboczego pulpitu nawigacyjnego

Możesz użyć dashboard_id, aby pobrać szczegóły z wersji roboczej pulpitu nawigacyjnego. Poniższe przykładowe żądanie i odpowiedź zawierają szczegóły bieżącej wersji roboczego pulpitu nawigacyjnego w obszarze roboczym.

Pole etag śledzi najnowszą wersję pulpitu nawigacyjnego. Ta opcja umożliwia zweryfikowanie wersji przed wprowadzeniem dodatkowych aktualizacji.

GET /api/2.0/lakeview/dashboards/04aab30f99ea444490c10c85852f216c

Response:

{
  "dashboard_id": "04aab30f99ea444490c10c85852f216c",
  "display_name": "Monthly Traffic Report",
  "path": "/path/to/dir/Monthly Traffic Report.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "47bb1c472649e711",
  "etag": "80611980",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

Aktualizowanie pulpitu nawigacyjnego

Możesz użyć dashboard_id w poprzedniej odpowiedzi, aby zaktualizować nowy pulpit nawigacyjny AI/BI utworzony za pomocą tej operacji. W poniższym przykładzie przedstawiono przykładowe żądanie i odpowiedź. dashboard_id z poprzedniego przykładu jest dołączany jako parametr ścieżki.

display_name i warehouse_id zostały zmienione. Zaktualizowany pulpit nawigacyjny ma nową nazwę i przypisany magazyn domyślny, jak pokazano w odpowiedzi. Pole etag jest opcjonalne. Jeśli wersja określona w etag nie jest zgodna z bieżącą wersją, aktualizacja zostanie odrzucona.

PATCH /api/2.0/lakeview/dashboards/04aab30f99ea444490c10c85852f216c

Request body:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "c03a4f8a7162bc9f",
  "etag": "80611980"
}

Response:

{
  "dashboard_id": "04aab30f99ea444490c10c85852f216c",
  "display_name": "Monthly Traffic Report 2",
  "path": "/path/to/dir/Monthly Traffic Report 2.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "c03a4f8a7162bc9f",
  "etag": "80611981",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

Tworzenie pulpitu nawigacyjnego

Możesz użyć punktu końcowego Tworzenie pulpitu nawigacyjnego w interfejsie API usługi Lakeview, aby przenieść pulpit nawigacyjny między obszarami roboczymi. Poniższy przykład zawiera przykładową treść żądania i odpowiedź, która tworzy nowy pulpit nawigacyjny. Klucz serialized_dashboard z poprzedniego przykładu zawiera wszystkie niezbędne szczegóły dotyczące tworzenia zduplikowanego pulpitu nawigacyjnego wersji roboczej.

Przykład zawiera nową wartość warehouse_id odpowiadającą magazynowi w nowym obszarze roboczym. Zobacz POST /api/2.0/lakeview/dashboards.

POST /api/2.0/lakeview/dashboards

Request body:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "parent_path": "/path/to/dir"
}

Response:

{
  "dashboard_id": "1e23fd84b6ac7894e2b053907dca9b2f",
  "display_name": "Monthly Traffic Report 2",
  "path": "/path/to/dir/Monthly Traffic Report 2.lvdash.json",
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "5e2f98ab3476cfd0",
  "etag": "14350695",
  "serialized_dashboard": "{\"pages\":[{\"name\":\"b532570b\",\"displayName\":\"New Page\"}]}",
  "lifecycle_state": "ACTIVE",
  "parent_path": "/path/to/dir"
}

Jedyną wymaganą właściwością w treści żądania jest display_name. To narzędzie może kopiować zawartość pulpitu nawigacyjnego lub tworzyć nowe, puste pulpity nawigacyjne.

Opublikuj pulpit nawigacyjny

Możesz użyć punktu końcowego publikowania pulpitu nawigacyjnego , aby opublikować pulpit nawigacyjny, ustawić poświadczenia dla osób przeglądających i zastąpić te ustawienia na pulpicie nawigacyjnym wersji roboczej warehouse_id. Musisz dołączyć identyfikator UUID pulpitu nawigacyjnego jako parametr ścieżki.

Treść żądania ustawia właściwość embed_credentials na wartość false. Domyślnie embed_credentials jest ustawiona na wartość true. Osadzanie poświadczeń umożliwia użytkownikom na poziomie konta wyświetlanie danych pulpitu nawigacyjnego. Zobacz Publikowanie pulpitu nawigacyjnego. Pominięto nową wartość warehouse_id, więc opublikowany dashboard używa tego samego magazynu przypisanego do dashboardu projektu.

POST /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Request body:

{
  "embed_credentials": false
}

Response:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "embed_credentials": false,
  "revision_create_time": "2019-08-24T14:15:22Z"
}

Publikowanie pulpitu nawigacyjnego przy użyciu poświadczeń jednostki usługi

Pulpit nawigacyjny można opublikować przy użyciu poświadczeń jednostki usługi osadzonych, uwierzytelniając się jako jednostka usługi podczas wykonywania wywołania interfejsu API. Podczas publikowania przy użyciu tokenu należącego do jednostki usługi, pulpit nawigacyjny jest publikowany z danymi oraz uprawnieniami dotyczącymi przetwarzania tej jednostki usługi, pozwalając użytkownikom, którzy nie mają bezpośredniego dostępu do danych, na wyświetlanie pulpitu nawigacyjnego.

Przed opublikowaniem jednostka usługi musi mieć co najmniej uprawnienia CAN MANAGE na pulpicie nawigacyjnym, SELECT uprawnienia CAN MANAGE do wszystkich źródeł danych używanych na pulpicie nawigacyjnym i uprawnienia CAN USE w magazynie. Aby uzyskać szczegółowe informacje na temat tworzenia jednostek i generowania tajemnic protokołu OAuth, zobacz Jednostki i Autoryzowanie dostępu jednostki do Azure Databricks za pomocą protokołu OAuth.

Najpierw uwierzytelnij się jako główne konto usługi, aby uzyskać token dostępu.

POST https://<databricks-instance>/oidc/v1/token

Request body (form-urlencoded):

grant_type=client_credentials&scope=all-apis

Authorization header:

Basic <base64-encoded-client-id:client-secret>

Response:

{
  "access_token": "eyJraWQiOiJkYTA4ZTVjZ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Następnie użyj tokenu dostępu, aby opublikować pulpit nawigacyjny przy użyciu poświadczeń jednostki usługi:

POST /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Authorization header:

Bearer <service-principal-access-token>

Request body:

{
  "embed_credentials": true,
  "warehouse_id": "5e2f98ab3476cfd0"
}

Response:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "embed_credentials": true,
  "revision_create_time": "2019-08-24T14:15:22Z"
}

Kiedy embed_credentials ma wartość true, użytkownicy przeglądający pulpit nawigacyjny używają uprawnień jednostki usługi do uzyskiwania dostępu do danych i zasobów obliczeniowych. Użytkownicy potrzebują tylko uprawnień dostępu do samego obiektu pulpitu nawigacyjnego. Wszystkie zapytania w pulpicie nawigacyjnym są uruchamiane przy użyciu tożsamości podmiotu usługi, dlatego dzienniki inspekcji pokazują podmiot usługi jako wykonawcę zapytania.

Uzyskaj opublikowany pulpit nawigacyjny

Odpowiedź z GET /api/2.0/lakeview/dashboards/{dashboard_id}/opublikowana jest podobna do odpowiedzi podanej w poprzednim przykładzie. dashboard_id jest dołączany jako parametr ścieżki.

GET /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Response:

{
  "display_name": "Monthly Traffic Report 2",
  "warehouse_id": "5e2f98ab3476cfd0",
  "embed_credentials": false,
  "revision_create_time": "2019-08-24T14:15:22Z"
}

Cofnij publikację pulpitu nawigacyjnego

Wersja robocza pulpitu nawigacyjnego jest zachowywana podczas korzystania z interfejsu API Lakeview do wycofywania publikacji pulpitu nawigacyjnego. To żądanie usuwa opublikowaną wersję pulpitu nawigacyjnego.

W poniższym przykładzie użyto dashboard_id z poprzedniego przykładu. Pomyślne żądanie zwraca kod stanu 200. Brak treści odpowiedzi.

DELETE /api/2.0/lakeview/dashboards/1e23fd84b6ac7894e2b053907dca9b2f/published

Panel sterowania kosza

Użyj DELETE /api/2.0/lakeview/dashboards/{dashboard_id}, aby przenieść wersję roboczą pulpitu nawigacyjnego do kosza. Pulpit nawigacyjny można nadal odzyskać.