dv-overview

スキル：概要 — 何をいつ使うか

Dataverse の作業では、まずこのスキルを読み込んでください。すべてのタスクで必要となる横断的なコンテキスト、つまり対象範囲、ツールの機能リファレンス、厳守事項、変更ライフサイクルがまとめられています。このスキルはルーティングを行いません。エージェントは、各スキル独自の WHEN／DO NOT USE WHEN フロントマターのトリガーに基づいて、専門スキルを自動選択します。ユーザーは希望する内容を平易な英語で説明します。エージェントはスキルを自動的に連携させ、ユーザーにスキル名やコマンドを指定するよう求めることはありません。

---

このプラグインの対象

専門スキルを通じて、すべてのペルソナ（ビルダーやエージェント開発者、データサイエンティスト、環境管理者、ビジネスユーザー）向けに Dataverse／Power Platform の作業を行います。エージェントはフロントマターのトリガーに基づいて、これらのスキルを自動的に読み込んでルーティングします。スキル名を指定して呼び出す必要はありません。

領域	スキル
接続、認証、MCP の構成、環境の確認	dv-connect
スキーマ — テーブル、列、リレーションシップ、フォーム、ビュー。既存のスキーマの確認	dv-metadata
データ書き込み — レコードの CRUD、一括作成／更新／アップサート、CSV／外部キー順のインポート、サンプルデータ	dv-data
データの読み取りと分析 — OData クエリ、QueryBuilder、FetchXML（集計＋N:N 結合）、DataFrames	dv-query
ソリューション ALM — 作成、エクスポート、インポート、パック／アンパック、インポート後の検証	dv-solution
Finance and Operations X++ — 作成、ビルド、デプロイ、DB 同期、検証	erp-xpp
環境管理 — 一括削除、保持／アーカイブ、組織と OrgDB の設定、ごみ箱	dv-admin
セキュリティとアクセス — ロール、ユーザー、アプリケーションユーザー、ビジネスユニット、権限の自己昇格（PAC CLI）	dv-security

モデル駆動型アプリ： 構成要素（テーブル、フォーム、ビュー）は dv-metadata が対象です。アプリシェル自体（サイトマップとナビゲーション）の構成は、まだファーストクラスのスキルではありません。

対象外：

• キャンバスアプリ — 別のテクノロジーです。pac canvas またはメーカー ポータルを使用してください
• Power Automate フロー — メーカー ポータルまたは Power Automate Management API を使用してください
• サービスプリンシパルの設定に必要な範囲を超える Azure インフラストラクチャ
• Business Central またはその他の Dynamics 製品

---

厳守事項

安全に関するルール（初期化、認証、環境の確認）は必須です。ツールの選択（ルール 1、2、4）は機能に基づいて行います。

0. 最初に初期化状態を確認する

コードを記述したりファイルを作成したりする前に、呼び出し可能なツールを積極的に検索し、名前または説明に dataverse を含むツールがないか確認してください（ツールは、一般的な名前ではなく、mcp__dataverse_<orgid>__read_query のような環境固有の名前で登録されている場合があります）。Dataverse MCP ツールが見つかった場合は、それを直接使用し、初期化の確認とすべてのセットアップを省略してください。 MCP 認証はホスト側で管理されるため、.env や scripts/auth.py は不要です。最初に表示されたツール一覧だけを根拠に、MCP を利用できないと判断してはいけません。

MCP ツールが見つからない場合は、データ操作に最も早く使える既存の CLI プロファイルを確認してください。

dataverse auth who

アクティブなプロファイルと環境 URL が表示された場合は、データ操作に CLI を直接使用してください（dv-query／dv-data の例を参照）。.env、auth.py、ワークスペースのセットアップは不要です。「接続」または「セットアップ」の明示的な依頼の場合は、MCP、SDK、PAC を構成するため、いずれの場合も dv-connect を実行してください。

CLI プロファイルが存在しない場合は、ワークスペースの初期化状態を確認してください。

ls .env scripts/auth.py 2>/dev/null

• 両方存在する場合：タスクを進めます。
• どちらか一方でも欠けている場合：python <plugin-scripts>/auth.py --ping を実行します。REACHABLE が出力された場合（終了コード 0）、pip を使わずにワークスペースを起動できます。URL を確認してから作業を進めます。--ping が失敗した場合は、dv-connect を実行してください。

