進行状況の追跡を始めよう
Trailhead のホーム
Trailhead のホーム

プラットフォームイベントの定義および公開

学習の目的

この単元を完了すると、次のことができるようになります。
  • プラットフォームイベントを定義する。
  • プラットフォームイベントメッセージの公開方法を説明する。
  • Apex メソッドを使用してイベントを公開する。
  • プロセスまたはフローのクリク操作でイベントを公開する。
  • REST API を使用して sObject を挿入することでイベントを公開する。

プラットフォームイベントの定義および公開

プラットフォームイベントの概要とその使用事例を理解できたので、実際にプラットフォームイベントを定義してみましょう。Cloud News 通信社を覚えていますか? ニュースイベントのデータを保持するプラットフォームイベント定義を作成しましょう。

次の手順で Cloud News という名前のプラットフォームイベントを定義します。

  1. [設定] から、[クイック検索] ボックスに「プラットフォームイベント」と入力し、[プラットフォームイベント] を選択します。
  2. [プラットフォームイベント] ページで、[新規プラットフォームイベント] をクリックします。
  3. [表示ラベル] に、「Cloud News」と入力します。
  4. [表示ラベル(複数形)] に、「Cloud News」と入力します。
  5. [説明] に、「Cloud news events deliver news at your fingertips (Cloud News イベントで簡単にニュースを配信)」と入力します。
  6. [公開動作] は、デフォルトの [コミット後に公開] のままにします。
  7. [保存] をクリックします。
  8. [カスタム項目 & リレーション] 関連リストで、[新規] をクリックします。
  9. [テキスト] を選択し、[次へ] をクリックします。
  10. [項目の表示ラベル] と [項目名] に「Location (場所)」と入力します。
  11. [長さ] に「100」と入力します。その他の項目はデフォルトのままにし、[説明] 項目は空白のままにします。[保存] をクリックします。
  12. ステップ 7、8、9 を繰り返して次の 2 つの項目を追加します。
    項目の表示ラベル/名前 データ型
    Urgent チェックボックス
    News Content テキストエリア (ロング)

定義した Cloud News イベントでは、テキスト項目やチェックボックスなど、さまざまなデータ型の項目を作成しました。プラットフォームイベントでサポートされるのは次のデータ型です。

  • チェックボックス
  • 日付
  • 日付/時間
  • 数値
  • テキスト
  • テキストエリア (ロング)

イベント保持と ReplayId システム項目

Salesforce ではイベントを 24 時間保存します。保存されたイベントは API CometD クライアントで取得できますが、Apex では取得できません。保存されたイベントをすべて取得することも、イベントの再実行 ID をイベントの取得部分の基準として指定することもできます。

Salesforce はイベントレコードを一時的に保持していますが、SOQL や SOSL を使用したクエリはできません。同様に、レポート、リストビュー、検索のユーザインターフェースでイベントレコードを使用することはできません。過去のイベントを取得するには、CometD で登録するか、ReplayId オプションを使用する必要があります。イベントへの登録方法は、次の単元で説明します。

各イベントメッセージには、ReplayId 項目に含まれる不透明な ID が割り当てられます。ReplayId 項目値は、イベントが登録者に配信されるときにシステムによって入力され、イベントストリーム内のイベントの位置を参照します。連続するイベントの再実行 ID 値が連番になるという保証はありません。たとえば、ID 999 のイベントの次のイベントの ID が 1,025 になることもあり得ます。登録者は、再実行 ID 値を保存し、その ID を再登録で使用して保持期間内のイベントを取得することができます。たとえば、登録者は接続障害が発生した後に、欠落イベントを取得できます。登録者が、保存された再実行 ID に基づいて新しい再実行 ID を計算し、ストリーム内の他のイベントを参照することはできません。

API 参照名サフィックス

プラットフォームイベントを作成するときに、システムにより __e サフィックスが付加されてイベントの API 参照名が作成されます。たとえば、Cloud News イベントの場合、API 参照名は Cloud_News__e になります。Apex、REST API、Enterprise API など、プログラムでイベントを参照する場合は常に API 参照名を使用します。

プラットフォームイベントとトランザクション

[コミット後に公開] 公開動作を定義したプラットフォームイベントはトランザクションに左右され、ロールバックできますが、[すぐに公開] 公開動作を定義したプラットフォームイベントはトランザクションに左右されず、ロールバックできません。動作には次の違いがあります。

