salesforce零基础学习（八十五）streaming api 简单使用（接近实时获取你须要跟踪的数据的更新消息状态）

时间 2021-08-12

标签 php java git github express api 服务器 spa code orm 栏目 PHP 繁體版

原文原文链接

Streaming API参考连接：php

https://trailhead.salesforce.com/en/modules/api_basics/units/api_basics_streamingjava

https://resources.docs.salesforce.com/210/latest/en-us/sfdc/pdf/api_streaming.pdfgit

背景：工做中咱们有可能会有这样相关的需求：某些数据很重要，须要实时监控是否有变化,或者某些数据在其余的平台有集成。若是有变化，不刷新页面或者作其余trigger等操做即可以收到相关更改的推送通知（不论是salesforce平台仍是其余外部服务，好比java端等，能够经过此种方式进行实时同步），告诉当前的须要监控的记录已经发生了变化。这种场景每每更会出如今数据不止存储在salesforce端，还有其余平台有数据的存储或者访问。这种状况下可使用Streaming API。github

一.Stream API简单介绍express

Streaming API提供了两种功能，一种为基于Salesforce数据改变，对订阅的客户端进行通知推送，另外一种是不基于Salesforce数据改变，对订阅的客户端进行通知推送，接下来大部份内容基于Salesforce数据改变后，对订阅的客户端进行推送，另一种感兴趣的能够自行查看。通知推送不止能够应用于salesforce系统，其余系统等也能够经过oauth等链接后接收到通知推送，感兴趣的能够查看API提供的内容。api

Streaming API用于制定一套你想要接收的数据的条件，而且指定哪些事件（create/update/delete/undelete）状况下符合的数据推送一条通知到客户端，一条通知就是事件触发的结果发送到渠道的消息。通知的格式为JSON的格式。使用Streaming API能够减小没必要要的API请求。服务器

Streaming API使用的推送技术，即服务器端会主动给订阅的客户端发送通知信息，而不是客户端去调用服务器端返回消息，使用Bayeux协议和CometD用于长轮询。spa

cometd 参考连接： https://docs.cometd.org/code

若是想使用Streaming API，须要enable api的权限以及streaming api的权限orm

想要接受通知(notifications),当前登陆的user必须针对StreamingChannel表拥有read权限

想要建立和管理通知，当前登陆的user必须对StreamingChannel拥有Create权限

二.Streaming API 使用步骤

针对开发者来讲，更关注的是这个东西如何使用。使用Streaming API实现订阅者接收符合条件的推送消息能够三步走：

1.建立PushTopic

去除一下PushTopic神奇的面纱，简单的来讲，PushTopic是一个标准的sObject，封装了如下的字段：

ApiVersion：用于指定查询的SQL的版本，37之后系统能够存储24小时之内的事件，必填字段；
Description：PushTopic的描述信息，限定在400个字符之内；
ID：指定一条记录的全局惟一的标识；
isActive：是否可用，关系到PushTopic的限制计数（系统对PushTopic有limitation size）；
IsDeleted：指定此PushTopic是否移动到回收站；
Name：PushTopic的名字，定义了渠道的名字，而且此名称必须是惟一的，后期订阅者订阅时，使用的就是这个名字；
NotifyForFields：指定哪些字段被评估生成通知；
NotifyForOperations：指定数据哪一种事件操做会生成通知，在api version 29之后，此字段为只读字段；
NotifyForOperationCreate：Create操做是否会生成通知，api29之后可用；
NotifyForOperationDelete：Delete操做是否会生成通知，api29之后可用；
NotifyForOperationUndelete：UnDelete操做是否会生成通知，api29之后可用；
NotifyForOperationUpdate：Update操做是否会生成通知，api29之后可用；
Query：SOQL语句决定了哪些数据符合触发的事件后会发送到渠道。

恩，新建一个PushTopic，设置了必填字段的值insert之后，一个PushTopic就建立完了。这些字段有几个须要详细的描述一下：

Query：Query在PushTopic的做用不言而喻，定义了哪些数据能够知足条件进行推送。Query语法和SOQL基本相同，可是有一些状况不支持。限制以下：

select字段无ID；
子链接查询Semi-joins and anti-joins；
聚合类的查询，好比SUM，AVG等；
COUNT；
LIMIT；
关系型查询不支持，只能够查询到ID，不能经过“.”的方式查询到父的其余信息；
查询中包括Text Area字段；
ORDER BY；
GROUP BY；
WHERE部分使用了formula类型字段；
NOT Example : SELECT Id FROM Account WHERE NOT Name = 'Salesforce.com'
OFFSET
TYPEOF

NotifyForFields：推送的message包含一项sObject字段值的信息，会推送哪些字段值取决于NotifyForFields的赋值，NotifyForFields赋值及做用以下：

All ：推送全部的字段
Referenced (default) : 推送select以及where部分字段的并集集合，若是不指定此字段值，默认值为Referenced
Select ：只推送select部分的字段；
Where；只推送where部分的字段。

NotifyForOperationCreate：指定此字段值为true状况下，当操做的sObject进行insert操做，而且知足query的查询条件，则server端会推送一条通知给全部的订阅者们，此字段当且仅当ApiVersion大于29状况下才容许使用；

NotifyForOperationDelete：指定此字段值为true状况下，当操做的sObject进行delete操做，而且知足query的查询条件，则server端会推送一条通知给全部的订阅者们，此字段当且仅当ApiVersion大于29状况下才容许使用；

