Salesforce API（5）Streaming

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

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

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

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

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

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

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

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

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

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

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;

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

pushTopic.NotifyForOperationCreate = true;
pushTopic.NotifyForOperationUpdate = true;
pushTopic.NotifyForOperationUndelete = true;
pushTopic.NotifyForOperationDelete = true;

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

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

SELECT Id, Name, Phone FROM Account WHERE BillingCity='San Francisco' OR BillingCity='New York'

• 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指定的事件之后开始的事件流，也可以检索所有存储的事件。以下是订阅频道时可以指定的重播选项的摘要。

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

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

insert ch;

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

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

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

示例REST请求正文。

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

订阅的客户端收到的事件通知看起来类似于以下内容。

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