コードを使用して Customer Engagement 内のカスタムビジネスアプリを作成および管理する

[アーティクル]
03/22/2023

Dynamics 365 Customer Engagement のビジネスアプリはモジュール型の、目的が組み込まれたアプリで、特定領域の作業に関連付けられるロールベースの機能を提供します。これらのアプリケーションにはシンプルで直観的なインターフェイスが用意され、日々の活動で必要とするものを簡単に検索できるようになっています。たとえば、Sales ビジネスアプリには、営業担当者に関連する適切な一連のフォーム、ビュー、ダッシュボード、およびプロセスフローのみの、よりシンプルで小さなサイトマップが用意されています。

システム管理者およびカスタマイザーは、セキュリティロールを使用してこれらのビジネスアプリケーションへのアクセスを提供することができます。ユーザーはアクセス許可を持つアプリケーションにのみアクセスすることができます。

Note

Dynamics 365 Customer Engagementのカスタムビジネスアプリは Power Apps のモデル駆動型アプリと同じです; どちらも同じ基盤プラットフォーム上に構築されています。詳細: モデル駆動型アプリとは

アプリデザイナーを使用したカスタムビジネスアプリの作成に加え、Dynamics 365 Customer Engagement (on-premises) でカスタムビジネスアプリをプログラムで作成および管理できるようになりました。

重要

必要でない限りカスタムビジネスアプリを構築するためにコードを記述する必要はありません。アプリデザイナーには、タイルベースの情報構造およびさらに単純なインターフェイスを提供することにより、コードを記述する必要なしにカスタムビジネスアプリを構築するための単純で直観的なエクスペリエンスが用意されています。確認: アプリデザイナーを使用して、カスタムビジネスアプリを設計

カスタムビジネスアプリの作成には以下の手順が含まれます。

AppModule エンティティインターフェイスを作成してアプリとそのプロパティを定義します。
AddAppComponents および RemoveAppComponents アクションを使用するカスタムアプリのエンティティ、サイトマップ、および他のコンポーネントなどの、コンポーネントをアプリに追加または削除します。
ValidateApp 関数を使用することにより、欠落している必須コンポーネントのアプリを確認します。
アプリを公開します。
適切なセキュリティロールをカスタムビジネスアプリに関連付けて、ユーザーにアクセスを提供します。

ビジネスアプリを作成およびプロパティを定義する

アプリを作成するには、システム管理者またはシステムカスタマイザーのセキュリティロール、または同等のアクセス許可が必要です。

アプリを作成するには、少なくとも以下のプロパティを指定する必要があります。

name: アプリに対して一意
uniquename: これはユーザーのアプリの名前とは異なる場合があり、英文字および数字のみで構成されます。このアプリを作成するとき、ソリューション発行者の接頭辞 (たとえば 'new_') が名前に自動的に付きます。
webresourceid: アプリのイメージアイコンとして設定する Web リソースの ID です。システムにはデフォルトのWebリソース (ID: 953b9fac-1e5e-e611-80d6-00155ded156f) が用意されており、アプリケーションのアイコンとして使用できます。

次の Web API 要求はアプリの統合インターフェイスの種類を作成します:

POST [Organization URI]/api/data/v9.1/appmodules HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "name": "SDKTestApp",
    "uniquename":"SDKTestApp",
    "webresourceid":"953b9fac-1e5e-e611-80d6-00155ded156f"    
}

応答 OData-EntityId ヘッダーには、作成したアプリの URI が含まれています。

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.1/appmodules(dd621d4a-d898-e711-80e7-00155db763be)

ビジネスアプリからコンポーネントを追加または削除する

ビジネスアプリに含める、サイトマップ、エンティティ、ダッシュボード、ビジネスプロセスフロー、ビュー、およびフォームなどの、アプリ内のコンポーネントを追加または削除することができます。ビジネスアプリに追加可能なコンポーネントの詳細については、アプリデザイナーでアプリコンポーネントを追加または編集を参照してください。

AddAppComponents アクションまたはAddAppComponentsRequest メッセージを使用してコンポーネントをビジネスアプリに追加します。そのアクションでは以下の内容を指定する必要があります。

AppId: コンポーネントを追加するアプリケーションの ID
コンポーネント追加するコンポーネントのコレクションです。追加するコンポーネントの ID およびエンティティの種類を指定する必要があります。 Customer Engagement Web API のエンティティの種類のリストについては、Web API Entity Type Reference を参照してください。

次の Web API 要求は、ビュー (savedquery) およびフォーム (systemform) をアプリに追加します。

