Kurz: Správa řídicích panelů pomocí rozhraní API pracovních prostorů

Článek
04/27/2024

Tento kurz ukazuje, jak spravovat řídicí panely pomocí rozhraní API Lakeview a rozhraní API pracovního prostoru. Každý krok obsahuje ukázkovou žádost a odpověď a vysvětlení, jak společně používat nástroje a vlastnosti rozhraní API. Na každý krok se dá odkazovat samostatně. Provedením všech kroků vás provede úplným pracovním postupem.

Poznámka:

Tento pracovní postup volá rozhraní API pracovního prostoru k načtení řídicího panelu Lakeview jako obecného objektu pracovního prostoru.

Požadavky

Pro připojení k pracovnímu prostoru potřebujete osobní přístupový token. Viz ověřování tokenů pat azure Databricks.
Potřebujete ID pracovního prostoru pracovního prostoru, ke které chcete získat přístup. Zobrazení názvů, adres URL a ID instancí pracovního prostoru
Znalost referenčních informací k rozhraní REST API služby Databricks

Krok 1: Prozkoumání adresáře pracovního prostoru

Rozhraní API seznamu pracovních prostorů GET /api/2.0/workspace/list umožňuje prozkoumat adresářovou strukturu pracovního prostoru. Můžete například načíst seznam všech souborů a adresářů v aktuálním pracovním prostoru.

V následujícím příkladu path vlastnost v požadavku odkazuje na složku uloženou examples_folder v domovské složce uživatele. Uživatelské jméno je zadané v cestě. first.last@example.com

Odpověď ukazuje, že složka obsahuje textový soubor, adresář a řídicí panel 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: Export řídicího panelu

Rozhraní API pro export pracovního prostoru GET /api/2.0/workspace/export umožňuje exportovat obsah řídicího panelu jako soubor. Soubory řídicího panelu Lakeview odrážejí koncept verze řídicího panelu. Odpověď v následujících příkladech ukazuje obsah minimální definice řídicího panelu. Pokud chcete prozkoumat a porozumět dalším podrobnostem serializace, zkuste exportovat některé z vašich vlastních řídicích panelů.

Stažení exportovaného souboru

Následující příklad ukazuje, jak stáhnout soubor řídicího panelu pomocí rozhraní API.

Vlastnost "path" v tomto příkladu končí příponou lvdash.jsontypu souboru , řídicím panelem Lakeview. Název souboru, který se zobrazí v pracovním prostoru, předchází ho. V tomto případě je to mydashboard.

Vlastnost pro tento požadavek je navíc nastavená tak, "direct_download" aby true odpověď byla exportovaným souborem.

Poznámka:

Vlastnost "displayName" zobrazená ve vlastnosti stránky odpovědi neodráží viditelný název řídicího panelu v pracovním prostoru.

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

Kódování exportovaného souboru

Následující kód ukazuje příklad odpovědi, kde "direct_download" je vlastnost nastavena na false. Odpověď obsahuje obsah jako řetězec kódovaný jako 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: Import řídicího panelu

K importu konceptů řídicích panelů do pracovního prostoru můžete použít rozhraní POST / api/2.0/workspace/import . Například po exportu zakódovaného souboru, jako v předchozím příkladu, můžete tento řídicí panel importovat do nového pracovního prostoru.

Aby se import rozpoznal jako řídicí panel Lakeview, musí být nastaveny dva parametry:

"format": "AUTO" – toto nastavení umožní systému automaticky rozpoznat typ prostředku.
- "path": musí obsahovat cestu k souboru, která končí na ".lvdash.json".

Důležité

Pokud se tato nastavení nenakonfigurují správně, import může být úspěšný, ale řídicí panel se bude považovat za běžný soubor.

Následující příklad ukazuje správně nakonfigurovaný požadavek na import.


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: Přepsání při importu (volitelné)

Při pokusu o opětovné vytvoření stejného požadavku rozhraní API dojde k následující chybě:

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

Pokud chcete místo toho přepsat duplicitní požadavek, nastavte "overwrite" vlastnost true jako v následujícím příkladu.


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: Načtení metadat

Můžete načíst metadata pro libovolný objekt pracovního prostoru, včetně řídicího panelu Lakeview. Viz GET /api/2.0/workspace/get-status.

Následující příklad ukazuje get-status požadavek na importovaný řídicí panel z předchozího příkladu. Odpověď obsahuje podrobnosti potvrzující, že soubor byl úspěšně importován jako "DASHBOARD". Skládá se také z "resource_id" vlastnosti, kterou můžete použít jako identifikátor s rozhraním 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: Publikování řídicího panelu

Předchozí příklady používaly rozhraní API pracovního prostoru a umožňovaly práci s řídicími panely Lakeview jako obecné objekty pracovního prostoru. Následující příklad používá rozhraní API Lakeview k provedení operace publikování specifické pro řídicí panely Lakeview. Viz POST /api/2.0/lakeview/dashboards/{dashboard_id}/published.

Cesta ke koncovému bodu rozhraní API zahrnuje "resource_id" vlastnost vrácenou v předchozím příkladu. V parametrech požadavku je nastavená taktrue, "embed_credentials" aby přihlašovací údaje vydavatele byly vloženy do řídicího panelu. Vydavatel v tomto případě je uživatel, který vytváří žádost autorizovaného rozhraní API. Vydavatel nemůže vložit přihlašovací údaje jiného uživatele. Informace o tom, jak funguje nastavení přihlašovacích údajů pro vložení, najdete v tématu Publikování řídicího panelu.

Vlastnost "warehouse_id" nastaví sklad, který se použije pro publikovaný řídicí panel. Pokud je zadána, tato vlastnost přepíše sklad zadaný pro řídicí panel konceptu, pokud existuje.

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

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

Response:
{}

Po dokončení příkazu se k publikovanému řídicímu panelu dostanete z prohlížeče. Následující příklad ukazuje, jak vytvořit odkaz na publikovaný řídicí panel.

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

Vytvoření jedinečného odkazu:

Nahraďte <deployment-url> adresou URL nasazení. Tento odkaz je adresa na adresní řádku prohlížeče, když jste na domovské stránce pracovního prostoru Azure Databricks.
Nahraďte <resource_id> hodnotou "resource_id" vlastnosti, kterou jste identifikovali v načtených metadatech.

Krok 7: Odstranění řídicího panelu

Pokud chcete odstranit řídicí panel, použijte rozhraní API pracovního prostoru. Viz POST /api/2.0/workspace/delete.