应用开发示例2：Zoho CRM

我们之前做了一个简单的应用示例开发：百度云OCR

在这篇文章里，我们将介绍一个较为复杂的应用接入：Zoho CRM，从这个示例中我们将了解：

● 如何配置Oauth2.0授权

● 如何配置一个触发动作 （包含授权前额外步骤）

● 如何配置动态下拉选项

● 如何使用代码模式进行开发

1 应用案例介绍和功能说明

Zoho CRM是一款国际的CRM系统，我们将使用其作为案例说明如何对Oauth2.0的应用进行开发，同时讲解如何配置触发动作，和一些更加复杂的接口功能。

Zoho CRM中国官网：https://www.zoho.com.cn/crm/

Zoho CRM开发文档：https://www.zoho.com.cn/crm/help/developer/api/overview.html

2 配置OAuth2.0授权

Zoho CRM是一个通过OAuth2.0 授权的应用，同时包含一个额外的选择服务器地区步骤，然后再进行OAuth2.0授权步骤。下面是成品演示截图：

首先是一个服务器地区选择：（您的应用不一定需要这个步骤）

每个选项选择后API接口请求的网址会有不同，比如：

中国是：https://www.zohoapis.com.cn

美国是： https://www.zohoapis.com

因此如果您的授权地址有多个，需要用户在授权时选项，比如 不同的产品版本，不同的服务器地址（例如私有部署版本可能需要用户填写他们的部署网址），您可以配置一个额外步骤让用户选择。如果授权地址是固定的，则无需这个步骤。

授权后，进入Oauth2.0授权界面：

好的，成品演示完毕，我们开始一步步的来进行配置：

2.1 设置额外步骤字段（非必须）

根据Zoho CRM接口授权文档：

https://www.zoho.com.cn/crm/help/developer/api/auth-request.html

我们配置授权方式，选择Oauth2.0授权：

因为Zoho CRM有不同服务器地区，且接口地址不同，因此我们做一个额外选项让用户选项他们账户所在的服务器地址：（您的应用Oauth2.0授权不一定需要此额外步骤配置，如不需要可以忽略此步骤的授权字段设置）

字段名称：用户在前端可以看到的名称, 本示例中为API Key

字段key: 此字段对应在接口调用时的Key，本示例中为 client_id

是否必填：如果用户必须填写此字段，则勾选此选项

字段类型：目前在授权环节支持的字段类型有三种：文本，密码（前端以密码形式展现），和 下拉。如果是下拉类型，则需要在页面最后的选项中配置选项的字段key与字段值。本示例中为文本

字段说明：用于在前端展现给用户，一般用于说明此字段在哪里获取，或者填写时应该注意什么。

默认字段值：可以设置在字段中默认展现一个字段值，用户可以直接使用此字段值或者删除此字段值后重新填写。

下拉选项：仅字段类型为”下拉”类型时需要设置

更多关于字段参数设置可以见：

如何设置动作字段？

保存后，返回授权设置页面我们可以看到刚才配置的字段已经展现在授权字段设置中：

2.2 设置授权回调地址和Client Key, Client Secrect

Oauth2.0 的授权认证中一般需要配置授权回调地址，Client ID和 Client Secret.

根据Zoho CRM的开发者文档，https://www.zoho.com.cn/crm/help/developer/api/register-client.html

开发者需要在Zoho开发者平台注册了一个开发者账户，并创建一个应用以获取Client Key和Client Secret, 并设置授权回调地址。（与企业微信，钉钉，抖音，微信公众号的开发者平台授权逻辑类似。）

按照Zoho文档提示，我们注册了一个开发者账户并获取了Client ID 和 Client Secret

我们返回集简云开发者平台添加Client ID 和 Client Secret

同时将集简云开发者平台生成的回调URL填写回Zoho CRM创建的应用中：

3 设置授权接口请求参数

Zoho CRM的Oauth2.0是比较规范的流程，包括以下几个步骤：

发起授权请求，对应集简云开发者平台的“URL接口设置 ”步骤

生成令牌：对应集简云的”Access Token请求接口“步骤

刷新访问令牌：对应集简云的“刷新Token请求接口”步骤

下面我们逐一说明：

3.1 “URL接口 ”配置步骤

这个步骤用于在前端发起授权请求：

根据Zoho CRM的发起授权请求，文档：https://www.zoho.com.cn/crm/help/developer/api/auth-request.html

我将请求中需求的参数添加到接口请求中：

配置后点击保存

3.2 "Access Token请求接口"配置步骤

用户完成授权后，我们需要换取授权账户的Access Token用于后续接口的调用。

根据Zoho CRM的“生成令牌”文档：https://www.zoho.com.cn/crm/help/developer/api/access-refresh.html

我们将对应参数添加到Access Token请求接口步骤中：

其中code字段要填写授权步骤返回参数中code字段的字段值，因此我们使用变量 {{auth_data.code}}, 任何在授权步骤接口返回的参数都可以以变量 {{auth_data.xxx}}调用，其中xxx部分为授权接口返回中对应的字段key。 在Zoho CRM这个示例中为{{auth_data.code}}。

