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

プラットフォームイベントの概要とそのユースケースを理解できたので、実際にプラットフォームイベントを定義してみましょう。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 クライアントまたは Pub/Sub API クライアントを使用してイベントバスから取得できます。保存されたイベントをすべて取得することも、イベントの再実行 ID をイベントの取得部分の基準として指定することもできます。Apex トリガーでは、サスペンド状態のトリガーを再開し、保持された最も古い未処理イベントを取得できます。このモジュールの後半で、Apex トリガー登録の管理方法について学習します。

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

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

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

アプリケーションが Salesforce プラットフォーム上にある場合、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() メソッドを使用してチェックできます。詳細は、「リソース」セクションを参照してください。 

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

外部アプリケーションは API を使用してプラットフォームイベントメッセージを公開します。イベントを公開するには、sObject を挿入するのと同じ方法でイベントレコードを作成します。SOAP API、REST API、Bulk API などの Salesforce API を使用して、プラットフォームイベントメッセージを作成できます。Apex の場合と同様に、イベントメッセージは非同期で公開されます。イベントを公開し、true の成功状況が取得されると、公開要求が Salesforce のキューに配置されます。

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

sObject REST エンドポイント:

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

プラットフォームイベントメッセージが作成された後、REST 応答は次の出力のようになります。

REST API コールを行うには、REST API ツールまたは HTTP クライアントアプリケーションを使用できます。たとえば、次の手順に従って Postman を使用できます。これまで Postman を使用したことがない場合は、「Quick Start: Connect Postman to Salesforce (クイックスタート: Postman を Salesforce に接続する)」プロジェクトにアクセスして、Salesforce APIs コレクションを設定、フォークしてください。Postman についての詳細は、「リソース」セクションを参照してください。

DE 組織を Postman に接続する。

1. Trailhead DE 組織にログインします。
2. Postman アプリケーションを開き、ワークスペースを選択し、Salesforce API コレクションのフォークに移動します。
3. [Authorization (認証)] タブで、最下部までスクロールして [Get New Access Token (新しいアクセストークンを取得)] をクリックします。
4. [許可] をクリックします。
5. [Manage Access Tokens (アクセストークンを管理)] ダイアログで、[instance URL (インスタンス URL)] をクリップボードにコピーします。
6. [Use Token (トークンを使用)] をクリックします。
7. [Variables (変数)] タブで [_endpoint] 行の [CURRENT VALUE] 列に、コピーしたインスタンス URL を貼り付け、[Save (保存)] をクリックします。ドキュメントペインを閉じないと、[Save (保存)] ボタンが表示されない場合があります。
8. 接続が機能していることをテストします。
   1. コレクションで、Salesforce APIs コレクションのフォークを選択します。
   2. [REST] を選択して、REST APIs を展開します。
   3. [GET Limits] を選択して、[Send (送信)] をクリックします。
   4. 応答ウィンドウの [Status (状況)] 項目に [Status: 200 OK] と表示されるはずです。表示されない場合は、ステップを繰り返して新しいトークンを取得します。

REST API コールを実行し、イベント通知を公開する。

1. Salesforce APIs コレクションのフォークで、[REST] をクリックします。
2. [sObject] をクリックして展開します。
3. [POST SObject Create] をクリックします。
4. [Params (パラメーター)] タブの [Path Variables (パス変数)] の下の [SOBJECT_API_NAME] に Cloud_News__e と入力します。
5. [Body (ボディ)] タブで、次の JSON ボディを貼り付けます。

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

6. [送信] をクリックします。イベントの投稿後に Salesforce が返す応答は次のようになります。

   {
     "id" : "e00xx0000000001AAA",
     "success" : true,
     "errors" : [
          {
               "statusCode": "OPERATION ENQUEUED",
               "message": "08ffc869-b9f8-4cff-a4ba-8dff9b3dd6cb",
               "fields": []
          }
      ]
   }

または、SOAP API で create() コールを使用するか、Bulk API で一括処理ジョブを使用してイベントを公開できます。Pub/Sub API を使用してイベントメッセージを公開することもできます。これは、イベントメッセージへの登録にも Pub/Sub API を使用している場合には便利です。詳細は Pub/Sub API のドキュメントを参照してください。

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

• ストリーミング API 開発者ガイド: メッセージの永続性
• プラットフォームイベント開発者ガイド: プラットフォームイベントの割り当て
• Apex 開発者ガイド: 実行ガバナと制限
• Salesforce ヘルプ: フロー
• Trailhead: Quick Start: Connect Postman to Salesforce (クイックスタート: Postman を Salesforce に接続する)
• 外部ヘルプ: Postman 学習センター
• Pub/Sub API ドキュメント
• REST API 開発者ガイド
• SOAP API 開発者ガイド
• Bulk API 開発者ガイド