datalens-sdk

DataLens SDK

公式 Python SDK を使用して Yandex DataLens を操作します。手作業で HTTP リクエストを作成してはいけません。

続行する前に、名前または名前空間付きベース名が datalens である利用可能なスキルを見つけて読み込んでください。このスキルには、この SDK の手順と併せて適用される、共通のインストールおよびオブジェクトモデルに関する情報が記載されています。見つからない場合は、公開 DataLens スキルのインストールが不完全であることを報告して、停止してください。読み込んだ後、SDK のセットアップと実行を行うためにここへ戻ってください。

このスキルの手順は、インストール済みの datalens-sdk パッケージ内に保存されており、環境が対象とする DataLens のインストール内容によって拡張されます。 SDK は 0.x 系のアルファ版であり、マイナーリリースごとにクラスやメソッドの名前が変わるため、別途配布された手順では、ユーザーの環境にない API が説明されてしまいます。何かを行う前に、パッケージから手順を読み込んでください。

ユーザーが SDK とは何か、または自分のタスクに適しているかだけを尋ねている場合は、このファイルの情報だけで回答し、そこで停止してください。ドキュメントを読むだけのためにブートストラップを実行したり、パッケージをインストールしたりしないでください。

ブートストラップしてから手順を読み込む

セッションで最初の SDK 操作を行う前に、このラッパースキルのディレクトリを絶対パスに解決し、ユーザーのプロジェクトディレクトリからブートストラップスクリプトを実行してください。

bash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh"

このスクリプトは、./.venv を検討する前に uv または Poetry が管理するプロジェクトを解決します。これらのツールは、同じ名前の環境を所有していることが多いためです。管理対象外のプロジェクトの場合に限り、./.venv を作成します。選択されたすべての bin/python が、その環境に属していると自身を識別することを検証するため、古いシンボリックリンクによってシステム Python にインストールされることはありません。設定済みの Python パッケージインデックスに接続し、選択した環境に datalens-sdk をインストールする場合があります。

このスクリプトでは、SDK のバージョンや Python の互換性範囲を固定していません。通常の環境では、選択したインタープリターの pip 設定を通じて照会します。uv および Poetry のプロジェクトでは、それぞれのネイティブなプロジェクトソースを通じて解決します。候補の選択では、SDK のメタデータと PROJECT_REQUIRES_PYTHON、および存在する場合は数値形式の .python-version 固定値との共通範囲を考慮します。互換性と最新性の確認では、pip のアップグレードや SDK、その依存関係のインストールは行いません。候補が仮想環境を作成できる場合、新しいプロジェクトの確認では、その候補とまったく同じインタープリターを使って使い捨ての仮想環境を作成し、プローブにもその pip のソースポリシーを引き継ぎます。検証済みのプロジェクト環境は直接照会します。

---BOOTSTRAP--- マーカー以降の KEY=VALUE 行を解析してください。

• STATUS=ready — 以降のすべての Python 呼び出しには、PYTHON で指定された絶対パスのインタープリターを使用してください。
• STATUS=decision_required — パッケージスキルを読み込んだり SDK の作業を行ったりせずに、次の対応を行ってください。

  • REASON=sdk_install_required — uv または Poetry のプロジェクトで、マネージャー経由の datalens-sdk のインストールが必要です。依存関係がすでに宣言されていても、同期されていない環境には存在しない場合や、追加が必要な場合があります。また、インポート可能な SDK がマネージャーによる同期で削除または置換される場合も該当します。マネージャーはプロジェクトのソース、ロックファイル、Python の制約に基づいて正確なバージョンを選択することを説明してください。再調整により、現在インポート可能な SDK のバージョンがアップグレードまたはダウングレードされる場合があります。依存関係を追加する必要がある場合は、プロジェクトのマニフェストとロックファイルが変更されることがあります。また、uv は再調整の際に、古くなったロックファイルをマニフェストに合わせて更新する場合があります。Poetry のインストールでは、ロックされている他の不足した依存関係もインストールされることがありますが、追跡対象外のパッケージは削除されません。uv sync は厳密な同期を行うため、管理対象外のパッケージを削除することがあります。この同意を得る前に SDK_VERSION や AVAILABLE_SDK_VERSION が出力されることはありません。承認された場合は、以下の正確なコマンドを実行して、結果を再度解析してください。

    bash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh" --install-sdk
    

    管理対象プロジェクトでは、pip install に置き換えないでください。

  • REASON=sdk_update_available — インストール済みの SDK_VERSION と、互換性のある新しい AVAILABLE_SDK_VERSION をユーザーに伝え、クリック可能な CHANGELOG_URL を示し、インストール済みのバージョンを維持するかアップグレードするかを明確に尋ねます。ユーザーの言語に合わせてください。維持する場合は、報告された PYTHON で続行します。アップグレードする場合は、報告された利用可能なバージョンを指定して、以下の正確なコマンドを実行し、ブートストラップの結果を再度解析します。

    bash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh" \
      --upgrade-sdk "$AVAILABLE_SDK_VERSION"
    

    実行結果で別の利用可能なバージョンが報告された場合は、再度尋ねてください。あるバージョンへの同意は、別のバージョンへの同意ではありません。直接の pip コマンドに置き換えないでください。

  • REASON=sdk_upgrade_target_unavailable — 承認されたバージョンは、インデックスで提供される互換性のあるリリースではなくなっており、ブートストラップはダウングレードも推測も行いません。インストール済みのバージョンを維持するか、元の確認を後で再試行するかを尋ねてください。

  • REASON=sdk_version_check_failed と SDK=installed の場合 — インストール済みの SDK は動作しますが、最新かどうか、またはパッケージマネージャーが所有しているかどうかを確認できなかったと説明します。報告された SDK_VERSION で続行するか、元のブートストラップコマンドを再試行するかを尋ねてください。黙って続行したり、最新であると説明したりしないでください。この理由は SDK=missing には適用されません。

  • REASON=sdk_upgrade_failed と SDK=installed の場合 — アップグレードには失敗しましたが、報告された SDK_VERSION は引き続き使用可能だと説明します。このバージョンで続行するか停止するかを尋ねてください。ユーザーが求めた場合に限り、アップグレードコマンドを正確に再試行します。

