Catalog と CatalogAssignment テーブル

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) でカタログ レコードとカタログ割り当て レコードを作成できます。

ソリューションの一部として、常にカタログを作成する必要があります。 次の手順を使用して、カタログ レコードを作成します。

  1. Power Apps にサインイン

  2. 左側のナビゲーション ペインで、ソリューション を選択します。

  3. 使用するソリューションを作成または選択して、新規をクリックします。

  4. メニューからカタログを選択すると、新しいウィンドウが開きます。

  5. 以下のフィールドに入力します:

    フィールド 説明
    親項目のカタログ ソリューション ルートカタログに親カタログを設定しないでください。 それ以外の場合は、ソリューション ルート カタログを設定します。
    一意の名前 一意の名前にはカスタマイズ接頭辞が必要であり、スペースを含めることはできません。 この接頭辞は、ソリューション発行者のカスタマイズ接頭辞と同じである必要があります。
    名前 カタログの名前を入力してください。 通常は一意の名前と同じですが、カスタマイズ接頭辞を使わず、スペースを含みます。
    表示名 通常は、名前と同じです。
    説明 カタログの説明をわかりやすく入力します。
  6. フォームを保存して閉じます。

Power Apps でカタログ割り当てを作成

Power Apps のカタログを含む同じソリューションを使用する

  1. 新規をクリックします。

  2. メニューからカタログの割り当てを選択すると、新しいウィンドウが開きます。

  3. 名前を入力してください。 この値は、カスタマイズ接頭辞から始まり、スペースを含まない必要があります。 ソリューション発行者に対して定義されたのと同じカスタマイズ接頭辞を使用する必要があります。

  4. カタログ割り当てオブジェクトを設定します。 このルックアップにより、3 つの異なるタイプのレコードを設定できます。

    • カスタム API 群
    • エンティティ
    • プロセス

    名前を入力することで、探しているタイプを見つけることができます。

  5. カタログを選択

    注

    選択するカタログは、カテゴリを表す第 2 レベルのカタログである必要があります。

  6. フォームを保存して閉じます

管理ソリューションのカタログ アイテムのカスタマイズをブロックする

管理ソリューションをインストールするユーザーがカタログとカタログの割り当てをカスタマイズできるようにする場合を除いて、IsCustomizable プロパティを false に設定する必要があります。なぜなら、既定値を使うとカスタマイズできるためです。

これを Power Apps UI で設定するには:

  1. ソリューション内の各カタログまたはカタログ割り当てを選択します

  2. メニューで、省略記号ボタン (...) をクリックし、管理プロパティを選択します。

    省略記号ボタンをクリックして、管理プロパティ ボタンを表示します。

  3. 開いたウィンドウで、カスタマイズを許可するの選択を解除します。

    [カスタマイズを許可]の選択を解除します。

  4. 完了をクリックします。

テーブル ダイアグラム

次の図は、Catalog テーブルと CatalogAssignment テーブル間の関連付けを示しています

Catalog テーブルと CatalogAssignment テーブルの図

ParentCatalogId を使用した自己参照関係により、1つのソリューション カタログと、カタログ レコードを使ってカテゴリーを表現した複数のカタログの間に 2 段階の階層を作成できます。

カタログ テーブルの列

利用可能なすべての列と関連付けは、Catalog テーブル/エンティティの参照 で利用できます。

次の表には、設定可能なカタログ テーブル/エンティティの列/属性のうち、選択されたものが含まれています。

表示名
SchemaName
LogicalName
タイプ 説明
カタログ
CatalogId
catalogid
Uniqueidentifier カタログ インスタンスの一意識別子です。
説明
Description
description
String カタログ インスタンスのローカライズされた説明です。
必須
表示名
DisplayName
displayname
String カタログ インスタンスのローカライズされた表示名です。
必須
カスタマイズ可能
IsCustomizable
iscustomizable
ManagedProperty カタログのカスタマイズや削除を行うかどうかを制御します。
既定値は true です。 詳細: 管理ソリューションのカタログ アイテムのカスタマイズをブロックする
必須
名前
Name
name
String カタログの主要な名前です。
必須
親 Catalog
ParentCatalogId
parentcatalogid
検索 親カタログの一意の識別子。
保存後に変更できません。
一意の名称
UniqueName
uniquename
String カタログを表す一意の名前です。
必須
カスタマイズ接頭辞で始める必要があります。

注

カタログの割り当てをカタログに関連付けると、カタログ割り当てを削除するまでそのカタログを削除できなくなります。

CatalogAssignment テーブルの列

利用可能なすべての列と関連付けは、CatalogAssignment テーブル/エンティティ参照 で利用できます。

次の表には、設定可能な CatalogAssignment テーブル/エンティティの選択された列/属性が含まれています。

表示名
SchemaName
LogicalName
タイプ 説明
カタログ割り当て
CatalogAssignmentId
catalogassignmentid
Uniqueidentifier カタログ割り当てインスタンスを表す一意識別子です。
カタログ
CatalogId
catalogid
検索 カタログ割り当てに関連付けられたカタログを表す一意識別子です。
必須
カスタマイズ可能
IsCustomizable
iscustomizable
ManagedProperty CatalogAssignment をカスタマイズまたは削除できるかどうかを制御します。
既定値は true です。 詳細: 管理ソリューションのカタログ アイテムのカスタマイズをブロックする
必須
名前
Name
name
String カタログ割り当ての主要名。
カタログ割り当てオブジェクト
Object
object
検索 カタログ割り当てに関連付けられたオブジェクトを表す一意識別子です。
必須
保存後に変更できません。
このポリモーフィック ルックアップは、次のテーブルにリンクできます:
  customapi
  エンティティ
  ワークフロー

Web API を使用してこのポリモーフィックな関係を関連付ける場合は、各関係に単一値のナビゲーション プロパティ名を使用する必要があります。

これらの名前は次のとおりです。
  CustomAPIId
  EntityId
  WorkflowId

テーブル、カスタム 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 オブジェクトのタイプ。 有効な値は次の通りです:
entity
customapi
workflow

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 を使用してエンティティを取得する