1. スクリプトには Python を使用し、CLI と MCP も第一級の選択肢として扱います

Python は自動化のロジック（変換、制御フロー、再試行、CSV）に使用する言語です。ツールチェーン（scripts/auth.py、SDK、スキルの例）は Python ベースです。一方、MCP ツール、Dataverse CLI（dataverse）、Python SDK、PAC CLI（pac）は、すべて第一級のツール呼び出しです。用途に合ったものを使用してください。Dataverse CLI は pac と同等の位置づけであり、ソリューションおよびメタデータのスキル全体で自由に使用されています。

絶対に行わないでください：

• 自動化のロジックを JavaScript／TypeScript／Node.js（npm、yarn、pnpm、package.json、node_modules/）で記述する
• @azure/msal-node、@azure/identity、または Node.js Azure SDK を使用する
• 独自の MSAL／デバイスコードフローを実装する — 認証には scripts/auth.py、pac auth、Dataverse CLI を使用します

必ず行ってください：

• データおよびスキーマのロジックには pip install と Python SDK（PowerPlatform-Dataverse-Client）を使用する
• トークン／認証情報には scripts/auth.py を使用し、Azure の認証情報フローには azure-identity（Python）を使用する
• Dataverse CLI（dataverse）と pac を使用可能なファーストパーティ CLI として扱う

2. 用途に合ったインターフェイスを選ぶ — 固定の順序ではなく、機能を理解して選択します

ツールの使用順序に決まりはありません。各インターフェイスにはそれぞれの機能があります。用途と、現在利用しているインターフェイスに合ったものを選んでください。これは推奨事項であり、必須の順序ではありません。すべての一覧は下記のツールの機能にあります。原則は次のとおりです。

• 生の OData を手作業で実装するより、マネージドインターフェイス（MCP、Dataverse CLI、SDK）を優先してください。これらは認証、ページング、再試行、地理的ルーティングを処理しますが、生の HTTP ではこれらを再実装する必要があります。MCP で対応できない場合（25 件を超える一括処理、大量の読み取り、フォーム／ビュー／N:N 関係／グローバル選択肢セット／代替キーなどの高度なスキーマ操作、複数ステップのワークフロー、分析、または MCP が利用できない場合）は、Python SDKをデフォルトとして使用してください。
• 生の Web API は、マネージドな手段がないインターフェイスに対する最後の手段です（PublishXml などのバインドされていないアクション、グローバル選択肢セット、第一級の SDK／CLI コマンドがないもの）。その場合でも、独自実装の urllib／get_token より dataverse api（認証をマネージドで処理し、終了コードを提供）を優先してください。フォーム／ビューは生の API だけで対応するものではありません（systemform／savedquery に対する SDK の records.create／update を使用できます。dataverse api が必要なのは PublishXml だけです）。集計／N:N 結合も生の API だけで対応するものではありません。client.query.fetchxml()（集計 + link-entity）、または N:N の書き込みには CLI の data associate を使用できます。
• SDK のメソッドが失敗した場合や、PAC コマンドが見当たらない場合は、生の HTTP を独自実装する前に、該当するスキルを確認してください。

フィールドの大文字・小文字： $select／$filter には、小文字の論理名（new_name）を使用します。$expand と @odata.bind には、大文字・小文字を区別し、$metadata と一致する必要がある Navigation Property Names を使用します（例：new_AccountId）。誤ると 400 エラーになります。SDK のレコードペイロード： @odata.bind キーには、正しい大文字・小文字の SchemaName を指定してください（例：[email protected]）。SDK は誤った大文字・小文字を自動修正しません。生の Web API 呼び出し（フォーム、ビュー、メタデータ）では、大文字・小文字の指定はすべて手動です。小文字の [email protected] は 400 エラーになります。

発行者のプレフィックス： プレフィックス（特に new）をハードコードしないでください。既存の発行者を照会し、ユーザーに確認してください。プレフィックスは永続的です。ソリューションスキルの発行者検出フローを参照してください。

3. 文書化された認証パターンを使用する