另外注意的是在Zoho CRM文档中请求接口地址是一个变量：{Accounts_URL}， 这个值需要根据用户在授权步骤选择的服务器地区请求不同的接口地址。较为复杂，需要使用到“编码模式”。关于编码模式我们在后面的文章里会介绍。因此在截图中我们使用了一个固定的API接口地址替代。

3.3 ”刷新Token请求接口“配置步骤

如果您的Oauth2.0授权有一定的实效性，比如1个月或者3个月，您应该配置“刷新Token请求接口“步骤。

根据Zoho CRM的刷新token文档：https://www.zoho.com.cn/crm/help/developer/api/refresh.html

我们根据文档配置对应的接口参数

同时我们勾选了自动刷新Token，这样如果token过期报401错误时，集简云将自动执行token刷新接口，如果您不设置自动刷新，那么则授权过期后需要用户在前端手动重新更新账户时刷新token。

4 测试账户授权

配置完毕后在“账户授权测试”步骤，点击添加新账户，进行测试

可见我们授权窗口已弹出，测试成功。

如果您的授权认证较为复杂，可以使用代码模式进行开发授权，更多关于代码模式的说明见：

编码模式说明

5 配置触发动作

为了更好的说明触发动作配置，我们在这个示例中准备了3个不同的触发动作：

实时触发：当有新增联系人时 （通过Zoho CRM订阅消息接口实现)

