チャネルメンバーを追加して、変更イベント強化を設定する

メモ

日本語で受講されている方へ
このバッジの Trailhead ハンズオン Challenge は英語で受講していただく必要があります。英語の意味についてはかっこ内の翻訳をご参照ください。Trailhead Playground では (1) [Locale (地域)] を [United States (米国)] に、[Language (言語)] を [English (英語)] に切り替えて、(2) 英語の値のみをコピーして貼り付けてください。こちらの指示に従ってください。

翻訳版の Trailhead を活用する方法については、自分の言語の Trailhead バッジをご覧ください。

カスタムチャネルを設定したら、次は、このカスタムチャネルを使用し、取引先の変更イベント通知を有効にして、イベント強化を設定します。

イベント強化とは?

イベント強化を使用すると、変更イベントに変更のない項目を含めることができ、データの処理やレプリケーションが容易になります。たとえば、アプリケーションで外部システムのレコードを照合するために外部 ID 項目が必要な場合、強化を使用します。または、変更レコードに関する重要な情報を提供する項目を常に含めたい場合に使用します。

サポートされている種別の項目を選択できます。空でない強化された項目は、更新操作と削除操作の変更イベントメッセージに含まれます。変更イベントを強化する項目は、強化されたイベント項目 (略して、強化された項目) です。イベント強化は、標準の /data/ChangeEvents チャネルやカスタムチャネルなど、複数のエンティティをサポートするチャネルで利用可能です。イベント強化は、CometD および Pub/Sub API の登録者で利用できますが、Apex トリガーではマルチエンティティチャネルがサポートされていないため、Apex トリガーでは利用できません。強化された項目はチャネルメンバーの一部として追加します。

イベント強化の詳細は、『Change Data Capture Developer Guide (変更データキャプチャ開発者ガイド)』の「Enrich Change Events with Extra Fields (追加項目による変更イベントの強化)」と「Event Enrichment Considerations (イベント強化の考慮事項)」を参照してください。

営業インテグレーションアプリケーションのシナリオ例

インテグレーションアプリケーションは、Salesforce の取引先レコードのデータ変更を Salesforce 以外の ERP システムに同期します。このアプリケーションは、取引先レコードの変更に関する変更イベントを受信し、その変更を外部データストアに同期します。変更をより適切に同期するために、イベントは空でないときに常に存在する追加項目 (External_Account_ID__c および Industry) で強化されます。インテグレーションアプリケーションは、External_Account_ID__c 項目を使用して、Salesforce レコードと外部データストアのレコードを照合します。また、このアプリケーションは Industry 項目を使用して、外部システムで関連する変更も行います。

従業員オブジェクトと HR アプリケーションのイベント強化シナリオ。

カスタム取引先項目を作成する

設定する強化された項目の 1 つは取引先のカスタム項目であるため、次のステップに進む前にまずその項目を作成します。

歯車アイコンをクリックして、[Setup (設定)] を選択します。新しいタブで [Setup (設定)] が起動します。
[Home (ホーム)] の横にある [Object Manager (オブジェクトマネージャー)] タブをクリックします。
[Account (取引先)] を選択します。
左側のナビゲーションの [Fields & Relationships (項目とリレーション)] を選択して、[New (新規)] をクリックします。
[Data Type (データ型)] に [Text (テキスト)] を選択して、[Next (次へ)] をクリックします。
項目ウィザードに従って次の項目を作成します。

Field Label (項目の表示ラベル): External Account ID (外部取引先 ID)
Length (文字数): 18
External ID (外部 ID): Checked (オン)

その他の項目はデフォルトのまま変更せず、[Next (次へ)] をクリックします。
もう一度 [Next (次へ)] をクリックして、項目の表示とセキュリティのデフォルト設定を受け入れます。
[Save (保存)] をクリックして、External Account ID (外部取引先 ID) 項目をページレイアウトに追加します。

通知を有効化して、強化された項目を追加する

PlatformEventChannelMember を追加し、取引先の変更イベント通知を有効にして、強化された項目を追加します。通知の有効化は selectedEntity 項目を介して行われ、強化された項目は enrichdedFields 配列に追加されます。強化された項目は External_Account_ID__c と Industry です。

Salesforce API コレクションのフォークで、[Event Platform (イベントプラットフォーム)] > [Custom Channels (カスタムチャネル)] > [Change Data Capture (変更データキャプチャチャネル)] の順に展開し、[Create channel member (チャネルメンバーを作成)] をクリックします。