3 つのエントリーポイントで、サインインは共通です。

• dataverse auth create（Dataverse CLI）は、共有 MSAL トークンキャッシュを書き込みます。このサインインは、CLI、MCP プロキシ、および msal-extensions 経由の scripts/auth.py で使用されます。
• scripts/auth.py — Python／SDK の認証（サービスプリンシパル → 共有 CLI キャッシュ → デバイスコード）。SDK では get_client(skill) を優先してください。get_plugin_headers(skill, get_token()) は SDK に不足している機能を補う場合の代替手段です。どちらも帰属情報を付与します。
• pac auth create（PAC CLI）は、dv-solution、dv-admin、erp-xpp 用に pac を認証します。

**テレメトリの帰属情報（決定論的な状態を維持すること）：**すべてのリクエストには、クローズドスキーマの app=dataverse-skills/<ver>;skill=<skill>;agent=<agent> コンテキストが含まれるため、サーバーは各 OData 呼び出しをどのスキルがルーティングしたかを把握できます。これは組み込み済みです。get_client(skill) と get_plugin_headers(skill, ...) は SDK 経由と raw HTTP 経由の両方でこの情報を付与します。Dataverse CLI は DataverseCli/<ver> とコマンドを自動で付与するため、--context "app=dataverse-skills/<ver>;skill=<skill>;agent=<agent>" でスキルを追加してください（CLI が自動的に括弧で囲むため、事前に括弧を付けないでください）。このコンテキストを変更、省略、または自由形式で指定してはいけません。これはクローズドスキーマです（許可リストに登録されたスキル／エージェントのみ。PII は含めません）。

絶対にしてはいけないこと：

• トークンキャッシュファイル（例：tokencache_msalv3.dat）を直接読み取ったり解析したりすること。キャッシュの再利用は scripts/auth.py／msal-extensions 経由に限ります。
• 独自の MSAL デバイスコードフローを実装すること。
• スクリプトにトークンや認証情報をハードコードすること。
• 新しい認証方式を考案すること。

認証の有効期限が切れている、または認証情報がない場合は、dataverse auth create（または pac auth create）を再実行するか、.env を確認してください。dv-connect スキルを参照してください。

4. 不足している機能は正直に伝える — 幻覚しない

各スキルにはテスト済みの手順が記載されています。該当する場合はその手順に従ってください。サポート対象で非推奨ではない API の正確な情報は、各スキルが提供します。呼び出しが AttributeError で失敗する場合、インストール済みの SDK バージョンにはその機能がない可能性があります。スキルに記載されたバージョン情報を確認し、文書化された代替手段を使用してください。

**正直さの原則：**スキルでカバーされていない機能上の不足に直面した場合は、その旨を伝え、回避策を提案してください。サポートされていない方法を幻覚で補ってはいけません。文書化されていないメソッド、パラメーター、エンドポイントを作り出してはいけません。確信が持てない場合は、そのように伝えてください。

接続性と認証は別物です。login.microsoftonline.com のトークン取得に成功しても、組織のデータプレーンのドメインに接続できない場合があります（ChatGPT Work Mode のように、外部への接続が制限されたホストなど）。実際に応答を返した呼び出しで取得していない件数や結果を報告してはいけません。python scripts/auth.py --check で確認してください。失敗した場合は、架空の数値を示さず、「到達不能」と伝えてください。制約のあるホストでは、CLI／MCP ではなく SDK を優先してください。dv-connect/references/headless-hosts.md を参照してください。

---

ツールの機能 — 用途に応じたツールの選び方

各ツールの実際の制限を理解することで、幻覚による誤った方法を防げます。これは、個々のスキルだけではカバーできない唯一のコンテキストです。

