変更データキャプチャの特性

学習の目的

この単元を完了すると、次のことができるようになります。

変更データキャプチャで使用できるオブジェクトを把握する。
変更イベントヘッダーで返される項目を挙げ、操作ごとに本文に含まれる項目について説明する。
変更イベントチャネル名を作成する。
変更イベントへの登録に必要な権限を挙げる。

オブジェクトのサポート

変更データキャプチャでは、Salesforce 組織で定義されたすべてのカスタムオブジェクト、および標準オブジェクトのサブセットについて変更イベントを生成できます。よく使用される標準オブジェクト (Account、Contact、Lead、User、Order、OrderItem、Product2 など) のほとんどで変更イベントがサポートされます。変更イベントをサポートするオブジェクトのリストについては、『Salesforce および Lightning プラットフォームのオブジェクトリファレンス』の「StandardObjectNameChangeEvent」を参照してください。

レコード変更の通知を受信するには、[設定] の [変更データキャプチャ] ページで関心のあるカスタムオブジェクトとサポート対象の標準オブジェクトを選択します。オブジェクトの設定手順については、このモジュールの後半で説明します。

変更イベントの例

Robert を覚えていますか? 彼がコンサルティングしているお客様は、従業員データを管理するカスタム HR アプリケーションの一部である、Employee__c というカスタムオブジェクトを定義しています。Salesforce の従業員データを外部の HR システムと同期するため、Robert は新しい従業員レコードと変更された従業員レコードの変更イベントを受信して統合するアプリケーションを作成しました。

このアプリケーションが Pub/Sub API を使用して受信するイベントメッセージの例を見てみましょう。Salesforce でユーザーが作成した新規従業員レコードのデータが含まれています。変更イベントのペイロードの ChangeEventHeader には、変更、レコード項目、システム項目に関する情報を格納するヘッダー項目が含まれています。この変更イベントメッセージの例には、CreatedDate のようなシステム項目に加え、従業員の名、姓、在職期間が含まれています。Tenure 項目は、設定されなかったため null です。Pub/Sub API を使用して受信される変更イベントには、null 項目を含むすべてのレコード項目が含まれています。ChangeEventHeader の entityName 項目には Salesforce オブジェクトの名前が含まれ、changeType 項目はこの変更がレコードの作成であったことを示します。

{
  "ChangeEventHeader": {
    "entityName": "Employee__c",
    "recordIds": [
      "a00aj000006yrE7AAI"
    ],
    "changeType": "CREATE",
    "changeOrigin": "com/salesforce/api/soap/60.0;client=SfdcInternalAPI/",
    "transactionKey": "000033a1-751e-415e-47bc-60f581b7e049",
    "sequenceNumber": 1,
    "commitTimestamp": 1712601294000,
    "commitNumber": 1712601294485905400,
    "commitUser": "005aj0000032E1yAAE",
    "nulledFields": [],
    "diffFields": [],
    "changedFields": []
  },
  "OwnerId": "005aj0000032E1yAAE",
  "Name": "e-100",
  "CreatedDate": 1712601294000,
  "CreatedById": "005aj0000032E1yAAE",
  "LastModifiedDate": 1712601294000,
  "LastModifiedById": "005aj0000032E1yAAE",
  "Last_Name__c": "Smith",
  "First_Name__c": "Patricia",
  "Tenure__c": null
}

ChangeEventHeader 項目には、変更に関する情報を持つヘッダー項目が含まれます。次に挙げるヘッダー項目には注意が必要です。

entityName

この項目には、このレコード変更の標準オブジェクトまたはカスタムオブジェクトの名前が含まれます。この例では Employee__c です。

changeType

この項目には、変更を発生させた操作が含まれます。一般的な変更イベントの場合、この項目には次のいずれかの値が含まれます。

CREATE
UPDATE
DELETE
UNDELETE

この例はレコード作成に関する変更イベントであるため、値は CREATE です。

changedFields

この項目を使用して、更新操作で変更された項目を知ることができます。この項目は、他の操作では空です。変更イベントの例は新規レコード用であるため、この項目は空です。1 つ以上の項目を更新すると、項目名が LastModifiedDate と共に changedFields に追加されます。たとえば、First_Name__c が変更された場合、この項目値は ["LastModifiedDate", "First_Name__c"] になります。

diffFields

Pub/Sub API と Apex トリガーで受信されるイベントでのみ使用できます。テキスト値が大きいために統合された差分として値が送信される項目の名前が含まれます。

nulledFields

Pub/Sub API と Apex トリガーで受信されるイベントでのみ使用できます。更新操作で値が null に変更された項目の名前が含まれます。項目が変更されていないのではなく、更新で null に変更されたかどうかを特定するには、この項目を使用します。

changeOrigin

この項目を使用して変更の原因を特定します。インテグレーションアプリケーションが同じオブジェクトのレコードの変更に応じてレコードを変更する場合、変更が永遠に続くことがあります。こうした循環を回避するために、この項目を使用してアプリケーションが変更を開始したのかどうかを検出し、その場合には変更を再び処理せず、変更の執拗な繰り返しが生じないようにします。この項目には、変更を開始した Salesforce API と API クライアント ID が含まれます (クライアントで設定された場合)。変更が API アプリケーションによって行われた場合または Lightning Experience から実行された場合は、この項目に入力されます。それ以外は空になります。