コミット後に公開の動作

[コミット後に公開] 動作を定義したプラットフォームイベントは、トランザクションが正常にコミットされた後にのみ公開されます。公開トランザクションがコミットするデータに登録者が依存している場合は、イベントにこのオプションを定義します。たとえば、あるプロセスがイベントメッセージを公開し、ToDo レコードを作成するとします。そのイベントに登録している 2 つ目のプロセスは起動したときに ToDo レコードがあることを想定しています。この動作を選択する別の理由として、トランザクションが失敗したときにイベントメッセージを公開したくない場合があります。

すぐに公開の動作

[すぐに公開] 動作を定義したプラットフォームイベントは、公開コールが実行されたときに公開されます。トランザクションが成功したかどうかに関係なくイベントメッセージが公開されるようにする場合は、このオプションを選択します。また、公開者と登録者が独立していて、公開者がコミットするデータに登録者が依存していない場合もこのオプションを選択します。たとえば、記録目的で使用されるイベントにはすぐに公開する動作が適しています。このオプションを選択した場合、データが公開者のトランザクションによってコミットされる前に登録者がイベントメッセージを受信することがあります。

イベントの公開

アプリケーションが Salesforce Platform 上にある場合、Apex メソッドを使用するか、プロセスビルダーや Flow Builder などの宣言型ツールを使用してイベントを公開できます。アプリケーションが外部アプリケーションの場合、Salesforce API を使用してイベントを公開できます。

Apex を使用したイベントメッセージの公開

イベントメッセージを公開するには、イベントのインスタンスを作成して EventBus.publish() メソッドに渡します。

次の例では、種別が Cloud_News__e のイベントを 1 つ作成して公開し、公開が成功したか、エラーが発生したかをチェックします。EventBus.publish() メソッドは、公開の結果が含まれる Database.SaveResult オブジェクトを返します。isSuccess()true を返したら、イベントは Salesforce イベントバスに公開されています。それ以外の場合、イベントでは Database.Error オブジェクトで返されたエラーが発生しています。

開発者コンソールで Apex コードスニペットを実行できます。

  1. クイックアクセスメニュー (クイックアクセスメニュー) から、[開発者コンソール] を選択します。
  2. [Debug (デバッグ)] | [Open Execute Anonymous Window (実行匿名ウィンドウを開く)] をクリックします。
  3. 新しいウィンドウで、コンテンツをコードスニペットに置き換えてから [Execute (実行)] をクリックします。
    // Create an instance of the event and store it in the newsEvent variable
    Cloud_News__e newsEvent = new Cloud_News__e(
               Location__c='Mountain City', 
               Urgent__c=true, 
               News_Content__c='Lake Road is closed due to mudslides.');
    
    // Call method to publish events
    Database.SaveResult sr = EventBus.publish(newsEvent);
    
    // Inspect publishing result 
    if (sr.isSuccess()) {
        System.debug('Successfully published event.');
    } else {
        for(Database.Error err : sr.getErrors()) {
            System.debug('Error returned: ' +
                         err.getStatusCode() +
                         ' - ' +
                         err.getMessage());
        }
    }

同じコールで複数のイベントを公開するには、イベントのリストにイベントを追加し、リストを EventBus.publish() メソッドに渡します。このメソッドの出力は、Database.SaveResult オブジェクトの配列です (公開されたイベントごとにオブジェクトが 1 つずつ)。EventBus.publish() は、渡されたイベントを、エラーで公開できないものを除いて部分的に公開できます。EventBus.publish() メソッドは、失敗した公開操作による例外を発生させません。これは、Apex の Database.insert() メソッドが部分的な完了オプションを指定してコールされたときの動作に似ています。

// List to hold event objects to be published.
List<Cloud_News__e> newsEventList = new List<Cloud_News__e>();
// Create event objects.
Cloud_News__e newsEvent1 = new Cloud_News__e(
           Location__c='Mountain City', 
           Urgent__c=true, 
           News_Content__c='Lake Road is closed due to mudslides.');
Cloud_News__e newsEvent2 = new Cloud_News__e(
           Location__c='Mountain City', 
           Urgent__c=false, 
           News_Content__c='Small incident on Goat Lane causing traffic.');
// Add event objects to the list.
newsEventList.add(newsEvent1);
newsEventList.add(newsEvent2);