• STATUS=blocked — REASON と、関連する非機密フィールドを伝えます。別のインストールコマンドを独自に考えて実行しないでください。AVAILABLE_PYTHON がある場合、既存の互換性のない ./.venv は保持されており、その対処方法をユーザーが決める必要があります。venv_invalid の場合、インタープリターのパスを自動的に使用したり修復したりしないでください。managed_environment_unavailable または managed_environment_invalid の場合、uv/Poetry プロジェクトを保持し、管理対象の環境を修復するか選択するようユーザーに求めてください。並行して .venv を作成してはいけません。managed_python_incompatible の場合、別の環境にインストールするのではなく、パッケージマネージャーが選択した Python を変更するようユーザーに求めてください。configured_python_unavailable の場合、CONFIGURED_PYTHON に指定された数値バージョンをインストールまたは変更するようユーザーに求めてください。configured_python_incompatible の場合、設定されたインタープリターが PROJECT_REQUIRES_PYTHON と REQUIRES_PYTHON の両方を満たしていないことを説明してください。project_python_constraint_invalid または project_metadata_unreadable の場合、pyproject.toml を修正するようユーザーに求めてください。sdk_install_failed の場合、管理対象環境は保持されたと伝え、再試行するか、ブートストラップのプロトコル外でパッケージマネージャーのエラーを調べるかを尋ねてください。

認識できない decision_required の理由がある場合は、推測せずに停止し、解析済みのフィールドを表示してください。判断はこのセッションにのみ適用されます。オプトアウトのマーカーを書き込まないでください。

マーカーまたは STATUS がない場合は、停止して生の出力を表示してください。プロセスの終了コードから成功を推測しないでください。特に、pip の一般的な「No matching distribution」というメッセージを、パッケージが存在しない証拠として扱わないでください。診断を改善するためだけにプロジェクトの pip をアップグレードせず、システム Python にインストールしないでください。

ブートストラップが ready を報告した場合、またはユーザーが decision_required の後に動作可能なインストール済みバージョンを明示的に選択した場合は、報告された正確な PYTHON を使って、以下を実行します。

"$PYTHON" -c "
import datalens_sdk
for p in datalens_sdk.agent_skill_paths():
    print(p)
"

各行に絶対パスを 1 つずつ出力します。最初に基本の手順が出力され、その後にこの環境で利用可能なインストールオーバーレイが出力されます。追加の行が出力されるのは正常です。これらは特定の DataLens インストール用の追加情報であり、すべてがこの環境に該当するとは限りません。 これらの絶対パスを維持してください。 各ディレクトリには、それぞれ独自のスクリプト、サンプル、references/ ツリーが含まれており、参照先はそのディレクトリからの相対パスで指定されています。また、絶対パスで呼び出されることを前提としています。ディレクトリ内に cd しないでください。ユーザーのプロジェクトディレクトリを常に作業ディレクトリとして使用してください。

今すぐ最初のパスにある SKILL.md を読み、ここに記載されているものとして従ってください。これは正式な指示であり、このファイルの内容を含め、この SDK についてあなたが把握していることより優先されます。インストール状況の確認方法も記載されています。残りのパスのうちどれが該当するかを判断し、いつ読むべきかを指示するため、それらの指示があるまではオーバーレイを読まないでください。オーバーレイの内容がベースの指示と矛盾する場合は、オーバーレイを優先してください。参照先はすべて読むのではなく、指示されたときに必要なものだけ読んでください。

読み終えるまでは、SDK コードの作成、インストール、SDK に関する質問への回答、アプローチの決定を行わないでください。この API についてもっともらしい推測をするより、コマンドを一つ多く実行するほうが適切です。

ファイルを書き込む場合は、ユーザーのプロジェクトディレクトリまたは一時ディレクトリに書き込んでください。パッケージのディレクトリは読み取り専用、または root の所有である可能性があります。

範囲

タスク	該当する場所
Python から DataLens エンティティを操作するすべての作業	ここ — 上記のパッケージの指示を読み込んでください
DataLens でレンダリングされる単独の HTML ページとレポート	datalens-html-pages
Python SDK を通じた HTML ページの公開または管理	ここ — パッケージの指示に記載された操作を使用してください。該当する操作がなければ、その旨を伝え、SDK のアップグレードまたは MCP/HTTP を提案してください。公開手順と最終リンクについては datalens-html-pages を読み込んでください
DataLens のウェブ UI、スクリーンショット、埋め込み、メトリクスの解釈	どちらにも該当しません — 範囲外であることを伝え、そこで終了してください