Zoho CRM SDK

前言

因早期公司的业务在Zoho CRM，现在孵化出自己的想法，想着能把一部分CRM的数据同步导出来，故研究Zoho CRM SDK的接入方法。虽说在文档上都有提及，但有部分细节不甚明了，也是一遍遍尝试出来的，所以分享出来少走些弯路

一、Python SDK

1.环境配置(python2.7及以上)

• pip install requests
• pip install zcrmsdk

注：此处安装的zcrmsdk，可能无法像文档描述似的加载配置文件zcrmsdk.ZCRMRestClient.initialize(config)，那是因为安装的包版本不正确，应pip install zcrmsdk==2.0.11

二、注册应用

我理解着的这个应用相当于访问CRM的媒介，应用APP拿着CRM授权给的访问权限(令牌)请求，认证通过即可访问CRM数据！

1. 访问页面:https://accounts.zoho.com.cn/developerconsole配置应用，两种方式！

• 第一种方式:基于web
  
  
  

• 第二种方式:基于自身self
  
  

三、访问范围权限&授权令牌grant_token

1.两种方式配置，应用与URL

• 应用生成
  ①选择应用Self Client
  ②在“作用域”处填写有效的作用域(参考本章5.)，多个作用域之间用逗号分隔
  ③点击"生成"按钮，提取授权令牌grant_token
  
  
• URL生成
  ①选择应用Test_sdk
  ②收集client_id，作用域scope，重定向redirect_uri的值
  ③授权url规则{Accounts_URL}/oauth/v2/auth，路径参数有scope、client_id,、response_type、access_type、redirect_uri
  ③发起GET请求"https://accounts.zoho.com.cn/oauth/v2/auth?scope=ZohoCRM.Modules.ALL&client_id={client_id}&response_type=code&access_type={"offline"or"online"}&redirect_uri={redirect_uri}"
  ④在重定向的地址栏{redirect_uri}?code={grant_token}&location=cn&accounts-server=https://accounts.zoho.com.cn&中，提取授权令牌grant_token
  
  
  

四、SDK配置

1.相关的参数详解

• client_id、client_secret 和 redirect_uri 是注册 Zoho 客户端后获取的 OAuth 客户端配置
• access_type 取值范围【online，offine】，必须设置为 offline 的唯一原因是 Python SDK 目前不支持在线 OAuth 客户端
• accounts_url 根据您的域（EU或CN），更改 accounts_url 的值。默认值设置为 US 域，此处设置的CN域
• applicationLogFilePath 日志配置，如不提供此参数则不记录，仅在控制台查看它们。"."代表日志存放到当前位置
• sandbox 是否是沙箱账户，默认为false。很明显，此处不是沙箱环境
• 单用户认证 currentUserEmail，多用户认证，需要在当前线程中将用户邮箱地址设置为属性threading.current_thread().__setattr__('current_user_email','[email protected]')。无论如何一定要选择一种方式认证，否则Python SDK将抛出异常
• apiBaseUrl CRM函数模块的调用最终转换成url地址的请求，这个值代表URL地址的根地址。如https://www.baidu.com/s?wd=1111,根地址即为https://www.baidu.com
• apiVersion 调用的api服务版本号。一般跟地址的关系大体是，最终地址=根URL/版本号/api服务的接口名
• token_persistence_path 认证的持久化处理，即类似于token的永久认证。

2.持久化的四种方式，选其一即可

①保存到默认文件zcrm_oauthtokens.pkl (会在配置路径下创建此文件)中，此处采用这种
'token_persistence_path': '.'
②保存到自定义文件中

'persistence_handler_class' : 'Custom',
'persistence_handler_path': 'CustomPersistance.py'

③保存到本地local默认数据库
无需配置其它，自动本地读取数据库配置，需要：数据库端口为3306；数据库名称应该为“zohooauth”；必须有一个名为“oauthtokens”的表，此表带有以下列：“user identifier”(varchar(100))、“accesstoken”(varchar(100))、“refreshtoken”(varchar(100)) 和“expirytime”(bigint)
④保存到自定义数据库

