チュートリアル: Databricks REST API を使用して Lakeview ダッシュボードを管理する

プレビュー

この機能はパブリックプレビュー段階です。

このチュートリアルでは、Lakeview API とワークスペース API を使用して Lakeview ダッシュボードを管理する方法を説明します。 各ステップには、サンプルのリクエストとレスポンス、および API ツールとプロパティを一緒に使用する方法についての説明が含まれています。 各ステップは単独で参照できます。 すべてのステップを順番にたどっていくことで、完全なワークフローが完了します。

注:

このワークフローは、ワークスペース API を呼び出して、Lakeview ダッシュボードを汎用ワークスペース オブジェクトとして取得します。 この Lakeview ダッシュボード プレビュー リリースでは、Lakeview 固有の API サポートが制限されています。

前提 条件

ステップ 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 ダッシュボード ファイルには、 Lakeviewダッシュボードのドラフト バージョンが反映されます。 次の例の応答は、最小限のダッシュボード定義の内容を示しています。 シリアル化の詳細を調べて理解するには、独自のダッシュボードをいくつかエクスポートしてみてください。

エクスポートしたファイルをダウンロードします

次の例は、API を使用して Lakeview ダッシュボード ファイルをダウンロードする方法を示しています。

この例の"path"プロパティは、ファイル タイプ拡張子lvdash.json (Lakeview ダッシュボード) で終わります。 ワークスペースに表示されるファイル名は、その拡張子の前に付けられます。 この場合は、 mydashboardです。

さらに、この要求の "direct_download" プロパティは true に設定されているため、応答はエクスポートされたファイル自体になります。

注:

応答のページ プロパティに表示される"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 ダッシュボードとして認識するには、2 つのパラメーターを設定する必要があります。

  • "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/ワークスペース/get-statusを参照してください。

次の例は、前の例からインポートされたダッシュボードに対する get-status 要求を示しています。 応答には、ファイルが "DASHBOARD"として正常にインポートされたことを確認する詳細が含まれます。 また、Lakeview API で識別子として使用できる"resource_id"プロパティで構成されます。

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 ダッシュボードを汎用ワークスペース オブジェクトとして操作できるようにしました。 次の例では、Lakeview API を使用して、Lakeview ダッシュボードに固有の公開操作を実行します。 POST /api/2.0/ Lakeview /dashboards/{dashboard_id}/published を参照してください。

API エンドポイントへのパスには、前の例で返された"resource_id"プロパティが含まれています。 リクエスト パラメーターでは、発行者の認証情報がダッシュボードに埋め込まれるように、 "embed_credentials"trueに設定されています。 この場合、発行者は、承認された API リクエストを行っているユーザーです。 発行元は、異なるユーザーの資格情報を埋め込むことはできません。

"warehouse_id"プロパティは、公開されたダッシュボードに使用されるウェアハウスを設定します。 指定した場合、このプロパティは、ドラフト ダッシュボードに指定されたウェアハウス (存在する場合) をオーバーライドします。 埋め込み資格情報の 設定がどのように機能するかについては、 「Lakeview ダッシュボードの公開」 を参照してください。


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 に置き換えます。このリンクは、Databricks ワークスペースのホームページにアクセスしているときにブラウザーのアドレス バーに表示されるアドレスです。

  • <resource_id> を、「メタデータの取得」で特定した "resource_id" プロパティの値に置き換えます。

ステップ 7: ダッシュボードを削除する

ダッシュボードを削除するには、ワークスペース API を使用します。 POST /api/2.0/ワークスペース/delete を参照してください。

重要

これは物理的な削除です。 コマンドが完了すると、ダッシュボードは完全に削除されます。

次の例では、リクエストには前のステップで作成したファイルへのパスが含まれています。

POST /api/2.0/workspace/delete

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

Response:
{}

次のステップ