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

プラットフォームイベントの概要とその使用事例を理解できたので、実際にプラットフォームイベントを定義してみましょう。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 つの項目を追加します。

    項目の表示ラベル/名前	データ型
    緊急	チェックボックス
    News Content	テキストエリア (ロング)

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

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

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

Salesforce では、大規模プラットフォームイベントが 72 時間保存されます。Spring ’19 以前に定義された標準規模のイベントは 24 時間保存されます。 

メモ

新しく定義されたイベントは、デフォルトで大規模になります。標準規模イベントは、大規模イベントの前身なので、定義できなくなりました。

保存されたイベントは API CometD クライアントを使用してイベントバスから取得できます。保存されたイベントをすべて取得することも、イベントの再実行 ID をイベントの取得部分の基準として指定することもできます。Apex トリガでは、サスペンド状態のトリガを再開し、保持された最も古い未処理イベントを取得できます。このモジュールの後半で、Apex トリガ登録の管理方法について学習します。

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

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

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

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

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

次の例では、種別が Cloud_News__e のイベントを 1 つ作成して公開し、公開が成功したか、エラーが発生したかをチェックします。EventBus.publish() メソッドは、公開の結果が含まれる Database.SaveResult オブジェクトを返します。isSuccess() が true を返したら、この大規模プラットフォームイベントの公開要求が Salesforce のキューに配置されます。イベントメッセージはすぐに公開されないことがあります。isSuccess() が false を返したら、イベント公開操作でエラーが発生しました。このエラーは、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 時間の間に公開できるイベント数の割り当てが行われます。[コミット後に公開] 動作を設定したイベントの場合、各メソッドの実行は、Apex DML ステートメント制限に対して 1 つの DML ステートメントとしてカウントされます。使用制限は、Apex Limits.getDMLStatements() メソッドを使用してチェックできます。[すぐに公開] 動作を設定したイベントの場合、各メソッドの実行は、EventBus.publish() コール 150 件という個別のイベント公開制限に対してカウントされます。使用制限は、Apex Limits.getPublishImmediateDML() メソッドを使用してチェックできます。詳細は、「リソース」セクションを参照してください。 

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

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

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

外部アプリケーションは 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/v45.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. [Login with Salesforce (Salesforce でログイン)] をクリックします。
7. 次の画面で、[Allow (許可)] をクリックします。
8. 上部のメニューで、[utilities (ユーティリティ)] | [REST Explorer] を選択します。
9. [POST (投稿)] をクリックします。
10. URI を次の値に置き換えます。

    /services/data/v45.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 で一括処理ジョブを使用してイベントを公開できます。

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

• ストリーミング API 開発者ガイド: メッセージの永続性
• Platform Events Developer Guide (プラットフォームイベント開発者ガイド): Platform Event Limits (プラットフォームイベントの割り当て)
• Apex 開発者ガイド: 実行ガバナと制限
• Salesforce ヘルプ: Lightning プロセスビルダー
• Salesforce ヘルプ: フロー
• REST API 開発者ガイド
• SOAP API 開発者ガイド
• Bulk API 開発者ガイド