'mysql_username':'',
'mysql_password':'',
'mysql_port':'3306',

3.demo演示

import zcrmsdk
import logging
import httpx

class Request:
    def __init__(self):
        self.headers = {
            "User-Agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:56.0) Gecko/20100101 Firefox/56.0",
            "Authorization": "Zoho-oauthtoken 1000.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        }

    def get(self, url, headers={}):
        logging.debug(f"收到GET请求,URL地址{url}")
        self.headers.update(headers)
        return httpx.get(url, headers=self.headers).json()

    def post(self, url, json_data, files=None, headers={}):
        logging.debug(f"收到POST请求,URL地址{url}，Data数据{json_data}")
        self.headers.update(headers)
        return httpx.post(url=url, json=json_data, files=files, headers=headers).json()

config = {
    # 基于web的应用尝试
    # "client_id": "1000.xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    # "client_secret": "964xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    # 基于self的应用尝试
    "client_id": "1000.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "client_secret": "e5e3xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "redirect_uri": "https://hao.360.com/?a1004",
    "accounts_url": "https://accounts.zoho.com.cn",
    "token_persistence_path": ".",
    "access_type": "offline",
    "applicationLogFilePath": "./persistence",
    "sandbox": "False",
    "currentUserEmail": "[email protected]",
    "apiBaseUrl": "https://www.zohoapis.com.cn",
    "apiVersion": "v2",
}
# 初始化
zcrmsdk.ZCRMRestClient.initialize(config)
oauth_client = zcrmsdk.ZohoOAuth.get_client_instance()
# 授权令牌grant_token
grant_token = "1000.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
oauth_tokens = oauth_client.generate_access_token(grant_token)
accessToken, refreshToken = oauth_tokens.accessToken, oauth_tokens.refreshToken

# 通过刷新令牌获得新的访问令牌
# user_identifier = "[email protected]"
# oauth_tokens = oauth_client.generate_access_token_from_refresh_token(refreshToken, user_identifier)

五、访问令牌Token的获取与撤销

1.两种方式获取token，URL与Code

• Code代码获取Token已在本章4.3演示，即accessToken值
• URL获取访问令牌Token
  ①授权url规则{Accounts_URL}/oauth/v2/token，路径参数有grant_type、client_id,、client_secret、redirect_uri、code
  ②释意，grant_type固定值authorization_code；client_id客户端ID；client_secret客户端密钥；redirect_uri回调(重定向)URL；code授权令牌grant_token
  ③发起POST请求"https://accounts.zoho.com.cn/oauth/v2/token?grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&redirect_uri={redirect_uri}&code={grant_token}"
  
• 刷新用以获取访问令牌的地址，POST请求{Accounts_URL}/oauth/v2/token?refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}&grant_type=refresh_token
• 撤销访问令牌的地址，POST请求{Accounts_URL}/oauth/v2/token/revoke?token={refresh_token}

六、访问zoho的数据

1.python函数为什么无法访问CRM内部数据？

可以看到，请求头里需要的token，转换在函数中无法携带，认证无法通过

七、关于作用域的问题

ZohoCRM.org.ALL,
ZohoCRM.users.ALL,
ZohoCRM.Bulk.ALL,
ZohoCRM.Modules.ALL,
ZohoCRM.modules.notes.ALL
ZohoCRM.settings.all,
ZohoCRM.settings.modules.all,
ZohoCRM.settings.fields.all,
ZohoCRM.settings.layouts.all,
ZohoCRM.settings.related_lists.all,

.
.
.
研究明白在细说！目前来说的话呢，哪个能访问就用哪个，哈哈哈..

八、引用

• 中文版
• 中文高级版
• 英文版
• GitHub版
• 其它版
• Zoho社区解决问题
• 另一种途径接入未尝试

九、结束