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

学習の目的

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

プラットフォームイベントを定義する。
Apex でプラットフォームイベントメッセージを公開する方法を説明する。
Apex メソッドを使用してイベントを公開する。
プロセスまたはフローのクリック操作でイベントを公開する。
REST API を使用して sObject を挿入することでイベントを公開する。

メモ

日本語で受講されている方へChallenge は日本語の Trailhead Playground で開始し、かっこ内の翻訳を参照しながら進めていってください。Challenge での評価は英語データを対象に行われるため、英語の値のみをコピーして貼り付けるようにしてください。日本語の組織で Challenge が不合格だった場合は、(1) この手順に従って [Locale (地域)] を [United States (米国)] に切り替え、(2) [Language (言語)] を [English (英語)] に切り替えてから、(3) [Check Challenge (Challenge を確認)] ボタンをクリックしてみることをお勧めします。

翻訳版 Trailhead を活用する方法の詳細は、自分の言語の Trailhead バッジを参照してください。

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

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

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

[Setup (設定)] から、[Quick Find (クイック検索)] ボックスにPlatform Events (プラットフォームイベント) と入力し、[Platform Events (プラットフォームイベント)] を選択します。
[プラットフォームイベント] ページで、[新規プラットフォームイベント] をクリックします。
[Label (表示ラベル)] に、Cloud Newsと入力します。
[Plural Label (表示ラベル(複数形))] に、Cloud Newsと入力します。
[説明] に、Cloud news events deliver news at your fingertips (Cloud News イベントで簡単にニュースを配信) と入力します。
[Publish Behavior (公開動作)] は、デフォルトの [Publish Immediately (すぐに公開)] のままにします。

公開動作の詳細は、この単元の後半にある「プラットフォームイベントとトランザクション」を参照してください。

[Save (保存)] をクリックします。
[カスタム項目 & リレーション] 関連リストで、[New (新規)] をクリックします。
[テキスト] を選択し、[Next (次へ)] をクリックします。
[Field Label/Name (項目の表示ラベル/名前)] にLocation(場所) と入力します。
[Length (長さ)] に100と入力します。その他の項目はデフォルトのままにし、[説明] 項目は空白のままにします。[Save (保存)] をクリックします。
ステップ 7、8、9 を繰り返して次の 2 つの項目を追加します。

項目の表示ラベル/名前

データ型

緊急

チェックボックス

News Content

テキストエリア (ロング)

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

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

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

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

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

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

Salesforce はイベントメッセージを一時的に保持していますが、SOQL や SOSL を使用したクエリはできません。同様に、レポート、リストビュー、検索のユーザーインターフェースでイベントメッセージを使用することはできません。

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

API 参照名サフィックス

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

プラットフォームイベントの公開動作とトランザクション

定義したプラットフォームイベントに対して公開動作を選択できます。公開動作は、イベントが公開されるタイミング (公開コールの直後か、トランザクションが正常に完了した後のどちらか) を指定します。

すぐに公開の動作

イベントの公開がトランザクションデータに結び付けられていない場合は、[Publish Immediately (すぐに公開)] を選択します。これはデフォルトであり、ほとんどの実装ではこのオプションをお勧めします。このオプションは、トランザクションが成功したかどうかに関係なく、公開コールが実行された際にイベントメッセージを公開します。このオプションでは、データがコミットされる前に、登録者がイベントメッセージを受信できる場合があります。

たとえば、公開者と登録者が独立していて、公開者がコミットするデータに登録者が依存していない場合もこのオプションを選択します。あるいは、記録目的で使用されるイベントでも [Publish Immediately (すぐに公開)] が適しています。

コミット後に公開の動作

[Publish After Commit (コミット後に公開)] は、登録者がイベントメッセージを受信する際にコミット済みのトランザクションデータが必要な場合にのみ選択してください。このオプションでは、トランザクションが正常にコミットされた場合にのみイベントメッセージが公開され、トランザクションが失敗した場合は公開されません。

[Publish After Commit (コミット後に公開)] を使用する例としては、あるプロセスがイベントメッセージを公開してタスクレコードを作成した後に、そのイベントに登録している 2 番目のプロセスが起動してタスクレコードを探す場合などがあります。

イベントの公開

アプリケーションが Salesforce Platform 上にある場合、Apex メソッドを使用するか、Flow Builder 宣言型ツールを使用してイベントを公開できます。アプリケーションが外部アプリケーションの場合、Salesforce API (Pub/Sub API や、REST API などのデータ API を含む) を使用してイベントを公開できます。

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

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