ツール	用途	サポート対象外
MCP Server	データの CRUD（レコードの作成／読み取り／更新／削除、1 回の呼び出しにつき最大 25 件を一括処理）、テーブルの作成／更新／削除と列の追加（ローカル選択肢／複数選択肢および検索／顧客列を含む）、describe によるスキーマとレコードの調査、メタデータ検索（search）、データとファイル内容の検索（Dataverse 検索が有効な場合は search_data）、ファイルのアップロード／ダウンロード	フォーム、ビュー、グローバルオプションセット、N:N 関係、代替キー、ソリューション（検索列とローカル選択肢／複数選択肢列は create_table／update_table でサポートされています）。**注意：**テーブル作成はタイムアウトしても成功している場合があります。再試行する前に、必ず describe（例：describe('tables/{name}')）を実行してください。クエリは逐次実行してください（並列呼び出しはタイムアウトします）。スペースを含む列名はアンダースコアに正規化されます（例："Specialty Area" → cr9ac_specialty_area）。SQL（read_query）：JOIN、GROUP BY（COUNT/SUM/AVG/MIN/MAX）、TOP、WHERE、ORDER BY をサポートします。DISTINCT、HAVING、サブクエリ、OFFSET、UNION、CASE／IF、CAST／CONVERT、CTE、日付関数はサポートしません。これらには client.query.sql()（DISTINCT も使用可能、5K 行未満）、$apply、または pandas を使ったビルダーから DataFrame への変換を使用してください。dv-query を参照してください。**一括処理：**MCP の create_record／update_record／delete_record は 1 回の呼び出しにつき最大 25 件を一括処理します。それ以上の一括処理には SDK の CreateMultiple を使用してください。dv-data を参照してください。
Python SDK（dv-data）	スクリプトによるデータ書き込み、特に大量データの場合。レコード CRUD、アップサート（代替キー）、一括作成／更新／アップサート（CreateMultiple/UpdateMultiple/UpsertMultiple）、検索列の解決を伴う CSV インポート、ファイル列へのアップロード（128MB 超の場合はチャンク分割）	グローバルオプションセット、レコードの関連付け（$ref）、$apply による集計、テーブル／列／関係の作成（dv-metadata を使用）、カスタムアクションの呼び出し
Python SDK（dv-query）	一括読み取りと分析。複数ページにわたるレコードの反復処理、OData クエリ（select/filter/expand/orderby）、流暢な API の QueryBuilder、GUID を使わない表示（書式設定済みの値）、検索列の解決に使う $expand、client.query.fetchxml() による集計および N:N 結合（集計 FetchXML と link-entity）、エクスポート用の pandas DataFrame への引き渡し（client.query.builder(...).execute().to_dataframe()）、Jupyter ノートブックのスニペット	QueryBuilder の経路では OData の $apply と N:N の $expand は使用できません。N:N には records.list(expand=...) を、集計には fetchxml() を使用してください（生の urllib は使用しないでください）。
Dataverse CLI（dataverse）	ヘッドレスのデータプレーン：data CRUD、associate／disassociate（N:N と $ref）、data upload、api request／invoke（Web API の代替手段）、api list／describe（Custom API の検出）	メタデータ／スキーマ（SDK を使用してください。dv-metadata を参照）、ソリューション ALM（PAC を使用）、フォーム／ビュー。ChatGPT web／Codex cloud では利用不可（.NET ランタイムがありません）。SDK を使用してください。
PAC CLI	ソリューションのエクスポート／インポート／パック／アンパック、ERP X++ SDK のインストールとパッケージのひな形作成／コンパイル／デプロイ／DB 同期、環境の作成／一覧表示／削除／リセット、認証プロファイルの管理、プラグインの更新（pac plugin push。初回登録には Web API が必要）、ユーザー／ロールの割り当て（pac admin assign-user）、ソリューションコンポーネントの追加（pac solution add-solution-component）	データ CRUD、Dataverse メタデータの作成（テーブル／列／フォーム）、ソリューションコンポーネントの一覧表示（list-components はありません。SDK／CLI で solutioncomponent にクエリしてください）。X++ SDK のインストール／コンパイルには Windows が必要です。
Azure CLI	アプリ登録、サービスプリンシパル、資格情報の管理	Dataverse 固有の操作
GitHub CLI	リポジトリ管理、GitHub シークレット、Actions ワークフローのステータス	Dataverse 固有の操作
Raw Web API（最終手段）	管理されたインターフェースでは操作を実行できない場合に限ります。つまり、MCP、Python SDK、Dataverse CLI、dataverse api の代替手段のいずれでも実行できない場合です。該当する例は、PublishXml などのバインドされていないアクション、グローバルオプションセット、および同様の特殊ケースです（フォーム／ビューは該当しません。これらは systemform／savedquery に対する SDK のレコード CRUD で操作できます）。その場合でも、独自に urllib を実装するより、dataverse api（管理された認証とスキルの帰属情報を利用可能）を優先してください。	機能上の制限はありません（OData/MetadataService の全機能を利用できます）。ただし、生の urllib は管理された認証、ページング、再試行、スキルの帰属情報を迂回するため、最終手段として扱ってください。
ルーティング： 各サーフェスの役割は表に示されています。選び方の原則（固定順ではなく、あくまで推奨）はハードルール 2 です。リストにない MCP ツールが必要ですか？ dv-connect を読み込んでください。