NotifyForOperationUndelete：指定此字段值为true状况下，当操做的sObject进行undelete操做，而且知足query的查询条件，则server端会推送一条通知给全部的订阅者们，此字段当且仅当ApiVersion大于29状况下才容许使用；

NotifyForOperationUpdate：指定此字段值为true状况下，当操做的sObject进行update操做，而且知足query的查询条件，则server端会推送一条通知给全部的订阅者们，此字段当且仅当ApiVersion大于29状况下才容许使用。

ApiVersion:此字段声明Streaming版本。在36.0及之前，他不包含客户端的状态,也无法跟踪已通过去的事件信息。简单来讲，若是声明的版本为36及之前状况下，客户端订阅了渠道后，只能收到订阅后的知足条件的数据事件发生的数据，订阅之前的相关知足事件的数据便无法接收到。若是将此字段设置值为37.0及以上，Streaming API支持存储24小时内知足条件的数据通知信息，即便客户端订阅渠道后，也能够重播24小时内的之前的数据。一条记录有可能出现增删改等不少的事件，每个广播事件经过replayId做为编号，replayId在org和渠道中是惟一的，即便事件被删除后，此事件对应的replayId也不会被重用，订阅者能够经过赋值ReplayId接收不一样的事件消息进行重播，主要有三种ReplayId 赋值

-2：订阅者链接渠道后，接收全部的事件，包括订阅时前24小时的事件消息；

-1：订阅者链接渠道后，接收订阅之后的事件消息；

replayId：订阅者链接渠道后，接受指定replayId以及之后的事件消息，好比replayId为5，订阅者将会受到5之后的事件消息。

(注：每一个Query语句中只能搜索一个sObject.)

当新建PushTopic想要查看是否建立成功以及是否生效，或者模拟PushTopic的订阅，可使用workbench查看相关的状态，这里以Account为例，监听Account增删改事件，有以上事件则会发送通知。

1）登陆workbench,网址https://workbench.developerforce.com/login.php，选择登陆的版本为36.0

2）Jump To选择Streaming Push Topics

3)Push Topics 选择刚刚建立的TestAccountStreaming，点击Subscribe,则目前已经模拟订阅了此PushTopic

4）修改了一条Account信息，则会在Streaming Push Topic 显示具体的修改信息推送消息了。

PushTopic按照上面的字段描述能够很轻松的建立了，下一步应该是让客户端来订阅。如何让订阅呢，这时，咱们须要定义一个渠道，保证客户端能够顺利订阅此渠道（Channel），当有知足条件事件的数据进行触发后，由渠道server主动推送给订阅此渠道的客户端。渠道在salesforce端也封装成了一个对象 StreamingChannel，

StreamingChannel表结构以下：

Description ： Streaming Channel的描述
ID ： Streaming Channel的ID
IsDeleted ：指定Streaming Channel是否被移动到回收站
IsDynamic ：若是为true则在订阅时动态建立channel
LastReferencedDate ：存储当前用户最近一次查看的这条记录的时间戳
Name：绑定的PushTopic，以/u/开始，命名为/u/pushtopic Name
OwnerId : Streaming Channel的owner

这里主要须要说明的一个字段就是Name，Name字段要求必须为/u/PushTopicName，而且PushTopicName只能包含标准的字符以及‘_’或者‘/’，其余的字符不支持，好比上面建立的PushTopic的名称为TestAccountPushTopic，则建立StreamingChannel时，Name必须为/u/TestAccountPushTopic,而且区分大小写。

2.客户端订阅渠道

客户端订阅渠道能够简单的分红三部分：

发送一个握手请求
向渠道发送一个订阅的请求
使用长响应（轮询）进行链接。

若是订阅是在页面或者组件中使用，可使用Cometd进行操做，Cometd提供了基本方法用来实现客户端订阅操做，详见Cometd API。当渠道成功后，PushTopic定义的query的数据执行的操做事件（create/update/delete/undelete）知足了PushTopic定义的操做条件，渠道将会向全部订阅的客户端发送通知。上面说道，通知是一个JSON的字符串，大概格式以下所示：

{
  "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"
}

订阅者订阅接收消息须要有如下的权限：

where条件部分的字段的FLS

query对象的读的权限

PushTopic对象的读的权限

基于Sharing Rule的新建和编辑记录的权限

Salesforce存储了基于PushTopic时间24小时，而且容许你去从新检索已经存储的以及新的事件。订阅者能够经过重播的选项来选择哪些事件接收。

当你订阅一个渠道后，你并不想接收全部的数据，好比对于客户信息，不一样的人员更关注本身的客户的变化信息，这是你能够在订阅的URL后添加filter对事件通知进行过滤，推送你须要的通知信息。

eg：/topic/ChannelName?<expression>

其中ChannelName为上面定义的渠道的名称，<expression>包含一个或者多个条件，多个条件使用'&'分割，好比

/topic/TestAccountPushTopic?country=China&isActive=true
若是使用ID做为过滤条件，须要使用18位的ID格式，15位的不支持。

三.代码举例

官方提供了两个demo，一个是基于数据进行DML操做发送给订阅者消息，一个是主动广播发送给订阅者消息。

https://github.com/developerforce/SalesforceDurableStreamingDemo/archive/master.zip

能够下载下来看一下代码，代码里面详尽的讲解了客户端握手，订阅以及接受信息的操做。

总结：本篇主要简单讲解Streaming API的使用方式以及什么状况下会使用到此API，若是使用到查看上面的文档便可。