// Call method to publish events.
List<Database.SaveResult> results = EventBus.publish(newsEventList);

// Inspect publishing result for each event
for (Database.SaveResult sr : results) {
    if (sr.isSuccess()) {
        System.debug('Successfully published event.');
    } else {
        for(Database.Error err : sr.getErrors()) {
            System.debug('Error returned: ' +
                        err.getStatusCode() +
                        ' - ' +
                        err.getMessage());
        }
    }       
}
メモ

メモ

Salesforce プラットフォームでは、組織で定義できるイベント数と 1 時間の間に公開できるイベントレコード数の割り当てが行われます。また、イベント公開は DML 挿入操作と同じであるため、DML 制限とその他の Apex ガバナ制限も適用されます。詳細は、「リソース」セクションを参照してください。

クリック操作を使用したイベントメッセージの公開

コーディングなしでイベントメッセージを公開するには、プロセスまたはフローでレコード作成機能を使用します。

次のプロセスビルダーのスクリーンショットでは、Cloud News イベントメッセージを公開する [レコードを作成] アクションのサンプルが表示されています。基本的に、[レコードタイプ] を公開するプラットフォームイベント (Cloud News) に設定し、そのイベントの値を設定します。

プロセスビルダーの [レコードを作成] アクションが Cloud News レコードタイプに設定されています。Cloud News イベントの各項目は入力されています。

同様に、プラットフォームイベントメッセージをフローで公開できます。プラットフォームイベントのインスタンス (Cloud_News__e) を作成するように [レコード作成] 要素を設定し、イベントの値を設定します。Urgent__c など Boolean 項目の値を設定するには、{!$GlobalConstant.True} を使用します。

Salesforce API を使用したイベントメッセージの公開

外部アプリケーションは API を使用してプラットフォームイベントメッセージを公開します。イベントを公開するには、sObject を挿入するのと同じ方法でイベントレコードを作成します。SOAP API、REST API、Bulk API などの Salesforce API を使用して、プラットフォームイベントレコードを作成できます。

たとえば、Cloud News イベントの場合、Cloud_News__e レコードを挿入してイベント通知を公開できます。次の例では REST API で種別 Cloud_News__e のイベントを 1 つ作成します。

sObject REST エンドポイント:

/services/data/v40.0/sobjects/Cloud_News__e/

POST 要求のリクエストボディ:

{
   "Location__c" : "Mountain City",
   "Urgent__c" : true,
   "News_Content__c" : "Lake Road is closed due to mudslides."
}

プラットフォームイベントレコードが作成された後、REST 応答は次の出力のようになります。ヘッダーは簡略化のために削除されています。

HTTP/1.1 201 Created 

{   
   "id" : "e00xx000000000B",
   "success" : true,
   "errors" : [ ],
   "warnings" : [ ] 
}

REST API コールを行うには、REST API ツールまたは HTTP クライアントアプリケーションを使用できます。たとえば、次の手順に従ってワークベンチを使用できます。

  1. Trailhead DE 組織にログインします。
  2. 新しいタブを開き、https://workbench.developerforce.com/login.php のワークベンチに移動します。
  3. [Environment (環境)] で [Production (本番)] を選択します。
  4. [API Version (API バージョン)] で、使用可能な最大の番号を選択します。
  5. [I agree to the terms of service (サービス契約条件に同意します)] を選択します。
  6. [Salesforce でログイン] をクリックします。
  7. 次の画面で、[Allow (許可)] をクリックします。
  8. 上部のメニューで、[utilities (ユーティリティ)] | [REST Explorer] を選択します。
  9. [POST (投稿)] をクリックします。
  10. URI を次の値に置き換えます。
    /services/data/v40.0/sobjects/Cloud_News__e
  11. リクエストボディには、次の本文を JSON 形式で追加します。
    {
       "Location__c" : "Mountain City",
       "Urgent__c" : true,
       "News_Content__c" : "Lake Road is closed due to mudslides."
    }
  12. [Execute (実行)] をクリックします。

    イベントの投稿後に Salesforce が返す応答は次のようになります。

    {
      "id" : "e00xx0000000001AAA",
      "success" : true,
      "errors" : [ ],
      "warnings" : [ ]
    }
    

または、SOAP API で create() コールを使用するか、Bulk API で一括処理ジョブを使用してイベントを公開できます。

イベントの定義および公開方法を確認できたので、次は登録方法を学習しましょう。