定时触发：当有新增联系人时 (通过Zoho CRM查询联系人列表判断新增实现）

实时触发：当指定模块有新增数据时 （通过动态请求模块接口来实现）

点击触发动作设置，配置触发动作

5.1 实时触发：当有新增联系人时

Zoho CRM支持消息订阅接口：https://www.zoho.com.cn/crm/help/developer/api/subscription/enable.html ， 如果您的应用支持事件推送功能，您可以选择创建实时触发动作。

我们开始配置这个动作：

5.1.1 动作信息设置

动作信息设置是用于配置用户在前端看到的动作名称

用户在前端看到的样式：

动作名称：在前端展现给用户的动作名称，例如：当有新联系人创建时

动作Key：用于接口调用时的唯一字段标识，字段key应该为英文字母，例如API_Key，用户在前端不可见此字段

动作功能描述：描述此动作的功能，用户可以在前端看到此动作功能描述，示例：当有新增联系人时同步数据并触发流程。

动作是否可见：选择用户是否可以在前端选择和使用此动作，如果设置为不可见则仅用于动作之间内部调用，例如：在下拉字段中动态拉取部门成员列表，可以设置一个不可见的读取成员列表动作，在其他可见动作字段配置中进行调用。

5.1.2 动作字段设置 （触发动作配置时非必填）

如果您的触发动作需要用户进行额外的数据筛选，可以配置一个动作字段设置，例如只有指定条件满足时才触发此动作. 如果您不需要用户进行额外的数据筛选，则无需配置。

更多关于动作字段设置说明见：

如何设置动作字段？

5.1.3 动作接口参数

在这个部分配置如何调用您的应用接口。与执行动作不同，触发动作的触发方式分为2种：

数据推送：如果您的应用接口包含数据推送或者数据订阅功能，可以配置为此方式。此方式配置后可进行实时触发。每当有数据推送过来时触发流程

主动拉取：如果您的应用接口没有实时推送数据接口，但是有查询数据列表的接口可以使用主动拉取的方式触发。集简云将定时拉取数据列表，并进行排重判断是有新增数据，如果有新数据则触发流程，没有新增数据则不会触发流程。

在当前这个示例中，Zoho CRM有数据订阅接口，因此我们配置“数据推送”方式

5.1.3.1 订阅接口配置

订阅接口是通过接口订阅一个指定事件，依据Zoho CRM的接口文档：

https://www.zoho.com.cn/crm/help/developer/api/subscription/enable.html

配置接口参数：

注意：事件订阅地址为集简云系统自动生成，您只需要填写一个订阅地址变量{{bundle.targetUrl}} 即可

5.1.3.2 取消订阅接口配置：

取消订阅是用于用户取消授权后，集简云自动解除对消息的订阅。依据Zoho CRM的接口文档：https://www.zoho.com.cn/crm/help/developer/api/subscription/unsubscribe.html

5.2 定时触发：当有新增联系人时

为了更好的说明定时触发的配置方式，我们做一个示例：

首先选择：“主动拉取“：

主动拉取会定时读取接口数据（默认为15分钟1次），您需要返回一个数据列表，集简云内置的排重功能会判断是否有新增数据，并触发流程。

我们以读取Zoho CRM联系人列表为示例，当联系人列表有新增数据时触发流程。

接口文档：

https://www.zoho.com.cn/crm/help/developer/api/get-records.html

这里联系人模块的key为“Contacts”.

使用主动拉取读取数据列表时，需要：

排序：您的数据列表是按照一定顺序排序的，例如：当触发动作为：有新增数据时，应该使用数据的创建时间排序。当触发动作为：有数据更新时，应该使用更新时间排序。

唯一ID: 数据列表中的每条数据需要一个唯一ID，集简云将使用这个ID作为数据排重的依据。

Zoho CRM查询记录列表接口的排序字段为“sort_order”, 因为我们需要查询最新的数据，因此我们需要使用倒序，字段值填写“desc”

从Zoho CRM的接口文档可以看到每条数据都有一个唯一ID: id

因此我们在“数据唯一标识”字段填写“id”

5.3 实时触发：当指定模块有新增数据时

我们可以看到Zoho CRM有多个模块，线索，联系人，合同，市场活动等等，如果我们一个个配置触发动作需要配置很多条，用户选择起来也不方便。我们可以配置一个动态的选择动作，让用户在前端选择模块，当这个被选择的模块有新数据时触发流程。

成品效果如下：

5.3.1 配置一个不可见动作：查询模块列表

首先，我们要配置一个不可见动作用于读取可用模块列表，然后在设置触发动作调用此不可见动作。

在此动作接口中调用Zoho CRM的查询模块接口：

https://www.zoho.com.cn/crm/help/developer/api/modules-api.html

按照接口参数：

注意：下拉字段必须返回 key:label的格式。 其中key为下拉选项的唯一ID，将用于接口调用，label是展现给前端用户的选项名称。

然而Zoho CRM查询模块列表的返回参数并不是这个格式，其中包含了很额外参数

因此我们需要通过代码模式进行编写，将其转换为集简云需要的下拉列表格式：

点击接口配置中的编码模式：

使用下面的代码：

# 变量引用
# 认证字段：{{auth_data}} 
# 输入字段：{{input_data}} 
# 环境变量：{{process.env}}

# 支持import引入python内置模块，不支持第三方模块

# 请求参数选项
options = {
  'url': "https://www.zohoapis.com.cn/crm/v2/settings/modules",
  'method': 'GET',
  'headers': {
    'Content-Type' : 'application/x-www-form-urlencoded',
    'Accept' : 'application/json',
    'Authorization' : 'Zoho-oauthtoken {{auth_data.access_token}}',
    
  },
  'params': {
    'scope' : 'ZohoCRM.settings.modules.READ',
  },
  'body': {
  },
}

# 调用请求，返回的结果在response里
# 如果不需要接口请求，可以删除下面行
response = jjyHttpRequest(options)

# 存储临时数据。
# 参数'secret': type=str,要求为UUID4格式；
# 参数'data': type=dict or list, 支持可序列化的json格式。
# 注：临时存储的数据最多保留30天
# jjySave(secret, data)

# 读取临时数据。参数'secret':要求为UUID4格式,存储时传入的secret
# jjyLoad(secret)

modules = response.json()['modules']
outPutData = []
for item in modules:
  outPutData.append({'key':item['api_name'],'label':item['module_name']})


                

在OutPutData中将接口返回的参数进行整理。更多关于编码模式和变量使用方式见：

编码模式说明

编译变量&使用方式

5.3.2 创建一个新动作：当指定模块有新增数据时

下面我们开始创建新触发动作，并在此触发动作中调用上面配置的模块查询不可见动作：

添加一个“选择一个CRM模块”字段，允许用户选择哪个模块有新增数据时触发流程。

这里我们要动态展现一个下拉列表，首先勾选”是否有下拉选项”，然后勾选动态选项，在下拉选项中可以选择之前配置的动作：“查询模块列表”。

注意：只有通过接口测试的动作可以下拉选项中被调用.

动作接口参数配置：

下面我们进行动作订阅接口配置：

我们使用编码模式填写代码：

# 变量引用
# 认证字段：{{auth_data}} 
# 输入字段：{{input_data}} 
# 环境变量：{{process.env}}

# 支持import引入python内置模块，不支持第三方模块

# 请求参数选项
options = {
  'url': 'https://www.zohoapis.com.cn/crm/v2/actions/watch',
  'method': 'POST',
  'headers': {
    'Content-Type' : 'application/json',
    'Accept' : 'application/json',
    'Authorization' : 'Zoho-oauthtoken {{auth_data.access_token}}',
    
  },
  'params': {

  },
  'body': {
    "watch": [
       {
            "channel_id": "1000000068001",
            "events": [
                '{{input_data.model_select}}.create'
            ],
            "notify_url": '{{bundle.targetUrl}}'
        },
    ]
  },
}

# 调用请求，返回的结果在response里
# 如果不需要接口请求，可以删除下面行
response = jjyHttpRequest(options)

# 存储临时数据。
# 参数'secret': type=str,要求为UUID4格式；
# 参数'data': type=dict or list, 支持可序列化的json格式。
# 注：临时存储的数据最多保留30天
# jjySave(secret, data)

# 读取临时数据。参数'secret':要求为UUID4格式,存储时传入的secret
# jjyLoad(secret)

# 需要返回一个对象结构,outPutData 用于存放返回数据
outPutData = response.json()

其中events字段我们引用了之前配置的隐藏动作的动作key做为变量，这样用户在前端选择模块后我们会向选项动态添加这里作为请求，注意使用变量时引用的是动作设置中的“动作key". 不是下拉列表字段的字段key.