geekfujiwara/codeappsdevelopmentstandard/dataverse

Dataverse テーブル設計・構築・セキュリティロールスキル

Dataverse のソリューション・テーブル・リレーション・ローカライズ・デモデータ・セキュリティロールを Python スクリプト で一括構築する。

Code Apps 向けに SharePoint URL を渡された場合も、直接接続・継続利用の明示がなければ Dataverse への移行を既定とする。URL は仕様・移行元の参照情報として扱う。 スキーマ・業務キー・Lookup を設計し、既存データは data-migration で承認付き投入・照合する。 通常開発では admin の網羅チェックを挟まず、既存テーブルの重複確認など本スキルの安全な構築手順を進める。 Code Apps の scaffold・初回 push は全テーブル構築・移行・ローカライズの完了を待たせない。

サブリファレンス（必要に応じて参照）

このスキルの位置づけ: アーキテクチャ設計（architecture）で Dataverse 利用が確定した後、テーブル設計→構築を担当する。Code Apps / Generative Pages / Power Automate / Copilot Studio のいずれを使う場合でも、データ層はこのスキルで構築する。

前提

事前確認（会話の最初に 1 回だけ）

本スキルの利用が確定したら、standard の共通契約に加え、 1 回の AskUserQuestion で次をまとめて確認する。

System Administrator を既定にせず、schema 変更は System Customizer または必要 privilege の カスタムロールを優先する。security role の変更・割り当ては、その工程の担当者を分離する。 実装先または publisher が未確定なら Step 0 へ進まない。

共通認証: auth_helper.py

認証ヘルパーは standard スキルに同梱（.github/skills/standard/scripts/auth_helper.py）。 各スキルの Python スクリプトは sys.path に ../../standard/scripts を追加して import するため、コピー不要。 2 層キャッシュ（AuthenticationRecord + MSAL OS 資格情報ストア）によりデバイスコード認証は初回のみ。

コピー元: .github/skills/standard/scripts/auth_helper.py

auth_helper.py 公開 API

重要: api_get() は dict を直接返す。.json() を呼ぶとエラー。

.env 共通パラメータ

DATAVERSE_URL=https://{org}.crm7.dynamics.com/
TENANT_ID={your-tenant-id}
SOLUTION_NAME={YourSolutionName}
PUBLISHER_PREFIX={prefix}
SOLUTION_DISPLAY_NAME={日本語表示名}   # ソリューション作成後に自動保存される

依存パッケージ

pip install azure-identity requests python-dotenv

作業フロー（必ずこの順序で進める）

Step 0: パブリッシャー・プレフィックス確認（ユーザー承認必須）

テーブル設計に入る前に、必ず既存パブリッシャーを環境から確認する。

from auth_helper import api_get
# 既存パブリッシャー一覧を取得
pubs = api_get("publishers?$filter=customizationprefix ne 'none'&$select=friendlyname,uniquename,customizationprefix&$orderby=friendlyname")
for p in pubs.get("value", []):
    print(f"  {p['customizationprefix']} — {p['friendlyname']} ({p['uniquename']})")

ユーザーに提示する内容:

• 既存パブリッシャー一覧（プレフィックス・名前）
• 推奨: 既存パブリッシャーを再利用するか、新規作成するか
• 新規の場合: プレフィックス命名案（2〜5文字の英小文字）

ユーザーの承認を得てから `.env` の `PUBLISHER_PREFIX` を確定し、環境スキャンに進む。

Step 1: 環境スキャン（既存資産の棚卸し — 設計前に必須）

新規テーブルを設計する前に、必ず既存環境を API でスキャンし、再利用できる資産を棚卸しする。 いきなり新規テーブルを作らず、標準テーブル・他ソリューションのカスタムテーブルを最大限再利用する。

# 標準テーブル（account/contact/product/systemuser 等）＋全カスタムテーブルを走査し、再利用レポートを出力
python -u .github/skills/dataverse/scripts/scan_environment.py --out spec/dataverse-scan.md
# 特定テーブルの列詳細も見たいとき
python -u .github/skills/dataverse/scripts/scan_environment.py --tables account,contact,product

レポートをもとにユーザーに提示し、再利用 vs 新規を合意する:

• ユーザー: カスタムユーザーテーブルを作らない。systemuser Lookup ＋ ownerid/createdby/modifiedby システム列を使う。
• 顧客: 標準 account（企業）/ contact（個人）を再利用。顧客参照は customer 型 Lookup（account/contact ポリモーフィック）。
• 製品: 標準 product / pricelevel / uom を再利用。製品マスタを新規作成しない。
• 既存カスタムテーブル: Field Service 等が作成済みのテーブルは再利用候補として検討。
• 新規作成: 既存に存在しない「要件固有の概念」だけに絞る。

詳細な再利用判断は Dataverse 統合ガイド — 標準テーブル再利用ガイド を参照。

Step 2: 名前衝突チェック（設計確定前に必ず実施）

# ソリューション名の重複チェック
existing_sol = api_get(f"solutions?$filter=uniquename eq '{SOLUTION_NAME}'&$select=solutionid,friendlyname")
# テーブルスキーマ名の重複チェック
# ⚠️ 環境によっては EntityDefinitions への $filter=startswith(...) が 501 Not Implemented になる。
#    $select のみで全件取得し、プレフィックス一致は Python 側でフィルタする（詳細は Dataverse 統合ガイド参照）。
all_tables = api_get("EntityDefinitions?$select=LogicalName,SchemaName,DisplayName")
existing_tables = [t for t in all_tables["value"] if t["LogicalName"].startswith(f"{PREFIX}_")]

衝突がある場合はユーザーに報告し、名前を変更してから設計を確定する。

