Salesforce-API

Salesforce API(5)Streaming

学习目标

完成本单元后,您将能够:

  • 描述推技术提供的过拉技术的主要好处。
  • 创建一个PushTopic并接收事件通知。
  • 指定重播选项以进行持续流式传输。
  • 用通用流播放消息。

流事件

为了总结我们对Salesforce数据API的调查,我们来看看一个完全不同用例的API。流式API使您可以根据您定义的条件将一系列通知从Salesforce推送到客户端应用程序。推送通知与我们其他API使用的拉式范例有什么不同,客户端应用程序向Salesforce请求还是从中拉取数据?我们从船长的角度来看问题。
想象一下,你正在航行公海,你要留意迎面而来的危险,其他船只和富有宝藏的岛屿。你把一个水手放在鱼窝里保持积极的了望。现在再次戴上你的开发者帽子。假设您正在使用REST或SOAP API编写应用程序,该应用程序会定期检查是否有帐户已更新。您可以使用类似的解决方案,并通过不断请求帐户数据并检查其是否与旧数据匹配来保持主动了望。

现在想象你再次在你的船上,但是这次你可以使用一个闪亮的新型雷达显示器。你不需要把水手留在鱼窝里,因为每当感兴趣的物体接近时,显示器会发出蜂鸣声。

流媒体API是你的雷达。它允许您定义事件并在事件发生时将通知推送到您的客户端应用程序。您不必积极监视数据更改 – 您不必经常轮询Salesforce并发出不必要的API请求。

Streaming API can be used like a radar to detect data changes and send notifications

在Salesforce外部系统中存储业务数据时,跟踪Salesforce中的数据更改尤其有用。您可以使用Streaming API将您的外部来源与Salesforce数据保持同步。此外,Streaming API还可以处理外部系统中的业务逻辑,以响应Salesforce中的数据更改。例如,您可以使用Streaming API在机会更新时通知履行中心。

除了数据更改之外,还可以使用Streaming API为Salesforce外部定义的事件广播通知。例如,您可以在系统维护时段即将开始时或向用户提供新的优惠时使您的应用程序显示消息。这个功能被称为通用流媒体,我们也会介绍它。

Streaming API使用Bayeux协议和CometD消息库。

PushTopics

我们通过PushTopics与Streaming API进行交互。 PushTopic是一个sObject,它包含您想要侦听的事件的标准,例如特定对象的数据更改。您可以在PushTopic中将条件定义为SOQL查询,并指定记录操作以通知(创建,更新,删除和取消删除)。除了事件标准之外,PushTopic表示客户端应用程序订阅的频道。
当我们创建我们自己的PushTopic时,我们会深入下去。

PushTopic查询中支持的对象

PushTopic查询支持所有自定义对象。 PushTopic查询支持以下标准对象。

  • Account
  • Campaign
  • Case
  • Contact
  • Lead
  • Opportunity
  • Task

通过试验程序在PushTopic查询中支持以下标准对象。

  • ContractLineItem
  • Entitlement
  • LiveChatTranscript
  • Quote
  • QuoteLineItem
  • ServiceContract

PushTopics和通知

PushTopic使您能够定义您感兴趣接收事件通知的对象,字段和条件。以下示例显示了在Apex中定义并插入的PushTopic。在创建PushTopic之后,您可以订阅此PushTopic频道以跟踪账单城市是旧金山的客户的变化。此PushTopic指定在每个事件通知中返回Id,Name,Phone字段。默认情况下,会发送通知来创建,更新,删除和取消删除与查询条件匹配的操作。

PushTopic pushTopic = new PushTopic();
pushTopic.Name = 'AccountUpdates';
pushTopic.Query = 'SELECT Id, Name, Phone FROM Account WHERE BillingCity=\'San Francisco\'';
pushTopic.ApiVersion = 37.0;

insert pushTopic;
至少定义PushTopic名称,查询和API版本。您可以使用其余属性的默认值。默认情况下,SELECT语句字段列表和WHERE子句中的字段是触发通知的字段。通知只发送给符合WHERE子句条件的记录。要更改哪些字段触发通知,请将pushTopic.NotifyForFields设置为其中一个值。
NotifyForFields值 描述
All 如果所评估的记录符合WHERE子句中指定的条件,则会为所有记录字段更改生成通知。
Referenced (default) 评估SELECT和WHERE子句中引用的字段的更改。只有在评估记录符合WHERE子句中指定的条件时,才会生成通知。
Select 计算SELECT子句中引用的字段的更改。只有在评估记录符合WHERE子句中指定的条件时,才会生成通知。
Where 对WHERE子句中引用的字段的更改进行评估。只有在评估记录符合WHERE子句中指定的条件时,才会生成通知。

要显式设置通知首选项,请将以下属性设置为true或false。默认情况下,所有值都设置为true。

pushTopic.NotifyForOperationCreate = true;
pushTopic.NotifyForOperationUpdate = true;
pushTopic.NotifyForOperationUndelete = true;
pushTopic.NotifyForOperationDelete = true;
如果您创建一个帐户,则会生成一个事件通知。通知以JSON形式提供,并包含我们在PushTopic查询中指定的字段:Id,Name和Phone。事件通知类似于以下内容。
{
  "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"
}
通知消息包含PushTopic的通道,其名称格式为 /topic/PushTopicName. 当您创建一个PushTopic时,通道会自动创建。

