连接器
Zoho 提供对包括核心谷歌服务(Contacts、Calendar 和 AdWords)及微软软件(MS Office、MS Outlook 等等)在内的大量第三方应用程序的集成支持。但是,某些服务无法与您的 CRM 直接集成,例如,Dropbox、PandaDoc 和 Google Drive。在这些情况下,可使用连接器来扩展 Zoho 的第三方支持。连接器使用 OAuth 2.0 协议来完成此集成。
OAuth 2.0
OAuth 2.0 是一种行业标准的开源授权协议,用于在 HTTP 服务上获取对用户帐户的部分访问权。OAuth 2.0 授权的一个示例是当第三方应用程序(也称为客户端)请求对社交媒体帐户(例如,Facebook、Google 或 Yahoo)的部分访问权时显示的登录屏幕。
重要术语
- 客户端 - 此应用程序请求访问存储在外部系统中的数据。在 Zoho Developer 控制台中创建连接器时,客户端为 Zoho CRM 或您的自定义垂直 CRM 系统。
- 资源 - 客户端尝试访问此应用程序或服务。在此情况下,资源是您要尝试集成的第三方服务(例如,Dropbox)。
- 请求令牌 URL - 此 URL 用于向资源服务器发送授权请求。资源服务器会提示资源所有者(用户)对此请求授权。
- 访问令牌 URL - 资源所有者对此请求授权后,服务器会向客户端发送访问令牌。每次客户端想要访问资源数据时,必须交换此令牌。
- 刷新令牌 URL - 某些访问令牌仅在有限时间段内有效。访问令牌到期时,客户端必须使用刷新令牌 URL 以从该资源中获取另一访问令牌。
- 客户端 ID - 对每个客户端应用程序提供的唯一标识。此标识由资源所有者提供。
- 客户端密钥 - 每个客户端应用程序具有映射至其的密钥代码。它用于阻止对资源的未授权访问。
- 重定向 URL - 这是数据访问获得授权后最终用户将重定向至的 URL。客户端应用程序将自动生成重定向 URL。
创建连接器
要创建连接器,请执行以下操作:
- 登录 Zoho Developer 控制台,然后点击构建连接器。
- 点击创建连接器。
- 为连接器提供适用名称和描述。
- 提供有关第三方服务器的以下详细信息:
- 请求令牌 URL:这允许连接器请求授权以访问资源服务器上的数据。
- 访问令牌 URL:获得授权后,将针对该访问令牌交换请求令牌和信息密钥,允许连接器从第三方服务器获取特定信息。
- 刷新令牌 URL:某些应用程序通过限制特定令牌的有效期来提高安全性。在这些情况下,您需要提供“刷新令牌 URL”以允许连接器重新对访问授权。
- 点击保存。
- 在所提供空间中提供应用程序的客户端 ID 和客户端密钥。
可通过创建 OAuth 2.0 客户端/应用程序(术语因资源应用程序而异)来获取客户端 ID 和客户端密钥。此页面询问提供了一个示例。 - 复制设置客户端凭证页面中提供的重定向 URL 并在您的 web 应用程序的相应空间内输入该 URL。
这是授权过程完成时用户被重定向至的 URL。 - 点击保存。
关于令牌
请求令牌、访问令牌和刷新令牌 URL 由 web 应用程序提供。可从 web 应用程序的开发者空间获取这些 URL。例如,可从此处获取 Google 应用程序的 URL。
对于任何服务,请求令牌、访问令牌和刷新令牌 URL 将具有多个参数,包括范围、状态、客户端 ID 和访问类型。根据服务的不同,这些参数可能有所不同。但是,以下参数对所有服务是通用的:重定向 URL、客户端 ID 和响应类型。这些参数由 Zoho 处理。如果有任何其他必需参数(例如,“范围”、“状态”或“访问类型”),那么开发者必须以第三方服务指定的格式提供这些参数。
样本谷歌 API:
scope=email%20profile&
state=security_token%3D138r5719ru3e1%26url%3Dhttps://oa2cb.example.com/myHome&
access_type=offline
添加 API
创建连接器后,通过对连接器执行的每个操作添加 API 来定义它可以执行的操作。例如,一旦与 Google Drive 集成,您就可以将 CRM 数据导出至 Google Drive 或将其中的数据导入至 CRM。这两个过程需要不同 API。这些 API 将在应用程序的开发者文档中提供。
要添加 API,请执行以下操作:
- 在 Zoho Developer 控制台主页中,点击连接器。
- 将光标放在所选连接器上时,点击添加 API。
这将显示创建连接器 API 页面。 - 在创建连接器 API 页面中,填写以下详细信息:
- 提供 API 的名称。
- 选择方法类型,然后提供 API URL。
可从资源应用程序获取 API 方法类型及 API URL。
如果您的 API 的 URL 包含动态值,那么它们应添加 "$" 符号作为前缀并括在 {..} 中。
例如,http://example.com/callback?id=${myid}&key=${mykey}。
此处 myid 和 mykey 是动态变量,您必须在用于调用此 API 的自定义函数中定义其值。 - 指定标题字段和 URL 参数。
添加 API 后,可通过执行 API 并检查响应来验证该 API。
添加 API 后,可通过执行 API 并检查响应来验证该 API。
- 在连接器页面中,将光标放在包含要执行的 API 的连接器上,然后点击查看所有 API。
这将显示一个新页面,其中显示与该连接器相关联的所有 API。 - 点击您关注的 API 旁边的执行。
- 如果该 API 运行失败,那么您会在 API 响应区域中收到通知。更改代码,然后再次执行该 API。
发布连接器
从技术上看,发布连接器意味着发布与连接器相关联的 API。一旦发布与连接器相关联的第一个 API,系统将自动发布该连接器。
要发布 API,请执行以下操作:
- 在连接器页面中,将光标放在要在其中添加该 API 的连接器上,然后点击查看所有 API。
- 将光标放在您要发布的 API 上,然后点击发布。
- 点击确定。
现在将发布 API 和连接器,允许您将此连接器添加至扩展。
向扩展添加连接器
要将连接器关联至扩展,请执行以下操作:
- 在 Zoho Developer 控制台主页中,点击 Zoho CRM 的扩展。
- 选择要与连接器关联的扩展。
- 点击左窗格中的连接器。
- 点击添加连接器。
- 从可用连接器列表中选择要添加的连接器,然后点击添加。
- 在所产生弹出窗口中,输入第三方服务提供的客户端 ID、客户端密钥和独有代码。
它们用于在集成期间对您的帐户授权。 - 复制此页面中自动生成的重定向 URL 并将其提供给第三方服务。
- 点击保存。
- 这会将连接器及其所有关联 API 添加至您的扩展。
注
- 只有已发布连接器才会显示在添加连接器弹出窗口内的连接器列表中。尝试将连接器连接至扩展之前,确保它已发布并且可供访问。
调用连接器
连接器已发布并已添加至扩展之后,可根据需要调用该连接器。可使用自定义函数调用连接器。
用于调用连接器的自定义函数的语法为:
response_variable =zoho.crm.invokeConnector("API unique identifier",map);
可从连接器的关联扩展获取 API 唯一标识。
Map() 用于将 API 中的动态值替换为特定于用户的值。例如,如果 API 必须访存线索的详细信息(例如,名称、电子邮件地址、联系人电话号码等等),那么这些值在 API 中以动态值表示。通过使用 map() 函数,可将此动态值替换为线索详细信息页面中的实际值。本文档稍后给出的示例将提供有关此函数的更多详细信息。
要了解有关用于编写自定义函数的函数和变量的更多信息,请点击自定义函数。
要查找 API 标识,请执行以下操作:
- 在扩展的详细信息页面中,点击连接器并选择您要处理的连接器。
- 点击查看所有 API,然后选择您关注的 API。所显示页面包含唯一 API 标识。
此页面将包含 API 唯一标识。
此处将提供示例自定义函数。
样本连接器
为演示连接器的工作方式,我们来看一下示例场景。假设您要将某些 CRM 联系人(符合特定条件的联系人)添加到您的 Google 通讯录列表。Zoho 的现有 Google 通讯录集成对您想要实现的操作无效,因为它将整个 CRM 联系人列表与 Google 通讯录集成。要获取所需功能,您必须创建一个将您的 CRM 系统与 Google 通讯录集成的连接器,然后编写一个自定义函数,每当满足特定条件时,此函数将执行此连接器。
第 1 步:提供请求、访问和刷新令牌 URL
第一步是通过 Google 服务器提供请求令牌、访问令牌和刷新令牌 URL。
- 在 Zoho Developer 控制台主页中,点击构建连接器。
- 点击创建连接器。
- 为 Google 通讯录提供请求、访问和刷新令牌 URL:
- 请求令牌 URL:
https://accounts.google.com/o/oauth2/v2/auth?scope=https://www.google.com/m8/feeds - 访问令牌 URL:
https://www.googleapis.com/oauth2/v4/token - 刷新令牌 URL:
https://www.googleapis.com/oauth2/v4/token
注
- 请求令牌 URL 的基本格式为:<requesttokenURL>?scope="<scopelink>"。
- 要为 Google 通讯录创建特定请求令牌,请将 Google 请求令牌 URL ("https://accounts.google.com/o/oauth2/v2/auth") 与 Google 通讯录的范围 ("https://www.google.com/m8/feeds") 组合到一起。
- 因此,完整请求令牌 URL 应该为
https://accounts.google.com/o/oauth2/v2/auth?scope=https://www.google.com/m8/feeds
第 2 步:提供客户端 ID 和客户端密钥
下一步是从 Google 获取您的应用程序的客户端 ID 和客户端密钥。
要获取这些凭证,请执行以下操作:
- 在 Google Developer Console 主页中,点击屏幕右上角的 Select a Project。这会打开下拉列表。选择 Create a Project。
- 提供项目名称。
- 这将根据项目名称生成默认项目 ID。点击 Edit 以更改 ID。
- 点击 创建。
- 在 Google Developer Console 上的仪表板顶部点击 Enable and Manage APIs。
- 点击 Google APIs,然后在 Google Apps APIs 页签下选择 Contacts API。
- 点击 Enable。
- 启用 API 后,选择左窗格中的 Credentials。
- 点击 Create Credentials,然后选择 OAuth Cliend ID。
- 在 Create client ID 页面中,执行以下操作:
- 选择 Web application 作为 Application type。
- 提供凭证的名称。
- 提供重定向 URL。
此 URL 可从 Zoho Developer 控制台获取。 - 点击 创建。
- 这将生成客户端 ID 和客户端密钥。
复制客户端 ID 和客户端密钥并将它们粘贴到 Zoho Developer 控制台中。 - 点击保存。
第 3 步:对连接器授权
创建连接器后,需要对其授权以使其与您的 Google 帐户同步。
要对连接器授权,请执行以下操作:
- 在 Zoho Developer 的连接器页面中,点击您要处理的连接器旁边的授权链接。
- 如果您未登录 Google 帐户,那么系统会提示您登录。
- 登录后,授权窗口将说明对应该连接器的访问权限。
- 点击允许。
您的连接器现在已获授权。
第 4 步:添加 API
创建连接器后,必须添加 API 以执行所需操作。每个操作将具有不同 API。
要添加 API,请执行以下操作:
- 在 Zoho Developer 控制台主页中,点击连接器。
- 点击您正在使用的连接器旁边的添加 API。
- 在创建连接器 API 页面上填写必需详细信息。
- 要向 Google 通讯录添加新联系人,请填写以下 API 详细信息:
- 方法类型 - Post
- API URL - https://www.google.com/m8/feeds/contacts/{userEmail}/full
在“useremail”的位置,请使用 default 以引用已进行身份验证的用户。 - 标题字段 - Content-Type: application/atom+xml
- 请求正文 - <atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:gd="http://schemas.google.com/g/2005">
<atom:category scheme="http://schemas.google.com/g/2005#kind"
term="http://schemas.google.com/contact/2008#contact"></atom:category>
<gd:name>
<gd:givenName>${Fname}</gd:givenName>
<gd:familyName>${Lname}</gd:familyName>
</gd:name>
<atom:content type="text">Notes</atom:content>
<gd:email rel="http://schemas.google.com/g/2005#work"
primary="true"
address="${Email}" displayName="${Fname}"></gd:email>
<gd:phoneNumber rel="http://schemas.google.com/g/2005#work"
primary="true">
${Mobile}
</gd:phoneNumber>
</atom:entry> - 此处提供其他操作的 API。
- 点击创建。
- 执行 API。
成功执行 API 后,发布 API 并将连接器关联至扩展。
第 5 步:编写自定义函数以调用连接器
发布连接器并将其与扩展相关联后,可使用自定义函数来调用该连接器。通过使用连接器,您可执行以下操作:
1.将来自 CRM 的数据发布至 Google 通讯录帐户。
例如,如果联系人的邮寄地址的国家/地区列示为爱尔兰,并且您想要将 CRM 中的新联系人添加至 Google 通讯录。您需要编写自定义函数以调用连接器并将该自定义函数关联至工作流规则。使用以下设置创建工作流规则
- 模块:联系人
- 规则触发器:基于创建记录时的记录操作。
- 规则条件:邮寄国家/地区为爱尔兰。
- 即时操作:调用自定义函数
对应以上案例的自定义函数为:
Fnam = input.contact.get("FIRSTNAME");
Lnam = input.contact.get("LASTNAME");
mail = input.contact.get("EMAIL");
Mob = input.contact.get("MOBILE");
map = { "Fname" : Fnam, "Lname" : Lnam, "Email" : mail, "Mobile" : Mob};
response = zoho.crm.invokeConnector("googledrive.contacts",map);
此自定义函数将为您的客户创建 Google 通讯录条目。
2.将 Google 通讯录中的数据传送至 Zoho CRM。
可从第三方服务(例如Google 通讯录)获取数据并将其添加至 Zoho CRM。用于实现此操作的自定义函数为:
mapp=Map();
resp=zoho.crm.invokeConnector("googleintegration.contactsintegration.addcontacttogoogle",mapp);
if(resp.get("status_code").contains ("201")){
apiresponse = resp.get("response");
//Use the variable "apiresponse" to get the required data from the API that was executed
}