POST [Organization URI]/api/data/v9.1/AddAppComponents HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
	"AppId":"dd621d4a-d898-e711-80e7-00155db763be",
	"Components":[
		{
			"savedqueryid":"00000000-0000-0000-00aa-000000666000",
			"@odata.type":"Microsoft.Dynamics.CRM.savedquery"
		},
		{
			"formid":"c9e7ec2d-efca-4e4c-b3e3-f63c4bba5e4b",
			"@odata.type":"Microsoft.Dynamics.CRM.systemform"
		}
	]
}

アプリからコンポーネントを削除するには、RemoveAppComponents アクションまたは RemoveAppComponentsRequest メッセージを使用します。このアクションは、AddAppComponents アクションと同じパラメーターのセットを使用します。

次の Web API 要求はビュー (savedquery) をアプリから削除します。

POST [Organization URI]/api/data/v9.1/RemoveAppComponents HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
	"AppId":"dd621d4a-d898-e711-80e7-00155db763be",
	"Components":[
		{
			"savedqueryid":"00000000-0000-0000-00aa-000000666000",
			"@odata.type":"Microsoft.Dynamics.CRM.savedquery"
		}
	]
}

ビジネスアプリを検証する

アプリの検証には、アプリが適切に動作することを確認するための、ビジネスアプリ内に追加済みのコンポーネントの依存関係のチェックが含まれます。これはアプリデザイナーで検証をクリックすることと同じです。詳細: アプリケーションを検証する

ValidateApp 関数または ValidateAppRequest メッセージを使用してアプリを検証します。以下のWeb API要求は、次に示すIDを使用してビジネスアプリを検証する方法を説明します: dd621d4a-d898-e711-80e7-00155db763be

GET [Organization URI]/api/data/v9.1/ValidateApp(AppModuleId=dd621d4a-d898-e711-80e7-00155db763be)

検証エラーが発生しなければ、応答は次のいずれかになります。

HTTP/1.1 200 OK
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.ValidateAppResponse",
    "AppValidationResponse": {
        "ValidationSuccess": true,
        "ValidationIssueList": []
    }
}

アプリに検証の問題がある場合、応答により ValidationIssueList コレクション内にエラー/警告が表示されます。

HTTP/1.1 200 OK
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.ValidateAppResponse",
    "AppValidationResponse": {
        "ValidationSuccess": false,
        "ValidationIssueList": [
            {
                "ErrorType": "Error",
                "Message": "App does not contain Site Map",
                "DisplayName": null,
                "ComponentId": "00000000-0000-0000-0000-000000000000",
                "ComponentType": 0,
                "ComponentSubType": 0,
                "ParentEntityId": "00000000-0000-0000-0000-000000000000",
                "ParentEntityName": null,
                "CRMErrorCode": -2147155684,
                "RequiredComponents": []
            },
            {
                "ErrorType": "Warning",
                "Message": "Account doesn’t reference a form or view. App users will see all forms and views.",
                "DisplayName": null,
                "ComponentId": "00000000-0000-0000-0000-000000000000",
                "ComponentType": 0,
                "ComponentSubType": 0,
                "ParentEntityId": "00000000-0000-0000-0000-000000000000",
                "ParentEntityName": null,
                "CRMErrorCode": -2147155691,
                "RequiredComponents": []
            }
        ]
    }
}

ビジネスアプリを公開する

必須コンポーネントをカスタムビジネスアプリに追加して検証したら、ユーザーが使用可能にするために公開する必要があります。

PublishXml アクションまたは PublishXmlRequest メッセージを使用してカスタムビジネスアプリを公開します。以下の Web API 要求は、次に示す ID を使用してビジネスアプリを公開する方法を説明します: dd621d4a-d898-e711-80e7-00155db763be

POST [Organization URI]/api/data/v9.1/PublishXml HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{  
  "ParameterXml":"<importexportxml><appmodules><appmodule>dd621d4a-d898-e711-80e7-00155db763be</appmodule></appmodules></importexportxml>"
}

セキュリティロールを使用してビジネスアプリへのアクセスを管理する

ユーザーが設定>マイアプリ領域または Dynamics 365 Customer Engagement (on-premises) ホームページからアクセスできるようアプリへのアクセス権限をユーザーに提供するため、セキュリティロールをビジネスアプリに関連付けることができます。関連付けられたセキュリティロールが割り当てられているユーザーは Customer Engagement のビジネスアプリを表示および使用することができます。

AppModule エンティティエンティティの appmoduleroles_association ナビゲーションプロパティを使用して、ビジネスアプリをセキュリティロールに関連付けます。次の要求はビジネスアプリをセキュリティロールと関連付ける方法を示しています。