推送专题查询

让我们花点时间深入一下我们为我们的PushTopic定义的查询。 PushTopic查询是常规的SOQL查询,所以如果您熟悉SOQL,则不需要学习新的格式。如果你不熟悉,不要担心。我们在这里介绍基本的查询格式。简而言之,查询包含一个带有可选WHERE子句的SELECT语句,如下所示。

SELECT <comma-separated list of fields> FROM <Salesforce object> WHERE <filter criteria>
默认情况下,逗号分隔的字段列表指定要检测其更改的字段。这些字段的值在通知消息中发送。 FROM子句指定我们感兴趣的数据更改的对象。WHERE子句根据条件将记录集合缩小为更具体的集合。如果WHERE子句中的条件得到满足,则对WHERE子句中的字段的更改也会生成通知。您可以通过修改PushTopic字段NotifyForFields来更改哪些字段生成通知。
WHERE子句支持SOQL支持的运算符,如LIKE,IN,OR和AND运算符。例如,要过滤帐单城市是旧金山或纽约的帐户,我们将使用此查询。
SELECT Id, Name, Phone FROM Account WHERE BillingCity='San Francisco' OR BillingCity='New York'
为了确保及时发送通知,以下要求适用于PushTopic查询。
  • SELECT语句的字段列表必须包含Id。
  • 每个查询只允许一个对象。
  • 该对象必须对指定的API版本有效。

某些查询不受支持,例如聚合查询或半连接。

使用持久数据流检索过去的通知

到目前为止,您已经了解了有关Salesforce记录更改的PushTopics和事件通知。如果在客户端订阅PushTopic之前创建或更新Salesforce记录,会发生什么情况?在API版本37.0之前,客户端错过了相应的通知。从API版本37.0起,即使没有人订阅PushTopic,Salesforce也会存储与PushTopic查询匹配的事件。这些事件被存储了24小时,您可以随时在窗口中找回它们。好极了!

从API版本37.0开始,每个事件通知都包含一个名为replayId的字段。与重放视频类似,Streaming API会重播使用replayId字段发送的事件通知。 replayId字段的值是标识流中事件的数字。重播ID对于组织和渠道是唯一的。当您重放一个事件时,您将从存储流中的位置检索存储的事件。您可以检索由重播ID指定的事件之后开始的事件流,也可以检索所有存储的事件。以下是订阅频道时可以指定的重播选项的摘要。

重播选项 描述
replayId 订阅者接收通过重播ID值指定的事件发生的事件的通知。
-1 订阅者接收订阅后发生的所有新事件的通知。
-2 订阅者接收订阅后发生的所有新事件的通知,以及在24小时保留窗口内的先前事件。

此图显示了事件使用者如何使用各种重播选项来读取事件流。

Streaming events with replay options

样品持久的流媒体应用程序

要了解如何订阅事件并使用重播选项,请参阅“Streaming API开发人员指南”中的持久流式码示例。提供了几个示例,包括使用JavaScript CometD扩展的Visualforce页面和使用CometD连接器的Java客户端。这些代码示例的链接包含在参考资料部分。

通用流媒体

在您自行启动之前,让我们花几分钟的时间来回顾一下通用流。 Streaming API支持使用不受Salesforce数据更改限制的通用有效内容发送通知。
您可以在任何想要发送自定义通知的情况下使用通用流式传输,例如:

  • 将消息广播给特定的团队或整个组织
  • 发送Salesforce外部事件的通知

要使用通用流式传输,您需要:

  • 定义频道的流媒体频道
  • 一个或多个客户订阅该频道
  • Streaming Channel Push资源监视和调用通道上的事件

您可以通过用户界面中的Streaming Channels应用程序或通过API为通用流式创建流式通道。流式通道由StreamingChannel sObject表示,因此您可以通过Apex,REST API或SOAP API来创建它。通用流的通道名称的格式是 /u/ChannelName. 例如,这个Apex片段创建一个名为广播的频道。

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

insert ch;
或者,您可以选择让Salesforce动态地为您创建流式频道(如果不存在)。要在组织中启用动态流式传输渠道,请从“设置”中,在快速查找框中输入用户界面,然后选择 User Interface. 在“用户界面”页面上,选择 Enable Dynamic Streaming Channel Creation 选项。

您可以使用CometD客户端订阅频道。 (参考资料部分链接到Streaming API开发人员指南中的示例演练。)

要生成事件,请向以下REST资源发出POST请求。用您的频道的ID替换XX.0与API版本和 Streaming Channel ID

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

注意

要获得您的通道ID,请在StreamingChannel上运行SOQL查询,如: SELECT Id, Name FROM StreamingChannel

示例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字段。与PushTopic流式传输一样,通用事件通知也存储了24小时,可以使用API​​版本37.0中的replayId值进行检索。

通过活动通知,您可以放心地在公海启航,前往富有宝藏的岛屿!

你可能也会喜欢...