次の例では、種別が Cloud_News__e のイベントを 1 つ作成して公開し、公開が成功したか、エラーが発生したかをチェックします。EventBus.publish() メソッドは、公開の結果が含まれる Database.SaveResult オブジェクトを返します。isSuccess() が true を返したら、公開要求が Salesforce のキューに配置され、イベントメッセージが非同期で公開されます。isSuccess() が false を返したら、イベント公開操作でエラーが発生し、Database.Error オブジェクトでエラーが返されます。このメソッドは、失敗した公開操作による例外を発生させません。

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

クイックアクセスメニュー () から、[開発者コンソール] をクリックします。
[Debug (デバッグ)] | [Open Execute Anonymous Window (実行匿名ウィンドウを開く)] をクリックします。

新しいウィンドウで、コンテンツをコードスニペットに置き換えてから [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 はキューに登録されたイベントを EventBus.publish() コールから非同期に公開し、特定の保持期間はイベントバスに保持します。ほとんどの場合、最終的には公開は成功するため、キューに登録されたイベントの公開について心配する必要はありません。まれに、内部システムエラーが発生して非同期公開が失敗することがあります。最終的なイベント公開結果を確認するには、Apex 公開コールバックを使用します。詳細は、『プラットフォームイベント開発者ガイド』の「Apex 公開コールバックを使用した非同期プラットフォームイベント公開の結果の取得」を参照してください。

Salesforce Platform では、組織で定義できるイベント数と 1 時間の間に公開できるイベント数の割り当てが行われます。[コミット後に公開] 動作を設定したイベントの場合、各メソッドの実行は、Apex DML ステートメント制限に対して 1 つの DML ステートメントとみなされます。

使用制限は、Apex Limits.getDMLStatements() メソッドを使用してチェックできます。[すぐに公開] 動作を設定したイベントの場合、各メソッドの実行は、EventBus.publish() コール 150 件という個別のイベント公開制限に含まれます。使用制限は、Apex Limits.getPublishImmediateDML() メソッドを使用してチェックできます。詳細は、「リソース」セクションを参照してください。

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

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

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

外部アプリケーションは API を使用してプラットフォームイベントメッセージを公開します。Pub/Sub API を使用するか、SOAP API、REST API、Bulk API などのデータ API を使用してイベントを公開できます。

データ API を使用する場合は、sObject を挿入するのと同じ方法でイベントを公開します。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 に接続する。

Trailhead DE 組織にログインします。
Postman アプリケーションを開き、ワークスペースを選択し、Salesforce API コレクションのフォークに移動します。
[Authorization (認証)] タブで、最下部までスクロールして [Get New Access Token (新しいアクセストークンを取得)] をクリックします。
[許可] をクリックします。
[Manage Access Tokens (アクセストークンを管理)] ダイアログで、[instance URL (インスタンス URL)] をクリップボードにコピーします。
[Use Token (トークンを使用)] をクリックします。
[Variables (変数)] タブで [_endpoint] 行の [CURRENT VALUE] 列に、コピーしたインスタンス URL を貼り付け、[Save (保存)] をクリックします。ドキュメントペインを閉じないと、[Save (保存)] ボタンが表示されない場合があります。
接続が機能していることをテストします。

コレクションで、Salesforce APIs コレクションのフォークを選択します。
[REST] を選択して、REST APIs を展開します。
[GET Limits] を選択して、[Send (送信)] をクリックします。
応答ウィンドウの [Status (状況)] 項目に [Status: 200 OK] と表示されるはずです。表示されない場合は、ステップを繰り返して新しいトークンを取得します。

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

Salesforce APIs コレクションのフォークで、[REST] をクリックします。
[sObject] をクリックして展開します。
[POST SObject Create] をクリックします。
[Params (パラメーター)] タブの [Path Variables (パス変数)] の下の SOBJECT_API_NAME に Cloud_News__e と入力します。

[Body (ボディ)] タブで、次の JSON ボディを貼り付けます。

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

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

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

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

リソース

予想時間

トピック

ヘルプをお探しですか?

Salesforce Platform のリソース

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

学習の目的

メモ

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

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

API 参照名サフィックス

プラットフォームイベントの公開動作とトランザクション

すぐに公開の動作

コミット後に公開の動作

イベントの公開

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

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

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

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