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

学習の目的

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

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

オブジェクトのサポート

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

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

変更イベントの例

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

このアプリケーションが受信するイベントメッセージの例を見てみましょう。Salesforce でユーザが作成した新規従業員レコードのデータが含まれています。changeTypeentityName の項目値に注目してください。 

{
  "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 から実行された場合は、この項目に入力されます。それ以外は空になります。

たとえば、clientIDGetCloudy のアプリケーションが 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 日以内のイベントを再生するために使用できます。このモジュールでは、イベントの再生については説明しません。詳細は、「リソース」セクションを参照してください。

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

CometD クライアントが受信するイベントメッセージに Salesforce が含める項目は、実行される操作に応じて異なります。(CometD は、long polling によってイベントをリッスンし、プッシュテクノロジをシミュレートするメッセージングライブラリです。)

作成

新規レコードの場合、イベントメッセージの本文には空ではない項目すべてと、CreatedDate 項目や OwnerId 項目などのシステム項目が含まれます。

更新

更新されたレコードの場合、本文には変更された項目のみが含まれます。空の項目は、項目が更新されて値が空 (null) になった場合にのみ含まれます。また、LastModifiedDate システム項目も含まれます。LastModifiedById 項目は、変更された場合にのみ (レコードを変更したユーザが、そのレコードを前回保存したユーザと異なる場合) 本文に含まれます。

削除

削除されたレコードの場合、本文には項目もシステム項目も含まれません。

復元

復元されたレコードの場合、本文には、システム項目に加え、元のレコードから空ではない項目がすべて含まれます。 

たとえば、ユーザが Employee__c レコードを作成して一部の項目のみ (LastName__c と Name) を入力した場合、対応するイベントメッセージの本文には、LastName__c 項目、Name 項目、およびシステム項目が含まれます。メッセージに空の項目は含まれません。

メモ

メモ

また、Apex トリガでイベントチャネルに登録することもできます (このモジュールで後述)。Apex トリガで受信したイベントメッセージには、空の項目を含むすべての項目が記載されます。この理由は、他の Apex 型と同様、変更イベントメッセージの項目は静的に定義されるためです。

イベントメッセージ内の項目の順序

JSON イベントメッセージ内の項目の順序は保証されません。順序は、変更イベントのベースとなった基盤の Apache Avro スキーマ (データ逐次化システム) に従います。イベントが JSON 形式に展開されるとき、イベントの受信に使用されたクライアントに応じて、項目の順序がスキーマとは一致しないことがあります。

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

変更イベントメッセージがどのようなものかがわかったので、次は変更イベントの受信方法を確認しましょう。Salesforce では、変更イベントチャネルへの登録に複数の方法が用意されています。Salesforce 以外のアプリケーションの場合、ストリーミング API、またはプッシュテクノロジをシミュレートするオープンソースライブラリの CometD に基づくツールやライブラリを使用できます。ストリーミング API は、CometD に基づく登録メカニズムを提供します。 

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

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

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

ストリーミング API を使用して独自のアプリケーションを作成する場合は、『ストリーミング API 開発者ガイド』を参照してください。このガイドには、CometD を使用する登録のコード例が含まれています。lightning:empApi を使用して Lightning プラットフォームアプリケーションを作成するには、lightning:empApi Lightning コンポーネントに関するドキュメントを参照してください。   

登録チャネル

登録チャネルは、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 コネクタを使用してチャネルに登録し、イベントを受信する方法を学習します。

リソース