ボリュームの目安： 単発のコマンドには CLI の dataverse data create/query/count を使用します。1 回の呼び出しで約 25 件までのレコードを扱う場合や、単純なフィルターには MCP を使用します。大量の一括書き込みには SDK の CreateMultiple を使用します（大規模なセットは約 1,000 件から分割してください。dv-data を参照）。一括読み取りには dv-query を、集計には SDK の fetchxml() を使用します。

SDK メソッドの早見表（幻覚防止用であり、優先度を示すものではありません）：SDK のメソッド名は最も見つけにくいため、エージェントが捏造しがちです。この表では、よくある操作を正確な呼び出しに対応付けています。ハードルール 2 に従い、どの操作も MCP／CLI で同じように実行できます。全体のパターンについては、記載のスキルを参照してください。

操作	SDK の呼び出し	スキル
レコードの作成／更新／削除	client.records.create() ／ .update() ／ .delete()（一括処理ではリストを渡します）	dv-data
代替キーによるアップサート	client.records.upsert()	dv-data
レコードのクエリ／フィルター	client.records.list(...)（フラット）または .list_pages(...)（ストリーミング）	dv-query
GUID による 1 件のレコード取得	client.records.retrieve(table, guid)（見つからない場合は None）	dv-query
集計／サーバー側結合	client.query.fetchxml(xml)（集計 + link-entity）	dv-query
Fluent クエリの構築（連結可能）	client.query.builder(Table).where(...).execute()	dv-query
制限付き SQL 読み取り	client.query.sql("SELECT ...")	dv-query
pandas への読み込み	client.query.builder(table).select(...).execute().to_dataframe()	dv-query
ファイル列へのアップロード	client.files.upload(...)	dv-data
テーブル／列／ルックアップ／N:N の作成	client.tables.create() ／ .add_columns() ／ .create_lookup_field() ／ .create_many_to_many_relationship()	dv-metadata
代替キーの作成（アップサートを有効化）	client.tables.create_alternate_key(...)	dv-metadata
既存スキーマの確認	client.tables.list_columns(table) ／ .list_table_relationships(table)	dv-metadata
パブリッシャー／ソリューションの作成	client.records.create("publisher" / "solution", {...})	dv-solution

MCP の利用可否の確認

ユーザーの依頼が明示的または暗黙的に MCP に関係する場合は、呼び出し可能なツールから、名前または説明に dataverse を含むツールを検索してください（ハードルール 0 と同じ検索です）。

MCP が利用できず、ユーザーが MCP を明示的に要求した場合（「MCP を使ってクエリして」など）：

1. Python SDK や Web API に黙って切り替えないでください
2. ユーザーに次のように伝えてください：「このセッションでは Dataverse MCP ツールがまだ設定されていません。」
3. MCP サーバーを設定するために dv-connect を読み込んでください
4. MCP の設定後は停止してください。MCP ツールを利用するにはセッションを再起動する必要があります。SDK で処理を続行しないでください。

MCP が利用できず、ユーザーがデータに関する質問をした場合（「アカウントはいくつありますか？」など）：

1. CLI（プロファイルがある場合）または SDK を使って回答してください。ユーザーの処理を止めないでください。
2. 回答後、次のように提案してください：「MCP を使うと対話形式で処理できます。設定しますか？」

この違いが重要です。MCP の明示的な要求なら処理を止めて MCP を設定し、暗黙的な質問なら SDK で回答して MCP の設定を提案します。

MCP ツールが利用できる場合は、単純な読み取り／クエリ／小規模な CRUD には MCP を優先してください。スクリプトが必要な場合に限り SDK を使用します。