たとえば、clientIDGetCloudy を使用するアプリケーションが SOAP API を通じて従業員レコードを作成した場合、changeOrigin 項目の値は com/salesforce/api/soap/60.0;client=GetCloudy になります。この例では、値は com/salesforce/api/soap/60.0;client=SfdcInternalAPI/ ですから、レコードの変更が Salesforce ユーザーインターフェースを通じて行われたことを意味します。

トランザクション関連のヘッダー項目

次のヘッダー項目には、現在の変更のトランザクションに関する情報が含まれます。

transactionKey
sequenceNumber

このトランザクション項目を使用して、組織のデータの正確なレプリカを別のシステムで維持します。transactionKey 項目は、変更が含まれるトランザクションを一意に識別します。sequenceNumber 項目は、トランザクション内の変更の順序を識別します。この連番は、複数のステップが含まれる操作で便利です。たとえば、リードの取引開始や、after insert Apex トリガーでの関連レコードの作成などです。トランザクションに関与するすべてのオブジェクトが変更データキャプチャで有効になっていない場合は、連番が飛んでいます。1 つのトランザクションのすべての変更をシステム内の 1 回のコミットで複製することをお勧めします。

トランザクションベースの複製プロセスを使用しないことを選択した場合、登録が停止すると複製されたデータが完全ではなくなる可能性があります。たとえば、登録が 1 つのトランザクションのイベントストリームの途中で停止した場合、トランザクションの変更の一部のみがシステムで複製されます。

イベントメッセージの本文に含まれる項目

クライアントが受信するイベントメッセージに Salesforce が含める項目は、実行される操作とサブスクライバー種別に応じて異なります。たとえば、Apex トリガーまたは Pub/Sub API クライアントの場合、イベントメッセージには空であるか否かにかかわらずすべてのレコード項目とシステム項目が含まれます。詳細は、『Change Data Capture Developer Guide (変更データキャプチャ開発者ガイド)』の「Change Event Body Fields (変更イベント本文の項目)」を参照してください。

マージされた変更イベント

1 秒以内に同じオブジェクト種別の複数のレコードで同じ変更が行われた場合は、効率化するために 1 つのトランザクションの複数の変更イベントが 1 つのイベントにマージされることがあります。変更イベントがマージされると、Salesforce は影響を受けるすべてのレコードに対する 1 つの変更イベントと recordIds 項目を送信します。この項目には、同じ変更が行われたすべてのレコードの ID が含まれます。詳細は、『Change Data Capture Developer Guide (変更データキャプチャ開発者ガイド)』の「Merged Change Events (マージされた変更イベント)」を参照してください。

追加項目による変更イベントの強化

Pub/Sub API 登録者に配信される変更イベントを強化するための項目を選択します。選択された項目は、変更がなくても変更イベントメッセージに含まれます。たとえば、アプリケーションに外部システムのレコードを照合するための外部 ID 項目が必要な場合に強化を使用します。または、変更レコードに関する重要情報を提供する項目を常に含めます。詳細は、『Change Data Capture Developer Guide (変更データキャプチャ開発者ガイド)』の「Enrich Change Events with Extra Fields (追加項目による変更イベントの強化)」と Trailhead の「カスタムチャネルを作成して、変更イベントを強化する」プロジェクトを参照してください。

その他の種別のイベント: ギャップイベントとオーバーフローイベント

その他の種別の変更イベントは、特別な状況に対処するために生成されます。Salesforce では、変更イベントが生成できない場合や、登録者にエラーを通知するためにギャップイベントが生成されます。オーバーフローイベントは、変更の量が多い場合に生成されます。ギャップイベントとオーバーフローイベントにはレコードデータは含まれません。ギャップイベントにはレコード ID が含まれているため、レコードデータを取得できます。詳細は、『Change Data Capture Developer Guide (変更データキャプチャ開発者ガイド)』の「Gap Events (ギャップイベント)」、「Overflow Events (オーバーフローイベント)」、「High-Level Replication Steps (複製手順の概要)」を参照してください。

イベントチャネルへの登録

変更イベントメッセージがどのようなものかがわかったので、次は変更イベントの受信方法を確認しましょう。このモジュールでは、Pub/Sub API と Apex トリガーを使用して変更イベントに登録します。Salesforce では、変更イベントチャネルへの登録に複数の方法が用意されています。

Salesforce 外部のアプリケーションには、Pub/Sub API を使用できます。Pub/Sub API では、gRPC API と HTTP/2 に基づいて、バイナリイベントメッセージを効率的に公開および配信できます。

Lightning プラットフォームでデータの変更を非同期に処理するには、変更イベントの Apex トリガーを記述します。変更イベントの Apex トリガーについては、このモジュールの後半で詳しく説明します。

Lightning プラットフォーム上で実行されるアプリケーションで Salesforce データの変更に関するインスタント通知を受信するには、empApi Lightning コンポーネントを使用できます。

チャネルに登録することで、アプリケーションがどのイベントの取得に関心があるかを示します。ストリーミングアプリケーションは、Salesforce で変更が発生すると常にリアルタイムでイベントを受信します。

Pub/Sub API を使用して独自のアプリケーションを作成する場合は、『Pub/Sub API Developer Guide (Pub/Sub API 開発者ガイド)』を参照してください。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 コネクタを使用してチャネルに登録し、イベントを受信する方法を学習します。

予想時間

トピック

ヘルプをお探しですか?

Salesforce Platform のリソース