ストリーミング API の使用

船長となったあなたは外洋航海中、予測される危険や他の船舶、そして宝に溢れた島々を見逃さないようにしたいと考えています。船員の 1 人を見張り台に登らせ、異変を積極的に見つけ出すよう指示します。では開発者の立場に戻ります。あなたは開発者で、取引先が更新されていないかどうかを定期的に確認する REST または SOAP API を使用して、アプリケーションを記述しているとします。取引先データを絶えず要求して、古いデータと一致しているかどうかを確認することは、異変を積極的に見つけ出すことに通じる手法です。

さて、あなたは再び船上にいるとします。ただし、今回は最新のレーダー表示装置を利用できるものとします。気になる物体が近づくと表示装置から信号音が発せられるため、見張り台に船員を立たせておく必要がありません。

ストリーミング API は、このレーダーの役割を果たします。API でイベントを定義し、イベントが発生したときにクライアントアプリケーションに通知を転送 (プッシュ) できます。データの変更を積極的に見つけ出す必要がありません。Salesforce に絶えずポーリングして、不要な API 要求を行う必要がありません。

Salesforce の外部にあるシステムにビジネスデータが保存されている場合は特に Salesforce のデータ変更の追跡が役立ちます。ストリーミング API を使用すれば、PushTopic イベントと変更データキャプチャイベントを使用して、外部ソースを Salesforce データと常に同期させておくことができます。また、ストリーミング API により、Salesforce でのデータの変更に応じて、外部システムでビジネスプロセスを処理できます。たとえば、ストリーミング API を使用すれば、商談が更新されるたびに注文発送センターに通知することができます。

メモ

変更データキャプチャの詳細は、「変更データキャプチャの基礎」 Trailhead モジュールを参照してください。

データ変更のほかにも、ストリーミング API では、プラットフォームイベントと汎用ストリーミングを使用してカスタム通知をブロードキャストできます。たとえば、アプリケーションは、注文フルフィルメントサービスが処理する注文のプラットフォームイベント通知を生成できます。または、汎用イベントをリスンし、システムメンテナンス期間の開始前やユーザへの新機能の提供時などにメッセージを表示できます。

この点については、PushTopic の作成時に詳しく説明します。

{
  "clientId": "lxdl9o32njygi1gj47kgfaga4k",
  "data": {
    "event": {
      "createdDate": "2016-09-16T19:45:27.454Z",
      "replayId": 1,
      "type": "created"
    },
    "sobject": {
      "Phone": "(415) 555-1212",
      "Id": "001D000000KneakIAB",
      "Name": "Blackbeard"
    }
  },
  "channel": "/topic/AccountUpdates"
}

SELECT <comma-separated list of fields> FROM <Salesforce object> WHERE <filter criteria>

通知が遅滞なく送信されるように、PushTopic クエリには次の要件が適用されます。

• SELECT ステートメントの項目リストに Id を含める必要があります。
• 1 つのクエリに指定できるオブジェクトは 1 つのみです。
• オブジェクトは、指定された API バージョンで有効である必要があります。

{
  "data": {
    "schema": "dffQ2QLzDNHqwB8_sHMxdA",
    "payload": {
      "CreatedDate": "2018-08-22T12:11:40.517Z",
      "CreatedById": "005D0000001cSZs",
      "Order_Number__c": "12345",
      "Has_Shipped__c": true
    },
    "event": {
      "replayId": 1
    }
  },
  "channel": "/event/Order_Event__e"
}

StreamingChannel ch = new StreamingChannel();
ch.Name = '/u/Broadcast';
insert ch;

また、ストリーミングチャネルが存在しない場合に Salesforce で動的に作成されるようにするオプションを選択できます。組織で動的ストリーミングチャネルを有効にするには、[設定] から [クイック検索] ボックスに「ユーザインターフェース」と入力し、[ユーザインターフェース] を選択します。[ユーザインターフェース] ページで、[動的ストリーミングチャネル作成を有効化] オプションを選択します。

CometD クライアントを使用してチャネルに登録できます。(「リソース」セクションに『ストリーミング API 開発者ガイド』のサンプルウォークスルーへのリンクがあります)。

イベントを生成するには、次の REST リソースへの POST 要求を行います。XX.0 を API バージョン、Streaming Channel ID をチャネルの ID に置き換えます。

/services/data/vXX.0/sobjects/StreamingChannel/Streaming Channel ID/push

メモ

チャネル ID を取得するには、StreamingChannel で SELECT Id, Name FROM StreamingChannel などの SOQL クエリを実行します。

REST リクエストボディの例

{
  "pushEvents": [
      {
          "payload": "Broadcast message to all subscribers",
          "userIds": []
      }
   ]
}

メモ

すべての登録者にブロードキャストする代わりに、省略可能な userIds 項目を使用して、通知を送信する登録ユーザのリストを指定します。また、Streaming Channel Push REST API リソースの GET メソッドを使用して、チャネルのアクティブな登録者のリストを取得することもできます。

登録クライアントが受信するイベント通知は次のようになります。

{
  "clientId": "1p145y6g3x3nmnlodd7v9nhi4k",
  "data": {
    "payload": "Broadcast message to all subscribers",
    "event": {
      "createdDate": "2016-09-16T20:43:39.392Z",
      "replayId": 1
    }
  },
  "channel": "/u/Broadcast"
}

このイベント通知には replayId 項目が含まれています。 

イベント通知のおかげで、自信を持って荒波を航行し、宝物がたくさんある島に向かうことができます。

ここまで、さまざまなイベント種別について学びました。クライアントがイベントチャネルに登録する前、またはクライアントが接続していないときに、Salesforce レコードが作成または更新されている場合はどうなるでしょうか? API バージョン 37.0 より前は、対応する通知がクライアントに送信されませんでした。API バージョン 37.0 以降は、PushTopic イベント、汎用イベント、標準規模のプラットフォームイベントは 24 時間、大規模イベントは 72 時間それぞれ保存されます。この時間内であればいつでもイベントメッセージを取得できます。やりました!

API バージョン 37.0 以降、各イベント通知メッセージには replayId という項目が含まれています。動画の再生のように、ストリーミング API は replayId 項目を使用して、送信されたイベント通知を再生します。

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

次の図は、イベントコンシューマがさまざまな再生オプションを使用してイベントのストリームを読み取る方法を示しています。