[Body (ボディ)] をクリックして、[Raw (未加工)] と [JSON] のオプションが選択されていることを確認します。

{
  "FullName": "SalesEvents_chn_AccountChangeEvent",
  "Metadata": {
    "enrichedFields": [
      {
        "name": "External_Account_ID__c"
      },
      {
        "name": "Industry"
      }
    ],
    "eventChannel": "SalesEvents__chn",
    "selectedEntity": "AccountChangeEvent"
  }
}

[Send (送信)] をクリックします。
応答状況が [201 Created (201 作成済み)] であることを確認します。

応答で、次のような新しいカスタムチャネルの ID が返されます。

{
    "id": "0v88b0000004CgVAAU",
    "success": true,
    "errors": [],
    "warnings": [],
    "infos": []
}

次の画像は Postman で返された要求と応答を示しています。

この例では、selectedEntity は取引先オブジェクトです。標準オブジェクトの selectedEntity の形式は <Object>ChangeEvent になります。カスタムオブジェクトの場合、形式は <Object>__ChangeEvent になります。

PlatformEventChannelMember は、チャネルと selectedEntity にすでに存在している場合は上書きできません。PATCH 要求でチャネルメンバーを更新することも、チャネルメンバーを削除して再度作成し、強化された項目を追加することもできます。このプロジェクトでは、更新の実行方法を学習します。

強化された項目を照会する

便利な Tooling API オブジェクトである EnrichedField を使用すると、チャネルとチャネルメンバーに設定されている強化された項目を確認できます。REST を使用して、Tooling API で EnrichedField を照会します。

コレクションのフォークで、[Tooling] の [Tooling Query (Tooling クエリ)] を選択します。
[Params (パラメーター)] タブで、q の行に値 SELECT Id,ChannelMemberId,Field FROM EnrichedField ORDER BY ChannelMemberId を追加します。完全な URI は次のようになります。{{_endpoint}}/services/data/v{{version}}/tooling/query/?q=SELECT Id,ChannelMemberId,Field FROM EnrichedField ORDER BY ChannelMemberId
[Send (送信)] をクリックします。

強化された項目を照会するための Postman での Tooling API クエリと応答

返される応答は次の例のようになります。返されたサイズが 2 ということは、強化された項目が 2 つあることを意味します。各強化された項目はレコード配列にリストされます。また、各強化された項目にはチャネルメンバー ID が設定され、これは前のステップで作成したメンバーに対応します。強化された項目名は Field に返されます。Industry という項目名が表示されていることがわかります。カスタム項目の場合、Field には項目 ID が含まれ、名前は含まれません。

{
  "size": 2,
  "totalSize": 2,
  "done": true,
  "queryLocator": null,
  "entityTypeName": "EnrichedField",
  "records": [
    {
      "attributes": {
        "type": "EnrichedField",
        "url": "/services/data/v58.0/tooling/sobjects/EnrichedField/0dz8b000000CaSaAAK"
      },
      "Id": "0dz8b000000CaSaAAK",
      "ChannelMemberId": "0v88b0000004CgVAAU",
      "Field": "Industry"
    },
    {
      "attributes": {
        "type": "EnrichedField",
        "url": "/services/data/v58.0/tooling/sobjects/EnrichedField/0dz8b000000CaSZAA0"
      },
      "Id": "0dz8b000000CaSZAA0",
      "ChannelMemberId": "0v88b0000004CgVAAU",
      "Field": "00N8b00000J5pySEAR"
    }
  ]
}

カスタム項目の場合、項目名が ID として返されます。この例では、"Field":"00N8b00000J5pySEAR" です。対応する項目名は、CustomField で Tooling API クエリを実行することで取得できます。たとえば、次の Tooling クエリでは、指定された項目 ID の DeveloperName の項目名が返されます: SELECT Id,DeveloperName FROM CustomField WHERE Id='<field_Id>'。<field_Id> を EnrichedField クエリで返される項目 ID 値に置き換えると、DeveloperName で取得される名前は "External_Account_ID" になります。

別の方法として、開発者コンソールのクエリエディターでクエリを実行し、[Use Tooling API (Tooling API を使用)] オプションをオンにすることもできます。詳細は、Salesforce ヘルプの「開発者コンソールのクエリエディター」を参照してください。