CatalogとCatalogAssignment テーブルを使用して、ソリューションで使用されるアクションをビジネス イベントとして公開する構造を作成します。 Microsoft Dataverse ビジネス イベントにより、多くのシナリオで Dataverse 経由で他のアプリケーションとの統合を作成できます。 詳細: Microsoft Dataverse ビジネス イベント
カタログには、ご利用のソリューションに関連するイベントが記載されているため、人々がそれらのイベントを利用できるようになります。 ソリューションに関連するイベントをカタログ化しない場合、ソリューションを使用しているユーザーがそれらを利用できない場合があります。
Catalog テーブルを使って、2 レベルの階層を作成します。 これにより、カタログとカテゴリーのグループが作成されます。ここで、第2階層のカタログはカテゴリーを表します。
第一階層のカタログは、ご利用のソリューションを表すものでなければなりません。 第一階層のカタログに関連する複数の第二階層のカタログを使用して、ソリューション内の機能の異なるカテゴリをグループ化します。
ソリューション内のカテゴリを表す第 2 レベルのカタログごとに、CatalogAssignment テーブルを使って、イベントとして使用できるテーブル、カスタム API、またはカスタム プロセス アクションを指定します。
重要
環境メーカー セキュリティ ロールを持つユーザーは、Power Automate Dataverse コネクタの アクションの実行時 トリガーでカタログ データを表示できます。 他のセキュリティ ロールには、次のテーブルに対する適切なアクセス レベルの読み取り権限が必要です: カスタム API、プロセス、SDK メッセージ。
詳細:
例: Contoso の顧客管理
カタログのアイデアを紹介するために、まずは例を挙げてみます。
Contoso の顧客管理ソリューションには、多くのコンポーネントが含まれています。 ここで関係するコンポーネントは次のとおりです。
- 表
- カスタム API
- カスタム プロセス アクション (ワークフロー)
表
Contoso の顧客管理は、次のテーブルを含むソリューションです。
| スキーマ名 | 表示名 | 説明 |
|---|---|---|
Account |
アカウント | Dataverse システム テーブル |
Contact |
連絡先 | Dataverse システム テーブル |
contoso_Membership |
メンバーシップ | カスタム組織所有のテーブル |
カスタム API
また、カスタム API アクションをいくつか作成し、POS システム、Web サイト、ERP システムなどから呼び出して、Dataverse 外で発生したイベントを Dataverse に通知しています:
| UniqueName | 表示名 |
|---|---|
contoso_CustomerEnteredStore |
入店 |
contoso_CustomerVisitWebSite |
Web サイトを開く |
contoso_CustomerPurchasedProduct |
購入した製品 |
contoso_CustomerReturnedProduct |
返品された製品 |
カタログの構造
Contoso の顧客管理ソリューション カタログは次のようになります。
| カタログ | 説明 |
|---|---|
| Contoso の顧客管理 | ルートカタログ |
| 表 | 第 2 階層のカタログ カテゴリ |
| アカウント | CatalogAssignment: エンティティ |
| 連絡先 | CatalogAssignment: エンティティ |
| メンバーシップ | CatalogAssignment: エンティティ |
| 顧客イベント | 第 2 階層のカタログ カテゴリ |
| 入店 | カタログ割り当て: カスタムAPI |
| Web サイトを開く | カタログ割り当て: カスタムAPI |
| 製品の購入 | カタログ割り当て: カスタムAPI |
| 製品の返品 | カタログ割り当て: カスタムAPI |
利用可能なイベント
CatalogAssignment バインドをテーブルに対して作成すると、そのテーブルの一部のシステム バインド操作がイベントとして使用可能になります。
このカタログでは、次のイベントが利用可能になります :
| テーブル | イベント | 利用できる理由 |
|---|---|---|
| アカウント | 作成 更新 削除 |
標準データ操作 |
| アカウント | GrantAccess ModifyAccess RevokeAccess |
ユーザー所有のエンティティは共有できます。 |
| 連絡先 | 作成 更新 削除 |
標準データ操作 |
| 連絡先 | GrantAccess ModifyAccess RevokeAccess |
ユーザー所有のエンティティは共有できます。 |
| メンバーシップ | 作成 更新 削除 |
標準データ操作 |
| N/A | contoso_CustomerEnteredStore |
カタログの明示的な割り当て |
| N/A | contoso_CustomerVisitWebSite |
カタログの明示的な割り当て |
| N/A | contoso_CustomerPurchasedProduct |
カタログの明示的な割り当て |
| N/A | contoso_CustomerReturnedProduct |
カタログの明示的な割り当て |
ほとんどのテーブルでは、作成、更新、削除イベントに対応しています。 いくつかの例外があります。 ユーザー所有のテーブルは、共有の変更に関するイベントを公開します: GrantAccess、ModifyAccess、および RevokeAccess
注
テーブルにバインドされているカスタム API またはカスタム プロセス アクションも含まれます。
無効になっているカスタム プロセス アクションが表示されますが、有効にして使用するまでイベントは発生しません。
Power Apps でのカタログの作成
Power Apps (https://make.powerapps.com) でカタログ レコードとカタログ割り当て レコードを作成できます。
ソリューションの一部として、常にカタログを作成する必要があります。 次の手順を使用して、カタログ レコードを作成します。
Power Apps にサインイン
左側のナビゲーション ペインで、ソリューション を選択します。
使用するソリューションを作成または選択して、新規をクリックします。
メニューからカタログを選択すると、新しいウィンドウが開きます。
以下のフィールドに入力します:
フィールド 説明 親項目のカタログ ソリューション ルートカタログに親カタログを設定しないでください。 それ以外の場合は、ソリューション ルート カタログを設定します。 一意の名前 一意の名前にはカスタマイズ接頭辞が必要であり、スペースを含めることはできません。 この接頭辞は、ソリューション発行者のカスタマイズ接頭辞と同じである必要があります。 名前 カタログの名前を入力してください。 通常は一意の名前と同じですが、カスタマイズ接頭辞を使わず、スペースを含みます。 表示名 通常は、名前と同じです。 説明 カタログの説明をわかりやすく入力します。 フォームを保存して閉じます。
Power Apps でカタログ割り当てを作成
Power Apps のカタログを含む同じソリューションを使用する
新規をクリックします。
メニューからカタログの割り当てを選択すると、新しいウィンドウが開きます。
名前を入力してください。 この値は、カスタマイズ接頭辞から始まり、スペースを含まない必要があります。 ソリューション発行者に対して定義されたのと同じカスタマイズ接頭辞を使用する必要があります。
カタログ割り当てオブジェクトを設定します。 このルックアップにより、3 つの異なるタイプのレコードを設定できます。
- カスタム API 群
- エンティティ
- プロセス
名前を入力することで、探しているタイプを見つけることができます。
カタログを選択
注
選択するカタログは、カテゴリを表す第 2 レベルのカタログである必要があります。
フォームを保存して閉じます
管理ソリューションのカタログ アイテムのカスタマイズをブロックする
管理ソリューションをインストールするユーザーがカタログとカタログの割り当てをカスタマイズできるようにする場合を除いて、IsCustomizable プロパティを false に設定する必要があります。なぜなら、既定値を使うとカスタマイズできるためです。
これを Power Apps UI で設定するには:
ソリューション内の各カタログまたはカタログ割り当てを選択します
メニューで、省略記号ボタン (...) をクリックし、管理プロパティを選択します。
開いたウィンドウで、カスタマイズを許可するの選択を解除します。
完了をクリックします。
テーブル ダイアグラム
次の図は、Catalog テーブルと CatalogAssignment テーブル間の関連付けを示しています
ParentCatalogId を使用した自己参照関係により、1つのソリューション カタログと、カタログ レコードを使ってカテゴリーを表現した複数のカタログの間に 2 段階の階層を作成できます。
カタログ テーブルの列
利用可能なすべての列と関連付けは、Catalog テーブル/エンティティの参照 で利用できます。
次の表には、設定可能なカタログ テーブル/エンティティの列/属性のうち、選択されたものが含まれています。
表示名SchemaNameLogicalName |
タイプ | 説明 |
|---|---|---|
カタログCatalogIdcatalogid |
Uniqueidentifier | カタログ インスタンスの一意識別子です。 |
説明Descriptiondescription |
String | カタログ インスタンスのローカライズされた説明です。 必須 |
表示名DisplayNamedisplayname |
String | カタログ インスタンスのローカライズされた表示名です。 必須 |
カスタマイズ可能IsCustomizableiscustomizable |
ManagedProperty | カタログのカスタマイズや削除を行うかどうかを制御します。 既定値は true です。 詳細: 管理ソリューションのカタログ アイテムのカスタマイズをブロックする 必須 |
名前Namename |
String | カタログの主要な名前です。 必須 |
親 CatalogParentCatalogIdparentcatalogid |
検索 | 親カタログの一意の識別子。 保存後に変更できません。 |
一意の名称UniqueNameuniquename |
String | カタログを表す一意の名前です。 必須 カスタマイズ接頭辞で始める必要があります。 |
注
カタログの割り当てをカタログに関連付けると、カタログ割り当てを削除するまでそのカタログを削除できなくなります。
CatalogAssignment テーブルの列
利用可能なすべての列と関連付けは、CatalogAssignment テーブル/エンティティ参照 で利用できます。
次の表には、設定可能な CatalogAssignment テーブル/エンティティの選択された列/属性が含まれています。
表示名SchemaNameLogicalName |
タイプ | 説明 |
|---|---|---|
カタログ割り当てCatalogAssignmentIdcatalogassignmentid |
Uniqueidentifier | カタログ割り当てインスタンスを表す一意識別子です。 |
カタログCatalogIdcatalogid |
検索 | カタログ割り当てに関連付けられたカタログを表す一意識別子です。 必須 |
カスタマイズ可能IsCustomizableiscustomizable |
ManagedProperty | CatalogAssignment をカスタマイズまたは削除できるかどうかを制御します。 既定値は true です。 詳細: 管理ソリューションのカタログ アイテムのカスタマイズをブロックする 必須 |
名前Namename |
String | カタログ割り当ての主要名。 |
カタログ割り当てオブジェクトObjectobject |
検索 | カタログ割り当てに関連付けられたオブジェクトを表す一意識別子です。 必須 保存後に変更できません。 このポリモーフィック ルックアップは、次のテーブルにリンクできます: customapi エンティティ ワークフロー Web API を使用してこのポリモーフィックな関係を関連付ける場合は、各関係に単一値のナビゲーション プロパティ名を使用する必要があります。 これらの名前は次のとおりです。 CustomAPIIdEntityIdWorkflowIdテーブル、カスタム API、カスタム プロセスアクションに関連付ける場合は、それぞれの ID 値を取得する必要があります。 詳細については CatalogAssignment の項目の ID を取得するを参照してください。 |
CatalogAssignment 項目の ID を取得します
CatalogAssignment に関連付ける場合は、エンティティの ID、カスタム API、カスタム プロセス アクションを取得する必要があります。
テーブルの ID を取得する
エンティティ テーブルには、各テーブルにつき1行が含まれています。 Web API を使ったこれらのクエリのいずれかを使って、Account テーブルなど特定のテーブルの ID を取得できます :
GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')?$select=MetadataId
GET [Organization URI]/api/data/v9.2/entities?$select=entityid&$filter=name eq 'Account'
カスタム API の ID を取得する
これは、Web API を使って簡単に行うことができます。 次の例では、uniquename が your_CustomAPIName であるカスタム API の customapiid を返します。
GET [Organization URI]/api/data/v9.2/customapis?$select=customapiid&$filter=uniquename eq 'your_CustomAPIName'
カスタム プロセス アクションの ID を取得する
これは、Web API を使って簡単に行うことができます。 次の例では、uniquename が ExampleCustomProcessAction であるカスタム プロセス アクションの workflowid を返します。
GET [Organization URI]/api/data/v9.2/workflows?$select=workflowid,uniquename&$filter=category eq 3 and type eq 1 and endswith(uniquename,'ExampleCustomProcessAction')
注
ワークフローの uniquename の名前には、Web API のカスタム プロセス アクションの名前の前に付加されるカスタマイズ用の接頭辞が含まれません。 Web API から呼び出すアクションが new_ExampleCustomProcessAction と命名されている場合、ワークフローの一意の名前は ExampleCustomProcessAction となります。
タイプが 1 の行にアクセスするようにしてください。 これはワークフローの定義です。
カスタム プロセスのアクション ワークフローは、カテゴリーの値が 3 です。
既存のカタログ割り当てを取得する
次の OData クエリを使用して、カタログ割り当て、割り当てのタイプ、関連付けられているカタログ、および親カタログに関する情報を取得できます。
GET [Organization URI]/api/data/v9.2/catalogassignments?$select=name
&$expand=CatalogId($select=uniquename;$expand=ParentCatalogId($select=uniquename)),
EntityId($select=entityid),
CustomAPIId($select=uniquename),
WorkflowId($select=uniquename)
&$filter=name ne null
コードでカタログと CatalogAssignments を作成する
カタログとカタログ割り当てレコードは、Web API または .NET 用 SDK を使って作成できます。
Web API の使用
注
現時点では、「deep-insert」 を使用してカタログやカタログ割り当てレコードを作成することはできません。
'deep-insert' を使用してカタログレコードの階層を作成できますが、カタログ割り当ては個別に作成する必要があります。
以下の一連の Web API 操作は、UniqueName: ContosoCustomerManagement のソリューションにカタログ階層と CatalogAssignment を作成します。 レコードが作成された際に、ソリューションへの関連付けを設定する MSCRM.SolutionUniqueName リクエストヘッダーの使用に注意してください。
詳細については、Web API を使用してレコードを作成する セクションの 基本的な作成 および 作成時のテーブル行の関連付け を参照してください。
ルート カタログを作成する
リクエスト:
POST [Organization URI]/api/data/v9.2/catalogs HTTP/1.1
MSCRM.SolutionUniqueName: ContosoCustomerManagement
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
"name": "Contoso Customer Management",
"uniquename": "contoso_CustomerManagement",
"displayname": "Contoso Customer Management",
"description": "The root catalog for the Contoso Customer Management solution",
"iscustomizable": {
"Value": false
}
}
応答:
HTTP/1.1 204 No Content
OData-EntityId: [Organization URI]/api/data/v9.2/catalogs(a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1)
テーブル イベント サブカタログの作成
リクエスト:
POST [Organization URI]/api/data/v9.2/catalogs HTTP/1.1
MSCRM.SolutionUniqueName: ContosoCustomerManagement
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
"name": "Contoso Customer Management Table Events",
"uniquename": "contoso_TableEvents",
"displayname": "Tables",
"description": "Groups Table events for the Contoso Customer Management Solution",
"iscustomizable": {
"Value": false
},
"ParentCatalogId@odata.bind": "catalogs(a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1)"
}
応答:
HTTP/1.1 204 No Content
OData-EntityId: [Organization URI]/api/data/v9.2/catalogassignments(b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2)
テーブル カタログで勘定カタログの割り当てを作成する
テーブルの ID についての情報は、テーブルの ID を取得するを参照してください。
リクエスト:
POST [Organization URI]/api/data/v9.2/catalogassignments HTTP/1.1
MSCRM.SolutionUniqueName: ContosoCustomerManagement
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
"name": "Account",
"EntityId@odata.bind": "entities(70816501-edb9-4740-a16c-6a5efbc05d84)",
"iscustomizable": {
"Value": false
},
"CatalogId@odata.bind": "catalogs(b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2)"
}
応答:
HTTP/1.1 204 No Content
OData-EntityId: [Organization URI]/api/data/v9.2/catalogassignments(c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3)
SDK for .NET の使用
次のコードは、UniqueName: ContosoCustomerManagement を持つソリューションで、カタログ階層とカタログ割り当てを作成する方法を示します。
注
そのソリューションのコンテキストでレコードを作成するには、CreateRequest Class で SolutionUniqueName オプション パラメーターを使用します。
詳細情報 : リクエストでオプションのパラメータを渡す
string conn = $@"
Url = {url};
AuthType = OAuth;
UserName = {userName};
Password = {password};
AppId = 51f81489-12ee-4a9e-aaae-a2591f45987d;
RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97;
LoginPrompt=Auto;
RequireNewInstance = True";
var service = new CrmServiceClient(conn);
// var service = new ServiceClient(conn);
var solutionUniqueName = " ContosoCustomerManagement ";
//Create the root catalog
Catalog rootCatalog = new Catalog
{
Name = "Contoso Customer Management",
UniqueName = "contoso_CustomerManagement",
DisplayName = "Contoso Customer Management",
Description = "The root catalog for the Contoso Customer Management solution",
IsCustomizable = new BooleanManagedProperty(false)
};
CreateRequest rootCatalogReq = new CreateRequest {
Target = rootCatalog
};
rootCatalogReq["SolutionUniqueName"] = solutionUniqueName;
Guid rootCatalogId = ((CreateResponse)service.Execute(rootCatalogReq)).id;
//Create the Table Events Sub-catalog
Catalog tableEvents = new Catalog
{
Name = "Contoso Customer Management Table Events",
UniqueName = "contoso_TableEvents",
DisplayName = "Tables",
Description = "Groups Table events for the Contoso Customer Management Solution",
IsCustomizable = new BooleanManagedProperty(false),
ParentCatalogId = new EntityReference("catalog", rootCatalogId)
};
CreateRequest tableEventsReq = new CreateRequest
{
Target = tableEvents
};
tableEventsReq["SolutionUniqueName"] = solutionUniqueName;
Guid tableEventsId = ((CreateResponse)service.Execute(tableEventsReq)).id;
//Create the Account Catalog Assignment on the Tables catalog
CatalogAssignment accountAssignment = new CatalogAssignment
{
Name = "Account",
IsCustomizable = new BooleanManagedProperty(false),
Object = new EntityReference("entity",new Guid("70816501-edb9-4740-a16c-6a5efbc05d84")),
CatalogId = new EntityReference("catalog", tableEventsId)
};
CreateRequest accountAssignmentReq = new CreateRequest
{
Target = accountAssignment
};
accountAssignmentReq["SolutionUniqueName"] = solutionUniqueName;
Guid accountAssignmentId = ((CreateResponse)service.Execute(accountAssignmentReq)).id;
ソリューション ファイルを編集して、カタログとカタログ割り当てを作成する
ソリューションファイル内のファイルを編集し、カタログおよびカタログの割り当てを作成できます。
SolutionPackager ツール を使用して、ソース コントロールで管理できるファイルにソリューションを抽出します。 続いて、ファイルを編集できます。 その後、SolutionPackager を使用して、解凍したファイルをソリューションに戻すことができます。 詳細情報: ソリューション ファイルによるソース コントロール
チップ
ソリューションでいくつかのカタログとカタログ割り当てを作成してから、ソリューションをエクスポートして展開し、複数の例を確認します。
最新版の Microsoft.CrmSdk.CoreTools NuGet パッケージ を使用しているか確認する
ソリューション ファイルを使用してカタログを作成する
ソリューション内では、すべてのカタログが catalogs フォルダ内に格納されます。 このフォルダー内のフォルダーとファイルを編集し、ソリューション パッケージャーを使用してパックされた後にソリューションをインポートすることにより、カタログを作成、変更、または削除できます。
各カタログは、カタログの uniquename と一致するフォルダー(contoso_CustomerManagement など)に含まれます。
フォルダー内には、カタログの定義を含む catalog.xml ファイルが入っています。
たとえば:
<catalog uniquename="contoso_CustomerManagement">
<description default="The root catalog for the Contoso Customer Management solution">
<label description="The root catalog for the Contoso Customer Management solution" languagecode="1033" />
</description>
<displayname default="Contoso Customer Management">
<label description="Contoso Customer Management" languagecode="1033" />
</displayname>
<iscustomizable>0</iscustomizable>
<name>Contoso Customer Management</name>
</catalog>
catalog 要素 uniquename 属性は、ファイルを含むフォルダーの名前と一致する必要があります。
catalog 要素には、これらの要素が含まれます:
| 要素 | 説明 |
|---|---|
description |
既定の説明の値を持つ default 属性があります。複数の言語が定義されている場合、 description と languagecode の属性を持つ label 要素が 1 つ以上含まれます。 |
displayname |
既定の表示名を値として持つ default 属性があります。複数の言語が定義されている場合、 description と languagecode の属性を持つ label 要素が 1 つ以上含まれます。 |
iscustomizable |
カタログがカスタマイズ可能かどうか。 0 = false, 1 = true。 |
name |
カタログの名前。 |
カタログがカテゴリを表す場合、親カタログとの関係は、親カタログの一意の名前を含む uniquename 要素を含む parentcatalogid 要素を使用して含まれます。
たとえば:
<catalog uniquename="contoso_TableEvents">
<description default="Groups Table events for the Contoso Customer Management Solution">
<label description="Groups Table events for the Contoso Customer Management Solution" languagecode="1033" />
</description>
<displayname default="Tables">
<label description="Tables" languagecode="1033" />
</displayname>
<iscustomizable>0</iscustomizable>
<name>Contoso Customer Management Table Events</name>
<parentcatalogid>
<uniquename>contoso_CustomerManagement</uniquename>
</parentcatalogid>
</catalog>
ソリューション ファイルを使用して CatalogAssignment を作成する
ソリューション内の Assetsフォルダに、catalogassignments.xml ファイルがあります。 すべてのカタログ割り当てがファイルに含まれています。 このファイルを編集して、ソリューション パッケージャーを使用してパックされた後にソリューションをインポートすることにより、カタログ割り当てを作成または変更できます。
たとえば:
<catalogassignments>
<catalogassignment object.logicalname="account" catalogid.uniquename="contoso_TableEvents" objectidtype="entity">
<iscustomizable>0</iscustomizable>
<name>Account</name>
</catalogassignment>
<catalogassignment catalogid.uniquename="contoso_CustomerEvents" object.uniquename="contoso_CustomerEnteredStore" objectidtype="customapi">
<iscustomizable>0</iscustomizable>
<name>Customer Entered Store</name>
</catalogassignment>
</catalogassignments>
各 catalogassignment 要素には次の属性があります:
| 属性 | 説明 |
|---|---|
catalogid.uniquename |
カタログ割り当ての対象であるサブカタログの一意の名前。 |
objecttypeid |
オブジェクトのタイプ。 有効な値は次の通りです:entitycustomapiworkflow |
objectypeid によって、各 catalogassignment 要素には、対応する次の属性のいずれかが必要です:
| 属性 | 説明 |
|---|---|
object.uniquename |
カスタム API の一意の名前 |
object.logicalname |
エンティティの論理名。 |
object.workflowid |
カスタム プロセス アクションの一意の ID 値。 |
catalogassignment 要素には、これらの要素が含まれます:
| 要素 | 説明 |
|---|---|
iscustomizable |
カタログ割り当てがカスタマイズ可能かどうか。 0 = false, 1 = true。 |
name |
カタログの割り当て名 |
関連項目
Microsoft Dataverse ビジネス イベント
Web API を使用してエンティティ レコードを作成する
Web API を使用してエンティティ レコードを取得する
.NET 用 SDK を使用してエンティティを作成する
.NET 用 SDK を使用してエンティティを取得する