記事公開日
Dataverseテーブル名を示すプロパティの区別

こんにちは。システムソリューション営業本部の吾妻です。
Microsoft Learnに「Microsoft Dataverse のテーブル定義」という公式資料が掲載されており、Dataverseテーブルを作成した際に、システムによって自動的に生成される列の名前や格納される内容などについて記載があります。
しかしながら、日本語版の記事では、文章が過剰に日本語翻訳されてしまっている箇所があり、解説や例示を理解するのが難しい場合があります。
そこで今回は、この公式資料の内容と、実際にDataverse Web APIを呼び出した結果の双方に基づいて、「テーブル名」に関する各プロパティの定義を分かりやすく整理し、解説します。
テーブルを作成するときのUI
ユーザーがテーブル名を入力するのは、主にDataverseにテーブルを作成するときです。
今回は、GUIで設定するために、メーカーポータルから操作していきます。
最近は、Copilotによる「スキャフォールディング(自動生成)」に誘導するUIになっているので、作成したいテーブルの構成が固まっていない段階では、その流れに乗ってAIに生成させると便利です(現状では、Copilotに任せると若干上手くいかない操作があるようなので、ちょっとだけ手直しが必要になります)。
一方で、「こう作りたい」というイメージが固まっているのであれば、「テーブル(高度なプロパティ)」メニューから始めた方が手戻りを減らせて便利です。各項目の具体的な内容については次節でご紹介します。
テーブル名を定義する8つのプロパティ
表にまとめたので早速載せます。日本語を含むマルチバイト文字を利用できるのは、表示名、表示コレクション名、説明の3つの列のみです。他の列では、半角英数字で指定します。説明は、厳密にはテーブル名を格納する列ではありませんが、表示名だけでテーブルに格納されるエンティティの特徴を伝えきれない場合に、この列に補足情報を記述することを目的としているので、今回はまとめて載せておきます。
プロパティ | 例 | 内容 | ||
---|---|---|---|---|
日本語 | 英語 | 日本語環境 | 英語環境 | |
スキーマ名 | SchemaName | Account |
パスカルケースで記述する一意な名前 | |
コレクションスキーマ名 | CollectionSchemaName | Accounts |
スキーマ名を複数形にしたもの | |
論理名 | LogicalName (EntityName) |
account |
スキーマ名をすべて小文字にしたもの |
|
論理コレクション名 | LogicalCollectionName | accounts |
コレクションスキーマ名をすべて小文字にしたもの | |
エンティティセット名 | EntitySetName | accounts |
Web API でコレクションを区別するためのもので、既定では論理コレクション名と同じ |
|
表示名 | DisplayName | 取引先企業 | Account |
スキーマ名に加えて、スペースやマルチバイト文字を含めることができる |
表示コレクション名 | DisplayCollectionName | 取引先企業 | Accounts |
表示名を複数形にしたもので、メーカーポータル上だと「複数形の名前」 |
説明 | Description | 顧客または潜在顧客... |
Business that represents...
|
テーブルの目的などを記述する |
テーブル名をつけるときに気をつけるポイント
テーブル名を格納する列にどんなものがあるかをご説明したので、今度はそれらの列にどのような名前を格納するべきか、考えていきたいと思います。テーブルに「命名」するときに、気をつけた方が良いポイントを以下に挙げます。
①既存テーブルと表示名を重複させない
Power AppsメーカーポータルやPower Automateフローデザイナーなどでテーブルを選択する場合に、スキーマ名ではなく表示名を入力して検索し、リストから選択させるようなUIが数多くあります。カスタムテーブルを作成するときに、スキーマ名さえ重複していなければ、表示名に既存のテーブルと同一の文字列を指定することもできるのですが、そのようなUIで、同名のアイテムから目的のテーブルを選択するのに苦労するので、重複を避けるべきです。
Power Platform環境に既定で用意されるシステムテーブルの一覧をこちらに載せておきます。カスタムテーブル同士で同一の名前をつけることはほぼないと思うので、これらのシステムテーブルと表示名が被らないようにカスタムテーブルを命名するよう心がけると良いかと思います。
表示名が日本語で定義されているものとして、特に、カテゴリ、タグ、レポート、投稿、記事といったシステムテーブルは、ありがちなテーブル名の割には、ユーザー(SystemUser)テーブルや取引先担当者(Contact)テーブルほど利用頻度が高くないので存在を忘れやすく、名前を衝突させがちなので注意が必要です。
②単数/複数
日本語のように、言語の特性上、名詞の単数形と複数形の区別がない場合は、テーブルの名前を検討する際に、単数形か複数形かを意識することがありませんが、スキーマ名を英語で命名する際には、単数形・複数形を気にする必要があります。
表に掲載されているテーブル名のうち、まず論理名については、ユーザーが入力したスキーマ名をすべて小文字に置換することで生成されます(論理名とスキーマ名が異なる場合、論理名はスキーマ名で上書きされます)。この処理の時点では、単に小文字に変換するだけなので、複数形かどうかを気にする必要はありません。
次に、エンティティセット名などについては、自動的に「論理名を複数形に変換した文字列」が使用されます。Dataverseに限らずLaravelなどのWebフレームワークでも当てはまるのですが、不規則に変化する(語尾にsまたはesをつけるだけで複数形にならない)英単語や外来語など、この複数形への変換が上手くいかない場合がどうしても生じてしまうことがあります。そのため、テーブルを作成する際にユーザーが入力する「複数形の名前」と、スキーマ名から論理名を経由して自動生成されたエンティティセット名とで、スペルが異なってしまい、バグの温床となることがあります。エンティティセット名だけでなく、コレクションスキーマ名、論理コレクション名といった列も同様です。
例えば、「データ」テーブルを作成して、スキーマ名に「qes_Data」を指定した場合を考えてみます(実際には「データ」テーブルという具体性に欠けた命名はせず、格納されるデータの内容に合わせた名前をつけてください)。
Dataはもともと複数形なので、エンティティセット名の生成結果は「qes_data」になることが期待されます。しかし、次のJSONで示すテーブル定義のように、実際に生成される結果は、「pre_datas」となっています。これは、Dataverseが、多くの英単語に適用される「末尾にsを付ける」という単純なルールで複数形を自動生成しているためです。dataがdatumの複数形である(dataの時点で複数形である)ことまでは考慮されないため、このような意図しない結果が生じます。
{
"@odata.context": "https://org********.crm7.dynamics.com/api/data/v9.2/$metadata#EntityDefinitions/$entity",
"LogicalName": "qes_data",
"SchemaName": "qes_Data",
"LogicalCollectionName": "qes_datas",
"CollectionSchemaName": "qes_Datas",
"EntitySetName": "qes_datas",
"DisplayCollectionName": {
"LocalizedLabels": [{"Label": "データ", "LanguageCode": 1041}],
"UserLocalizedLabel": {"Label": "データ", "LanguageCode": 1041}
},
"DisplayName": {
"LocalizedLabels": [{"Label": "データ", "LanguageCode": 1041}],
"UserLocalizedLabel": {"Label": "データ", "LanguageCode": 1041}
}
}
|
このテーブルに対してDataverse Web APIでレコードを取得しようとする場合、エンティティセット名 (qes_datas) を用いて、以下のようなエンドポイントを呼び出す必要があります。もし、単数形の qes_data を指定してしまうと、エラーが発生します。このように、「s」一文字の有無がAPIの成否を分けるため、複数形を自動生成する際の仕様をユーザーが誤って認識していると(もしくは何も考えずに実装すると)、深刻なバグの温床になり得ます。
(誤) org********.crm7.dynamics.com/api/data/v9.2/cr20b_data?$top=10 (正) org********.crm7.dynamics.com/api/data/v9.2/cr20b_datas?$top=10 |
こうした問題を避けるためにも、data(datumの複数形)や people(personの複数形)のような、それ自体が複数形である単語や、不規則な複数形を持つ単語(例: mouse→mice)をスキーマ名に使用するのは、慎重に検討するべきです。
③一貫性を保つ
事前に、業務用語を定義した用語集や、命名規約を含めたコーディング標準を作成しておき、ソリューションに含まれるすべてのテーブルで共通のフォーマットで名前をつけるようにします。例えば以下のようなルールを定めておくことで、可読性やメンテナンス性を保つことができます。
・接頭辞/接尾辞 …テーブルの種類を明確にするために、マスタデータには M、トランザクションデータには Tのような接頭辞を追加します。
・略語の禁止 …Customer を Cust と略すなど、特定の文脈でしか通用しない略語は避け、誰が読んでも理解できる単語を使用します。
・英単語の採用 …ローマ字表記(例: Torihikisaki)は避け、対応する適切な英単語(例: Account, Client)を使用します。
例えば、顧客マスタを格納するテーブルであれば、
Cust(略語)やTorihikisakiMaster(ローマ字表記)
と命名するよりは、
M_Customer(接頭辞でマスタと分かる)、ClientMaster
と命名した方が、テーブルに格納されるデータの特徴を理解しやすくなります。
これら3つの事柄は、どちらかというとPower Platform特有の挙動に対するベストプラクティスなので、一般的なデータベース設計からの観点で注意すべきポイントについては、以下の記事も併せてご覧いただければと思います。
まとめ
本記事では、Dataverseのテーブル名を定義する複数のプロパティ(SchemaNameやDisplayNameなど)における技術的な違いと役割、またテーブル名の命名におけるベストプラクティスを解説しました。
Dataverseテーブルを「命名」したあとに、アプリを作成していくうえで参考にしていただけるような事例やサンプルも、本ブログでご紹介していますので、以下のリンクからご覧ください。
QES では Power Platform の開発支援、QAサポート、開発者教育、ガバナンス整備など、組織で Power Platform を活用するためのサポートを包括的にご提供しています。Power Platform 活用についてご興味がある/利用中だが課題を感じていらっしゃるお客様はまずはお気軽にお問い合わせください。
このブログで参照されている、Microsoft、Windows、その他のマイクロソフト製品およびサービスは、米国およびその他の国におけるマイクロソフトの商標または登録商標です。