| name | dataverse |
| description | Dataverse テーブル設計・構築・デモデータ投入・セキュリティロール作成。ソリューション作成からテーブル・リレーション・ローカライズ・権限設定まで Python スクリプトで一括構築する。 |
| category | data |
| triggers | ["Dataverse テーブル作成","テーブル設計","スキーマ設計","Lookup","Choice","リレーション","デモデータ","ソリューション","パブリッシャー","プレフィックス","setup_dataverse","セキュリティロール","Security Role","権限設定","ロール作成","AddPrivilegesRole","ReplacePrivilegesRole","PrivilegeDepth","アクセス制御","RBAC","ロール権限","テーブル権限"] |
Dataverse テーブル設計・構築・セキュリティロールスキル
Dataverse のソリューション・テーブル・リレーション・ローカライズ・デモデータ・セキュリティロールを Python スクリプト で一括構築する。
サブリファレンス（必要に応じて参照）
このスキルの位置づけ: アーキテクチャ設計（architecture）で Dataverse 利用が確定した後、テーブル設計→構築を担当する。Code Apps / Generative Pages / Power Automate / Copilot Studio のいずれを使う場合でも、データ層はこのスキルで構築する。
前提
共通認証: 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(path) | dict | GET。パス文字列のみ（api_get("url", {"$filter": ...}) は 不可。クエリパラメータは URL に直接埋め込む） |
api_post(path, body, solution=) | str | None | POST。作成レコードの ID を返す。solution=SOLUTION_NAME でソリューションヘッダー付与 |
api_patch(path, body) | None | PATCH |
api_delete(path) | None | DELETE |
api_request(path, body, method="PUT") | None | PUT + MSCRM.MergeLabels: true ヘッダー自動付与。ローカライズ用 |
retry_metadata(fn, desc, max=5) | any | None | メタデータロック(0x80040237)・重複(already exists)検出リトライ。既存スキップ対応 |
get_token(scope=) | str | アクセストークン。省略時は {DATAVERSE_URL}/.default |
flow_api_call(method, path, body) | dict | Flow Management API 用。自動的に service.flow.microsoft.com スコープで認証 |
重要: 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")
all_tables = api_get("EntityDefinitions?$select=LogicalName,SchemaName,DisplayName")
existing_tables = [t for t in all_tables["value"] if t["LogicalName"].startswith(f"{PREFIX}_")]
衝突がある場合はユーザーに報告し、名前を変更してから設計を確定する。
Step 3: テーブル設計（ユーザー承認必須）
設計書を作成してユーザーに提示する。以下をすべて含める:
| 項目 | 内容 |
|---|
| 再利用テーブル一覧 | Step 1 スキャン結果から、再利用する標準/既存テーブルを明記 |
| テーブル一覧 | 新規のみ。マスタ → 主 → 従属の順に記載 |
| 列定義 | 英語スキーマ名、型、必須、Choice 値（100000000 始まり） |
| 全 Lookup リレーション | 漏れなく明記（既存テーブルへの Lookup・customer 型を含む） |
| ローカライズ計画 | テーブル名・列名・Choice オプションの日本語名 |
| デモデータ計画 | 全テーブルに対して（従属テーブル含む） |
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) を有効化済み。
テーブルが複数ある場合は並行作成（環境の混雑度に応じて並行数を調整）: 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 を先に済ませ、その後にローカライズする。
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 は常に付ける）。
必須要件
スキーマ設計
| ルール | 理由 |
|---|
| 設計前に環境スキャン（Step 1）を必ず実行 | 既存テーブルと重複作成して二重管理になる事故を防ぐ。scan_environment.py で棚卸し |
| ユーザー参照は systemuser ＋ システム列 | カスタムユーザーテーブルを作らない。ownerid/createdby/modifiedby を活用 |
| 顧客は account/contact を再利用 | 標準テーブルを使う。顧客 Lookup は customer 型（account/contact ポリモーフィック） |
| 製品は product/pricelevel/uom を再利用 | 製品マスタを新規作成しない |
| スキーマ名は英語のみ | 日本語スキーマ名は npx power-apps add-data-source で失敗する |
| ユーザー参照は SystemUser テーブル | カスタムユーザーテーブルを作らない |
作成者・報告者は createdby システム列を利用 | カスタム ReportedBy Lookup は不要 |
⚠️ Power Pages 例外: Power Pages では Web API 経由のレコード作成時に createdby がアプリケーションユーザー（サービスアカウント）になるため、createdby で報告者を追跡できない。Power Pages 向けテーブルでは Contact テーブルへの Lookup 列で報告者を追跡する設計が必須。詳細は power-pages スキルの教訓 19 を参照。
| Choice 値は 100000000 始まり | 0, 1, 2... はカスタム Choice では使用不可 |
| マスタテーブルは要件から網羅的に洗い出す | カテゴリ・場所・設備等、ユーザーが言及した分類はすべてマスタ化 |
| 全 Lookup リレーションシップを設計書に明記 | 漏れると Lookup が機能しない |
| デモデータは全テーブル（従属テーブル含む）に計画 | コメント等の従属テーブルにもデモデータを用意 |
| Instructions のテーブル名は単数形の論理名 | Power Apps MCP / Dataverse MCP は LogicalName でアクセス。複数形(EntitySetName)や表示名は不可 |
構築スクリプト
| ルール | 理由 |
|---|
retry_metadata() を使う | auth_helper.py 組み込みのリトライ。メタデータロック(0x80040237)・重複(already exists)を自動ハンドリング |
テーブル作成間に time.sleep(10)、列追加間に time.sleep(5) | メタデータロックの 予防策。retry_metadata はリアクティブ（発生後リトライ）だが、プロアクティブに待機する方が結果的に速い（リトライ回数が減る） |
| リレーション作成順: マスタ → 主 → 従属 → Lookup | 依存テーブルが存在しないとリレーション作成失敗 |
| 既存テーブルでもカラム欠落を補完 | テーブルは既存でも、前回失敗したカラムが欠けている場合がある。個別にカラム存在チェックして不足分を追加 |
api_post() に solution=SOLUTION_NAME を渡す | ソリューションヘッダー付与。テーブル・列・Lookup すべてに |
テーブル作成後に PublishAllXml | テーブルのメタデータを公開しないとローカライズが失敗する場合がある |
PublishAllXml は 429 レート制限に備える | 大量メタデータ操作後に 429 が頻発。時間を置いてスクリプト再実行で回復。べき等設計必須 |
ローカライズは api_request() で PUT | MSCRM.MergeLabels: true ヘッダーが自動付与される |
ローカライズ後に再度 PublishAllXml | ローカライズの反映に公開が必要 |
ソリューション含有は AddSolutionComponent で検証 | MSCRM.SolutionName ヘッダーだけに依存しない |
| EntitySetName は API で取得 | 複数形の推測は誤る場合がある（例: equipmentcategorys vs em_equipmentcategories） |
ソリューション表示名を .env に自動保存 | _save_env_value("SOLUTION_DISPLAY_NAME", name) で永続化。他スクリプトから参照可能 |
| メタデータロックで最大リトライ超過時は再実行 | retry_metadata() の max retries (5) を超えた列は、スクリプト再実行時に「既存。スキップ」で回復 |
| 失敗が多発する環境では並行数を下げる | 既存カスタムテーブルが多い環境では max_workers を 5→2〜3 に下げると失敗率が大幅に下がる（実測） |
| 429 レート制限は時間を置いて再実行 | PublishAllXml・EntityDefinitions PUT で 429 が頻発。べき等設計でスクリプト再実行で回復 |
Lookup と NavProp
| ルール | 理由 |
|---|
RelationshipDefinitions への POST で Lookup 作成 | 1:N リレーション（Lookup）は RelationshipDefinitions エンティティセットへ OneToManyRelationshipMetadata を POST する。CreateOneToMany バインドアクションは環境／Web API バージョンによって 404 Not Found になるため使わない |
| Lookup 作成前に属性存在チェック必須 | api_get("EntityDefinitions(LogicalName='{from}')/Attributes(LogicalName='{col}')") で存在確認。存在すればスキップ。retry_metadata の "already exists" 検出だけに頼らない |
LOOKUPS 形式: from_table, column_logical, display, to_table | シンプルな 4 キー構造。SchemaName は {from_table}_{column_logical} で自動生成 |
@odata.bind にはナビゲーションプロパティ名（NavProp名）を使う | 列の論理名ではない。大文字/小文字が区別される |
NavProp 名は ManyToOneRelationships で動的取得 | ReferencingEntityNavigationPropertyName を確認する |
| NavProp 名を推測しない | get_navprop(from_logical, to_logical) ヘルパーで取得 |
Lookup は NavProp@odata.bind で設定 | /{EntitySetName}({id}) の形式 |
| Lookup リレーション作成はべき等設計 | 属性存在チェック → 存在すればスキップ → 未存在なら RelationshipDefinitions へ POST → retry_metadata で二重保護 |
ローカライズ
| ルール | 理由 |
|---|
| テーブル表示名は PUT + MetadataId | PATCH では反映されないケースがある |
api_request() を使う | MSCRM.MergeLabels: true ヘッダーが自動付与される |
列の PUT には @odata.type が必要 | AttributeType に応じた OData 型を指定（Lookup → LookupAttributeMetadata 等） |
Choice オプションは UpdateOptionValue アクション | api_post("UpdateOptionValue", {...}) で各オプションの日本語ラベルを更新 |
テーブルアイコン
テーブルにカスタムアイコンを設定する場合は standard スキルの アイコン作成リファレンス を参照。
SVG WebResource 作成 → IconVectorName の PUT 設定パターンが記載されている。
デモデータ投入
| ルール | 理由 |
|---|
| NavProp 名を API から動的取得 | get_navprop() ヘルパーを使う |
| EntitySetName を API から動的取得 | get_entity_set_name() ヘルパーを使う |
| 既存データのべき等チェック | 主キー名で検索し、既存ならスキップ |
api_post() の戻り値は ID 文字列 | r.headers["OData-EntityId"] ではなく、直接 ID が返る |
テーブル設計テンプレート
## テーブル設計書
### テーブル一覧
| # | テーブル (論理名) | 種別 | 説明 |
|---|---|---|---|
| 1 | **{prefix}_mastera** | マスタ | ... |
| 2 | **{prefix}_mainentity** | 主テーブル | ... |
| 3 | **{prefix}_childentity** | 従属 | ... |
### 列定義: {prefix}_mainentity
| 列 (論理名) | 表示名 | 型 | 必須 | 備考 |
|---|---|---|---|---|
| {prefix}_name | Name / 名前 | String(200) | Yes | 主列 |
| {prefix}_status | Status / ステータス | Picklist | No | 100000000=New, 100000001=Active |
| {prefix}_masteraid | MasterA / マスタA | Lookup→mastera | No | |
### Lookup リレーション
| From (referencing) | → To (referenced) | lookup_attr | 表示名 |
|---|---|---|---|
| mainentity | mastera | {prefix}_masteraid | マスタA |
| mainentity | systemuser | {prefix}_assigneeid | 担当者 |
| childentity | mainentity | {prefix}_mainentityid | メイン |
### Choice 値
| フィールド | 値 |
|---|---|
| mainentity.status | 100000000=New, 100000001=Active, 100000002=Closed |
### ローカライズ
| 対象 | 日本語名 |
|---|---|
| mastera テーブル | マスタA / マスタA |
| mainentity テーブル | メインエンティティ / メインエンティティ一覧 |
| mainentity.name | 名前 |
| mainentity.status | ステータス |
| mainentity.status=100000000 | 新規 |
| mainentity.status=100000001 | アクティブ |
### デモデータ計画
| テーブル | 件数 | 概要 |
|---|---|---|
| MasterA | 5件 | ... |
| MainEntity | 10件 | 各ステータスを網羅 |
| ChildEntity | 8件 | 主要レコードにコメント |
スクリプト構成
同梱スクリプト
テンプレート（プロジェクト用にカスタマイズ）
setup_dataverse.py
カスタマイズ箇所:
TABLES — テーブル定義（論理名・列定義）LOOKUPS — リレーション定義LOCALIZE_TABLES / LOCALIZE_COLUMNS / LOCALIZE_OPTIONS — 日本語化定義create_demo_data() — デモデータ投入ロジック
実行ステップ:
- ソリューション確認/作成（べき等。表示名を .env に自動保存）
- テーブル作成（
retry_metadata + 既存カラム補完）
- Lookup リレーション作成
- カスタマイズ公開（
PublishAllXml）
- 日本語ローカライズ（
api_request PUT + MergeLabels + UpdateOptionValue）
- 再公開
- デモデータ投入（NavProp・EntitySetName 動的取得）
- ソリューション含有検証（
AddSolutionComponent）
- テーブル検証（EntitySetName で実クエリ）
Code Apps 案件では --skip-localize で 1〜4 のみ実行 → add-data-source → --localize-only で 5〜9 を実行する（詳細は Step 4）。
関連スキル
| スキル | 関係 |
|---|
standard | 共通認証（auth_helper.py）・.env パラメータ・retry_metadata |
architecture | アーキテクチャ判断後にこのスキルへ |
code-apps | テーブル構築後に Code Apps 開発 |
generative-page | テーブル構築後に Generative Page 開発 |
model-driven-app | テーブル構築後にモデル駆動型アプリ作成 |
security-role | テーブル構築後にセキュリティロール設定 |
