ワークスペース APIs でダッシュボードを管理する
このチュートリアルでは、 Lakeview API とワークスペース APIを使用してダッシュボードを管理する方法を示します。 各ステップには、サンプルの要求と応答、および API ツールとプロパティを一緒に使用する方法の説明が含まれています。 各ステップは、単独で参照できます。 すべてのステップを順番に実行すると、完全なワークフローがガイドされます。
注:
このワークフローは、ワークスペース API を呼び出して、 AI/BI ダッシュボードを汎用ワークスペース オブジェクトとして取得します。 AI/BI ダッシュボードは、以前は Lakeview ダッシュボードと呼ばれていました。 Lakeview API は、その名前を引き続き保持します。
前提条件
ワークスペースに接続するには、個人アクセストークンが必要です。 「Databricksパーソナルアクセストークン認証」を参照してください。
アクセスするワークスペースのワークスペース ID が必要です。 ワークスペースインスタンス名、URL、IDを参照してください
Databricks REST API リファレンスに精通していること。
ステップ 1: ワークスペース ディレクトリを探索する
ワークスペースリストAPI GET /api/2.0/workspace/list ワークスペースのディレクトリ構造を調べることができます。 たとえば、現在のワークスペース内のすべてのファイルとディレクトリのリストを取得できます。
次の例では、リクエストの path
プロパティは、ユーザーのホームフォルダーに格納されている examples_folder
という名前のフォルダーを指しています。 ユーザー名はパス first.last@example.com
で指定されます。
応答は、フォルダーにテキスト ファイル、ディレクトリ、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"
}
]
}
ステップ 2: ダッシュボードをエクスポートする
ワークスペース Export API GET /api/2.0/workspace/export ダッシュボードの内容をファイルとしてエクスポートできます。 AI/BI dashboards ファイルには、ダッシュボードのドラフト バージョンが反映されます。 次の例の応答は、最小限のダッシュボード定義の内容を示しています。 シリアル化の詳細を調べて理解するには、独自のダッシュボードの一部をエクスポートしてみてください。
エクスポートしたファイルをダウンロードする
次の例は、API を使用してダッシュボード ファイルをダウンロードする方法を示しています。
この例の "path"
プロパティは、AI/BI ダッシュボードのファイルタイプ拡張子 lvdash.json
で終わります。 ワークスペースに表示されるファイル名は、その拡張子の前にあります。 この場合は、 mydashboard
です。
さらに、この要求の "direct_download"
プロパティは true
に設定されているため、応答はエクスポートされたファイル自体であり、 "format"
プロパティは "AUTO"
に設定されます。
注:
応答の pages プロパティに示されている "displayName"
プロパティは、ワークスペースに表示されるダッシュボードの名前を反映していません。
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"
}
]
}
エクスポートされたファイルをエンコードする
次のコードは、 "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: ダッシュボードをインポートする
ワークスペース インポートAPIPOST /api/2.0/workspace/importを使用して、ドラフト ダッシュボードをワークスペースにインポートできます。 たとえば、前の例のようにエンコードされたファイルをエクスポートした後、そのダッシュボードを新しいワークスペースにインポートできます。
インポートを AI/BI ダッシュボードとして認識するには、次の 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: メタデータを取得する
AI/BI ダッシュボードを含む任意のワークスペース オブジェクトのメタデータを取得できます。 「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を使用して、 AI/BI ダッシュボードを汎用ワークスペース オブジェクトとして操作できるようにしました。 次の例では、Lakeview API を使用して、AI/BI ダッシュボードに固有の公開操作を実行します。 POST /api/2.0/Lakeview/dashboards/{dashboard_id}/published を参照してください。
API エンドポイントへのパスには、前の例で返された "resource_id"
プロパティが含まれます。 request パラメーターでは、 "embed_credentials"
が true
に設定されているため、発行元の資格情報がダッシュボードに埋め込まれます。 この場合、発行元は、承認された API 要求を行っているユーザーです。 パブリッシャーは、異なるユーザーの認証情報を埋め込むことはできません。 「 ダッシュボードの公開 」を参照して、資格情報の 埋め込み 設定のしくみを確認してください。
"warehouse_id"
プロパティは、公開されたダッシュボードに使用するウェアハウスを設定します。指定した場合、このプロパティは、ドラフトダッシュボードに指定されたウェアハウス (存在する場合) を上書きします。
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:
{}
次のステップ
ダッシュボードの詳細については、「 ダッシュボード」を参照してください。
REST API の詳細については、「 Databricks REST API リファレンス」を参照してください。