変更データキャプチャの特性
学習の目的
この単元を完了すると、次のことができるようになります。
- 変更データキャプチャで使用できるオブジェクトを把握する。
- 変更イベントヘッダーで返される項目を挙げ、操作ごとに本文に含まれる項目について説明する。
- 変更イベントチャネル名を作成する。
- 変更イベントへの登録に必要な権限を挙げる。
オブジェクトのサポート
変更データキャプチャでは、Salesforce 組織で定義されたすべてのカスタムオブジェクト、および標準オブジェクトのサブセットについて変更イベントを生成できます。よく使用される標準オブジェクト (Account、Contact、Lead、User、Order、OrderItem、Product2 など) のほとんどで変更イベントがサポートされます。変更イベントをサポートするオブジェクトのリストについては、『Salesforce および Lightning プラットフォームのオブジェクトリファレンス』の「StandardObjectNameChangeEvent」を参照してください。
レコード変更の通知を受信するには、[設定] の [変更データキャプチャ] ページで関心のあるカスタムオブジェクトとサポート対象の標準オブジェクトを選択します。オブジェクトの設定手順については、このモジュールの後半で説明します。
変更イベントの例
Robert を覚えていますか? 彼がコンサルティングしているお客様は、従業員データを管理するカスタム HR アプリケーションの一部である、Employee__c というカスタムオブジェクトを定義しています。Salesforce の従業員データを外部の HR システムと同期するため、Robert は新しい従業員レコードと変更された従業員レコードの変更イベントを受信して統合するアプリケーションを作成しました。
このアプリケーションが受信するイベントメッセージの例を見てみましょう。Salesforce でユーザーが作成した新規従業員レコードのデータが含まれています。changeType
と entityName
の項目値に注目してください。
{ "schema": "-pszPCNGMHqUPU1ftkjxEA", "payload": { "ChangeEventHeader": { "commitNumber": 65824495947, "commitUser": "005RM000001vI4mYAE", "sequenceNumber": 1, "entityName": "Employee__c", "changeType": "CREATE", "changedFields": [], "changeOrigin": "com/salesforce/api/soap/47.0;client=SfdcInternalAPI/", "transactionKey": "0005163c-8d04-d729-39bd-b917b035a66c", "commitTimestamp": 1569436136000, "recordIds": [ "a00RM0000004ICOYA2" ] }, "First_Name__c": "Jane", "Tenure__c": 2.0, "Name": "e-100", "Last_Name__c": "Smith", "CreatedDate": "2019-09-25T18:28:55.000Z", "LastModifiedDate": "2019-09-25T18:28:55.000Z", "OwnerId": "005RM000001vI4mYAE", "CreatedById": "005RM000001vI4mYAE", "LastModifiedById": "005RM000001vI4mYAE", }, "event": { "replayId": 1 } }
この変更イベントメッセージの例には、作成日のようなシステム項目に加え、名、姓、在職期間などの従業員項目が含まれています。新規レコードの場合、ユーザーが設定しなかった項目はイベントメッセージから除外されます。たとえば、ユーザーが在職期間項目を入力しなかった場合、それはイベントメッセージから除外されます。
ChangeEventHeader
項目には、イベントに関する情報を持つヘッダー項目が含まれます。次に挙げるヘッダー項目には注意が必要です。
entityName
この項目には、このレコード変更の標準オブジェクトまたはカスタムオブジェクトの名前が含まれます。この例では Employee__c です。
changeType
この項目には、変更を発生させた操作が含まれます。一般的な変更イベントの場合、この項目には次のいずれかの値が含まれます。
CREATE
UPDATE
DELETE
UNDELETE
この例はレコード作成に関する変更イベントであるため、値は CREATE
です。
changedFields
この項目を使用して、更新操作で変更された項目を知ることができます。この項目は、他の操作では空です。変更イベントの例は新規レコード用であるため、この項目は空です。1 つ以上の項目を更新すると、項目名と LastModifiedDate と共に changedFields
に追加されます。たとえば、First_Name__c が変更された場合、この項目値は ["LastModifiedDate", "First_Name__c"]
になります。
changeOrigin
この項目を使用して変更の原因を特定します。インテグレーションアプリケーションが同じオブジェクトのレコードの変更に応じてレコードを変更する場合、変更が永遠に続くことがあります。こうした循環を回避するために、この項目を使用してアプリケーションが変更を開始したのかどうかを検出し、その場合には変更を再び処理せず、変更の執拗な繰り返しが生じないようにします。この項目には、変更を開始した Salesforce API と API クライアント ID が含まれます (クライアントで設定された場合)。変更が API アプリケーションによって行われた場合または Lightning Experience から実行された場合は、この項目に入力されます。それ以外は空になります。
たとえば、clientID
が GetCloudy
のアプリケーションが SOAP API を通じて従業員レコードを作成した場合、[changeOrigin]
項目値は [com/salesforce/api/soap/47.0;client=GetCloudy]
になります。個の例では、値は com/salesforce/api/soap/47.0;client=SfdcInternalAPI/
ですから、レコードの変更が Salesforce ユーザーインターフェースを通じて行われたことを意味します。
トランザクション関連のヘッダー項目
次のヘッダー項目には、現在の変更のトランザクションに関する情報が含まれます。
transactionKey
sequenceNumber
このトランザクション項目を使用して、組織のデータの正確なレプリカを別のシステムで維持します。transactionKey 項目は、変更が含まれるトランザクションを一意に識別します。sequenceNumber 項目は、トランザクション内の変更の順序を識別します。この連番は、複数のステップが含まれる操作で便利です。たとえば、リードの取引開始や、after insert Apex トリガーでの関連レコードの作成などです。トランザクションに関与するすべてのオブジェクトが変更データキャプチャで有効になっていない場合は、連番が飛んでいます。1 つのトランザクションのすべての変更をシステム内の 1 回のコミットで複製することをお勧めします。
トランザクションベースの複製プロセスを使用しないことを選択した場合、登録が停止すると複製されたデータが完全ではなくなる可能性があります。たとえば、登録が 1 つのトランザクションのイベントストリームの途中で停止した場合、トランザクションの変更の一部のみがシステムで複製されます。
イベント再生 ID 項目
イベントメッセージの最後の部分には、replayId という項目が含まれます。この項目には、イベントメッセージの ID が含まれ、過去 3 日以内のイベントを再生するために使用できます。このモジュールでは、イベントの再生については説明しません。詳細は、「リソース」セクションを参照してください。
イベントメッセージの本文に含まれる項目
CometD クライアントが受信するイベントメッセージに Salesforce が含める項目は、実行される操作とサブスクライバー種別に応じて異なります。たとえば、新しいレコードの場合、CometD クライアントが受信するイベントメッセージには空でないすべてのレコード項目とシステム項目が含まれます。一方、Apex トリガーまたは Pub/Sub API クライアントの場合、イベントメッセージには空であるか否かにかかわらずすべてのレコードとシステム項目が含まれます。詳細は、『Change Data Capture Developer Guide (変更データキャプチャ開発者ガイド)』の「Change Event Body Fields (変更イベント本文の項目)」を参照してください。
イベントメッセージ内の項目の順序
JSON イベントメッセージ内の項目の順序は保証されません。順序は、変更イベントのベースとなった基盤の Apache Avro スキーマ (データ逐次化システム) に従います。イベントが JSON 形式に展開されるとき、イベントの受信に使用されたクライアントに応じて、項目の順序がスキーマとは一致しないことがあります。
マージされた変更イベント
1 秒以内に同じオブジェクト種別の複数のレコードで同じ変更が行われた場合は、効率化するために 1 つのトランザクションの複数の変更イベントが 1 つのイベントにマージされることがあります。変更イベントがマージされると、Salesforce は影響を受けるすべてのレコードに対する 1 つの変更イベントと recordIds
項目を送信します。この項目には、同じ変更が行われたすべてのレコードの ID が含まれます。詳細は、『Change Data Capture Developer Guide (変更データキャプチャ開発者ガイド)』の「Merged Change Events (マージされた変更イベント)」を参照してください。
追加項目による変更イベントの強化
CometD 登録者に配信される変更イベントを強化するための項目を選択します。選択された項目は、変更がなくても変更イベントメッセージに含まれます。たとえば、アプリケーションに外部システムのレコードを照合するための外部 ID 項目が必要な場合に強化を使用します。または、変更レコードに関する重要情報を提供する項目を常に含めます。詳細は、『Change Data Capture Developer Guide (変更データキャプチャ開発者ガイド)』の「Enrich Change Events with Extra Fields (追加項目による変更イベントの強化)」と Trailhead の「Create a Custom Channel and Enrich Change Events (カスタムチャンネルを作成し、変更イベントを拡充する)」プロジェクトを参照してください。
その他の種別のイベント: ギャップイベントとオーバーフローイベント
その他の種別の変更イベントは、特別な状況に対処するために生成されます。Salesforce では、変更イベントが生成できない場合や、登録者にエラーを通知するためにギャップイベントが生成されます。オーバーフローイベントは、変更の量が多い場合に生成されます。ギャップイベントとオーバーフローイベントにはレコードデータは含まれません。ギャップイベントにはレコード ID が含まれているため、レコードデータを取得できます。詳細は、『Change Data Capture Developer Guide (変更データキャプチャ開発者ガイド)』の「Gap Events (ギャップイベント)」、「Overflow Events (オーバーフローイベント)」、「High-Level Replication Steps (複製手順の概要)」を参照してください。
イベントチャネルへの登録
変更イベントメッセージがどのようなものかがわかったので、次は変更イベントの受信方法を確認しましょう。Salesforce では、変更イベントチャネルへの登録に複数の方法が用意されています。Salesforce 以外のアプリケーションの場合、ストリーミング API、またはプッシュテクノロジーをシミュレートするオープンソースライブラリの CometD に基づくツールやライブラリを使用できます。ストリーミング API は、CometD に基づく登録メカニズムを提供します。
Lightning プラットフォームでデータの変更を非同期に処理するには、変更イベントの Apex トリガーを記述します。変更イベントの Apex トリガーについては、このモジュールの後半で詳しく説明します。
Lightning プラットフォーム上で実行されるアプリケーションで Salesforce データの変更に関するインスタント通知を受信するには、empApi Lightning コンポーネントを使用できます。
チャネルに登録することで、アプリケーションがどのイベントの取得に関心があるかを示します。ストリーミングアプリケーションは、Salesforce で変更が発生すると常にリアルタイムでイベントを受信します。
ストリーミング API を使用して独自のアプリケーションを作成する場合は、『ストリーミング API 開発者ガイド』を参照してください。このガイドには、CometD を使用する登録のコード例が含まれています。empApi
を使用して Lightning プラットフォームアプリケーションを作成するには、lightning-emp-api Web コンポーネントまたは lightning:empApi Aura コンポーネントに関するドキュメントを参照してください。
登録チャネル
登録チャネルは、1 つ以上のエンティティに対応する変更イベントのストリームです。チャネルに登録すると、レコードの作成、更新、削除、削除解除の各操作に関する変更イベント通知を受信できます。変更データキャプチャには標準チャネルが事前定義されていますが、独自のカスタムチャネルを作成できます。
標準チャネル
ChangeEvents 標準チャネルでは、選択した 1 つ以上のエンティティからの変更イベントが登録可能な 1 つのストリームにまとめられます。複数のエンティティからの変更イベントが想定される場合は、ChangeEvents 標準チャネルを使用します。ChangeEvents チャネルで変更イベントを受信するには、変更データキャプチャのエンティティを選択します。変更イベントのエンティティを選択する方法については、この後の単元で学習します。
1 つのエンティティのみに変更イベントが発生すると思われる場合は、単一エンティティチャネルを使用します。単一エンティティチャネルでは、1 つのカスタムオブジェクトまたは標準オブジェクトのみからの変更イベントに登録できます。
次の表は、変更の取得に関心のあるレコードに対応する登録チャネルを指定する方法を示します。
変更イベントの登録対象: |
チャネル |
例 |
---|---|---|
選択したエンティティの標準チャネル | ||
選択したすべてのオブジェクト |
/data/ChangeEvents |
N/A |
単一エンティティチャネル |
||
標準オブジェクト |
/data/<Standard_Object_Name>ChangeEvent |
取引先の場合、チャネルは /data/AccountChangeEvent |
カスタムオブジェクト |
/data/<Custom_Object_Name>__ChangeEvent |
Employee__c レコードの場合、チャネルは /data/Employee__ChangeEvent |
カスタムチャネル
複数の登録者が存在し、各登録者が異なるエンティティセットから変更イベントを受信する場合は、カスタムチャネルを作成します。また、特定のチャネルの変更イベントで強化された項目の送信を分離する場合も、カスタムチャネルを使用してイベント強化を設定します。カスタムチャネルは登録者ごとに変更イベントをグループ化して分離するため、登録者が必要な種別のイベントのみを受信します。エンティティのあるカスタムチャネルを作成すると、そのエンティティの変更データキャプチャが自動的に有効になります。カスタムチャネルは次の形式を使用します。
/data/YourChannelName__chn
たとえば、チャネル名が SalesEvents の場合、登録チャネルは次のようになります。
/data/SalesEvents__chn
詳細は、『Change Data Capture Developer Guide (変更データキャプチャ開発者ガイド)』の「Compose Streams of Change Data Capture Notifications with Custom Channels」 (カスタムチャネルを使用した変更データキャプチャ通知のストリームの作成) を参照してください。
変更イベントを受信する権限
変更データキャプチャでは、共有設定は無視され、Salesforce オブジェクトのすべてのレコードについて変更イベントが送信されます。チャネルで変更イベントを受信するためには、その変更イベントに関連付けられているエンティティに応じて登録ユーザーに 1 つ以上の権限が必要です。詳細は、『Change Data Capture Developer Guide (変更データキャプチャ開発者ガイド)』の「Required Permissions for Change Events (変更イベントに必要な権限)」を参照してください。
項目レベルセキュリティ
変更データキャプチャには、組織の項目レベルセキュリティ設定が反映されます。配信されるイベントには、登録ユーザーに参照権限がある項目のみが含まれます。
次の単元では、オープンソースのサンプルツールである EMP コネクタを使用してチャネルに登録し、イベントを受信する方法を学習します。