プレフィックスを既存プロジェクトと共用する環境では {prefix}_project のような一般名が

高確率で衝突する。専用の名前空間（例: {prefix}_kbproject）を採用して回避する。

なお setup_dataverse.py は Step 1 の前に validate_no_foreign_tables() で

対象ソリューション外の既存テーブルとの衝突を必ず再検証し、検出したら API 呼び出し前に中断する。

Step 3: テーブル設計（ユーザー承認必須）

設計書を作成してユーザーに提示する。以下をすべて含める:

Code Apps 案件: スキーマ承認後すぐに Code Apps サブエージェントを起動する（並行実行）

architecture スキルで Code Apps が確定している場合、ユーザーがスキーマを承認したタイミングで

`code-apps` スキルをサブエージェントとして起動し、Dataverse 構築（Step 4）と並行して

Code Apps 開発（scaffold → deploy → add-data-source）を進める。

- このエージェント（dataverse）: Step 4 を --skip-localize で実行（テーブル構築のみ）

- サブエージェント（code-apps）: scaffold → pac code init → npm run deploy → pac code add-data-source（全テーブル）

- このエージェント（dataverse）: Code Apps 側の add-data-source 完了を待たずに --localize-only を実行して完了

Dataverse 構築が先に終わっても Code Apps サブエージェントは独立して継続する。

Step 4: 構築スクリプト実行

同梱の setup_dataverse.py をプロジェクト用にカスタマイズして実行する。

必ず `python -u`（unbuffered）で実行する: テーブル作成・Lookup 作成・ローカライズは

数分〜十数分かかるため、標準の出力バッファリング下では「止まって見える」ことがある。

-u を付けて Step ごとの進捗（=== Step 2: テーブル作成 === など）を確実にリアルタイム

表示させる。スクリプト側でも sys.stdout.reconfigure(line_buffering=True) を有効化済み。

**Windows PowerShell でログをファイルにリダイレクト/Tee-Objectする場合は、chcp 65001 に加えて

[Console]::OutputEncoding も明示的に UTF-8 へ設定する**: chcp 65001 は Windows の

コンソールコードページを切り替えるだけで、PowerShell（pwsh 7.x を含む）が子プロセスの出力を

解釈する [Console]::OutputEncoding（.NET プロパティ）には自動反映されないことがある。

chcp だけだと [Console]::OutputEncoding が cp932 のまま残り、スクリプト側が UTF-8 で

出力していても日本語部分が文字化けする（-Encoding UTF8 を付けて読み直しても直らない、

リダイレクト時点で既に破損しているため）。両方を実行前に設定することで確実に防げる。

```powershell

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

chcp 65001

python -u setup_dataverse.py 2>&1 | Tee-Object -FilePath setup_dataverse.log

```

`TABLES` 定義は API 呼び出し前に自動で事前検証される（validate_tables(), Step 0）:

Decimal/Integer の値域や String/Memo の maxLength が Dataverse の上限を超えていないかを

ローカルで静的チェックし、超過があれば構築を開始する前に分かりやすいエラーで停止する

（並行構築の途中で 400 エラーになり一部だけ作成された状態で止まる事故を防ぐ）。

テーブルが複数ある場合は並行作成（環境の混雑度に応じて並行数を調整）: setup_dataverse.py の

Step 2 では、TABLES に 2 つ以上のテーブルが定義されている場合、ThreadPoolExecutor

（デフォルト最大 3 並行）で全テーブルを並行作成する。

⚠️ Dataverse のメタデータロックはテナント全体で共有されるため、既存カスタムテーブルが

大量にある（100 件超）環境や、同一環境で他セッションが並行してメタデータ操作をしている環境では

並行数が高いほど競合が増える。実測では 10 テーブルを 5 並行で作成したところ 7 テーブルが

max retries (5) exceeded で失敗し、並行数を 2 に落として再実行したところ全て成功した。

失敗が多発する場合は create_tables() の ThreadPoolExecutor(max_workers=...) を 2 まで

下げて再実行する。スクリプトはべき等（成功済みテーブル・列は already exists, skipping

で自動スキップ）なので、同じコマンドを再実行するだけで失敗分だけがリトライされ、安全に復旧する。

Lookup（Step 3）は全テーブルと列が揃ってから作成するので、このスクリプトでの呼び出し順は

変わらない（create_tables() が全スレッドの完了を待ってから return する）。

Code Apps を使う場合はローカライズを2段階に分ける: pac code add-data-source は日本語

DisplayName だと Failed to sanitize string で失敗することがある。ローカライズ→英語に一時

戻す→再ローカライズという無駄な往復を避けるため、**構築時点ではローカライズせず英語のまま

add-data-source を先に済ませ、その後にローカライズする**。

```powershell

python -u setup_dataverse.py --skip-localize # テーブル構築のみ（英語のまま）

# ここで code-apps サブエージェント側の add-data-source を全テーブルに実行（build-reference.md Step 4）

python -u setup_dataverse.py --localize-only # ローカライズ・デモデータ投入

```

Code Apps を使わない（Generative Page / モデル駆動型アプリのみ等）場合は、従来どおり

フラグなしで一括実行して問題ない（python -u は常に付ける）。

必須要件

スキーマ設計

⚠️ Power Pages 例外: Power Pages では Web API 経由のレコード作成時に createdby がアプリケーションユーザー（サービスアカウント）になるため、createdby で報告者を追跡できない。Power Pages 向けテーブルでは Contact テーブルへの Lookup 列で報告者を追跡する設計が必須。詳細は power-pages スキルの教訓 19 を参照。

構築スクリプト

Lookup と NavProp