POST [Organization URI]/api/data/v9.1/appmodules(dd621d4a-d898-e711-80e7-00155db763be)appmoduleroles_association/$ref HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{  
  "@odata.id":"[Organization URI]/api/data/v9.1/roles(<roleId>)"
}

ビジネスアプリからセキュリティロールの関連付けを解除するには、同じナビゲーションプロパティで DELETE 要求を使用します。たとえば、次のようになります。

DELETE [Organization URI]/api/data/v9.1/appmodules(dd621d4a-d898-e711-80e7-00155db763be)/appmoduleroles_association/$ref?$id=[Organization URI]/api/data/v9.1/roles(<roleId)

ビジネスアプリとそのコンポーネントの管理

このセクションでは、アプリの取得、アプリのプロパティの更新、アプリのコンポーネントの取得、およびアプリの削除に関する情報を提供します。

公開済みアプリの取得

公開済みアプリを取得するには、以下の要求を使用します。

GET [Organization URI]/api/data/v9.1/appmodules?$select=name

未公開のアプリの取得

未公開アプリを取得するには、RetrieveUnpublishedMultiple 関数を使用します。たとえば、次のようになります。

GET [Organization URI]/api/data/v9.1/appmodules/Microsoft.Dynamics.CRM.RetrieveUnpublishedMultiple()?$select=name

公開済みビジネスアプリ内のコンポーネントの取得

ビジネスアプリのアプリコンポーネントを取得するには、RetrieveAppComponents 関数または RetrieveAppComponentsRequest メッセージを使用します。たとえば、次のようになります。

GET [Organization URI]/api/data/v9.1/RetrieveAppComponents(AppModuleId=dd621d4a-d898-e711-80e7-00155db763be)

公開済みビジネスアプリに関連付けられたセキュリティロールの取得

ユーザーのビジネスアプリに関連付けられたセキュリティロールを取得するには、$expand システムクエリオプションを appmoduleroles_association ナビゲーションプロパティと共に使用します。たとえば、ID: dd621d4a-d898-e711-80e7-00155db763be のビジネスアプリに関連付けられたすべてのセキュリティ役割を取得する要求は次のとおりです。

GET [Organization URI]/api/data/v9.1/appmodules(dd621d4a-d898-e711-80e7-00155db763be)?$expand=appmoduleroles_association&$select=name,appmoduleroles_association

ビジネスアプリの削除

DELETE 要求を使用してビジネスアプリを削除します。たとえば、次のようになります。

DELETE [Organization URI]/api/data/v9.1/appmodules(dd621d4a-d898-e711-80e7-00155db763be)

ビジネスアプリのクライアント API サポート

以下のクライアント API を使用してビジネスアプリの作業をすることができます。

次の方法で共有

コードを使用して Customer Engagement 内のカスタムビジネスアプリを作成および管理する

ビジネスアプリを作成およびプロパティを定義する

ビジネスアプリからコンポーネントを追加または削除する

ビジネスアプリを検証する

ビジネスアプリを公開する

セキュリティロールを使用してビジネスアプリへのアクセスを管理する

ビジネスアプリとそのコンポーネントの管理

公開済みアプリの取得

未公開のアプリの取得

公開済みビジネスアプリ内のコンポーネントの取得

公開済みビジネスアプリに関連付けられたセキュリティロールの取得

ビジネスアプリの削除

ビジネスアプリのクライアント API サポート

関連項目

フィードバック

その他のリソース

次の方法で共有

コードを使用して Customer Engagement 内のカスタム ビジネス アプリを作成および管理する

ビジネス アプリを作成およびプロパティを定義する

ビジネス アプリからコンポーネントを追加または削除する

ビジネス アプリを検証する

ビジネス アプリを公開する

セキュリティ ロールを使用してビジネス アプリへのアクセスを管理する

ビジネス アプリとそのコンポーネントの管理

公開済みアプリの取得

未公開のアプリの取得

公開済みビジネス アプリ内のコンポーネントの取得

公開済みビジネス アプリに関連付けられたセキュリティ ロールの取得

ビジネス アプリの削除

ビジネス アプリのクライアント API サポート

関連項目

フィードバック

その他のリソース

コードを使用して Customer Engagement 内のカスタムビジネスアプリを作成および管理する

ビジネスアプリを作成およびプロパティを定義する

ビジネスアプリからコンポーネントを追加または削除する

ビジネスアプリを検証する

ビジネスアプリを公開する

セキュリティロールを使用してビジネスアプリへのアクセスを管理する

ビジネスアプリとそのコンポーネントの管理

公開済みビジネスアプリ内のコンポーネントの取得

公開済みビジネスアプリに関連付けられたセキュリティロールの取得

ビジネスアプリの削除

ビジネスアプリのクライアント API サポート