---

変更のライフサイクル — 安全に操作する

実際に変更を加える場合は、次の 3 つの手順を順番に行ってください。まず場所を確認し、次にコンテナーを確認してから、結果を保存します。

Step 1 — 環境を確認する（必須）

Dataverse の作業では、複数の環境（dev、test、staging、prod）や複数の認証情報セットを扱うことがよくあります。現在の PAC 認証プロファイル、.env の値、または記憶や以前のセッションの情報が、現在のタスクに適した対象を示していると決して思い込まないでください。

特定の環境に影響する最初の操作を行う前に（テーブルの作成、プラグインのデプロイ、ソリューションのプッシュ、データの挿入など）、必ず次の手順を実行してください。

1. 使用する環境の URL をユーザーに提示する
2. 正しい URL であることをユーザーに確認する
3. pac org who を実行し、有効な接続先と一致することを確認する

「<URL> に変更を加えようとしています。この環境が正しい対象ですか？」

ユーザーが明示的に確認するまで、先へ進まないでください。 これはプラグインで最も重要な安全確認です。省略すると、誤った環境に取り消せない変更を加えるおそれがあります。同じセッション内で同じ環境を対象とする場合、一度確認すれば、その後の操作ごとに再確認する必要はありません。

Step 2 — ソリューションを確認する（メタデータを変更する前）

テーブル、列、その他のメタデータを作成する前に、作業を格納するソリューションが存在することを確認してください。

1. ユーザーに「これらのコンポーネントをどのソリューションに追加しますか？」と尋ねる
2. .env にソリューション名（SOLUTION_NAME）がある場合は、ユーザーに確認する
3. ソリューションがまだ存在しない場合は、dv-solution スキルを読み込み、発行元の特定とソリューション作成の手順に従う。SDK を使用し、発行元とソリューションのレコードの作成に生の Web API を決して使用しないでください。

# Quick reference — full pattern with publisher discovery is in dv-solution
publisher_id = client.records.create("publisher", {
    "uniquename": "<name>", "friendlyname": "<display>",
    "customizationprefix": "<prefix>", "description": "<desc>",
})
solution_id = client.records.create("solution", {
    "uniquename": "<Name>", "friendlyname": "<Display>",
    "version": "1.0.0.0",
    "[email protected]": f"/publishers({publisher_id})",
})

4. すべての SDK 呼び出しで solution="<UniqueName>" を渡すか、生の Web API でメタデータを呼び出す場合は "MSCRM.SolutionName": "<UniqueName>" ヘッダーを含める

ソリューションを指定せずにメタデータを作成すると、既定のソリューションにのみ存在し、適切にエクスポートまたはデプロイできません。必ずソリューションを先に用意してください。

Step 3 — リポジトリにプルする（必須）

メタデータを変更した場合（MCP、Web API、または maker portal 経由を問わず）、セッションの最後に必ず次をプルしてください。

pac solution export --name <SOLUTION_NAME> --path ./solutions/<SOLUTION_NAME>.zip --managed false
pac solution unpack --zipfile ./solutions/<SOLUTION_NAME>.zip --folder ./solutions/<SOLUTION_NAME>
rm ./solutions/<SOLUTION_NAME>.zip
git add ./solutions/<SOLUTION_NAME>
git commit -m "feat: <description>"
git push

リポジトリを常に信頼できる唯一の情報源としてください。

---

スクリプト

このプラグインには scripts/auth.py（Azure Identity によるトークン／認証情報の取得。ほかのすべてのスクリプトと SDK で使用）が含まれています。単発のクエリを超える Web API 呼び出しは、scripts/auth.py を使ってトークンを取得する Python スクリプトを /scripts/ に作成し、コミットしてください。書き込みについては dv-data、クエリと分析については dv-query、インポート後の検証については dv-solution を参照してください。

---

Windows でのスクリプト作成

プラットフォーム固有のシェルルール（.py 内での ASCII 使用、複数行の python -c の禁止、PAC PowerShell ラッパー、バッファーなしのバックグラウンド出力）は、references/windows-scripting.md に記載されています。Windows で実行する場合は、こちらを読んでください。