迁移到V2.0—概述

    2018年12月31日,Zoho CRM API v1被弃用。因此,要继续访问Zoho CRM,您需要迁移到API v2。

    为什么API V2更好?

    1. 提升了API调用限制 - Zoho CRM的超级版最高可调用2,000,000次,然而对于企业版API v1.0的最大限制是25,000次

    2. 易于解析 - 输入和响应的简单JSON格式

    3. 安全性提高 - 支持OAuth 2.0认证协议

    4. API名称 - 取代了显示标签

    5. 通知API - 数据变更,立即推送通知

    6. 批量API - 一次最多能获取200,000条记录或插入25,000条记录 

    7. SDK - 支持服务器端、移动端以及Javascript SDK

    用于开发人员的迁移清单

    1. 检查您是否需要迁移用户访问令牌或使用新权限重新验证。

    2. 熟悉新的v2语法。API v2.0只接受JSON输入。

    3. 熟悉字段属性和字段格式的更改。帮助文档中也提到了这一点 : 区别 - v1 和 v2

    4. 看一下v1中可用的API方法,以及它们在v2中的不同之处这里

    5. 更新应用程序中处理的错误,以将正确的状态码运用到v2错误。

    6. 看一下集成任务和如何在您的deluge脚本中使用v2 API,详情请点击这里

    以下是从v1和v2迁移时需要注意的方面,每一节都详细解释了两个版本之间的差异。

    1. 认证
    2. 基地址(Base URL)
    3. 输入格式和API名称
    4. API响应
    5. 集成任务
    6. 限制
    7. 令牌迁移

    认证

    • v1
    • v2
     

    v1

    https://crm.zoho.com.cn/crm/private/xml/Leads/insertRecords?
    														newFormat=1
    														&authtoken=Auth Token
    														&scope=crmapi
    														&xmlData=<data>

    v1 API使用auth token来进行认证。这个auth token在输入中传递参数。

    v2

    地址: https://www.zohoapis.com.cn/crm/v2/Leads
    														方法: GET
    														头: Authorization=Zoho-oauthtoken {access_token}

    v2 API使用 Oauth 2.0协议进行认证。这里,访问令牌会在请求头中传递。OAuth 2.0协议运用作用域来仅对选定资源提供访问权限,进而提高安全性。

    基地址(Base URL)

    • v1
    • v2
     

    v1

    https://crm.zoho.com.cn/crm/private/xml/Leads/getRecords?authtoken=AuthToken&scope=crmapi

    这里,https://crm.zoho.com.cn/crm/private/是基地址。

    v2

    地址: https://www.zohoapis.com.cn/crm/v2/Leads
    														方法: GET
    														头: Authorization=Zoho-oauthtoken {oauth_token}

    这里,https://www.zohoapis.com.cn/crm/v2/是用于中国数据中心的特定于域的基地址。请参阅多数据中心以获取有关特定于域的API地址的更多详细信息。

    输入格式和API名称

    • v1
    • v2
     

    v1

    curl -X POST
    														'https://crm.zoho.com.cn/crm/private/xml/Leads/insertRecords?newFormat=1&authtoken=***'
    														-d 'xmlData=<Leads><row no="1"><FL val="Lead Source">Web Download</FL><FL val="Company">Your Company</FL><FL val="First Name">Hannah</FL><FL val="Last Name">Smith</FL></row></Leads>'
    1. v1 API在请求中使用字段标签。在上面显示的'创建记录'示例中,线索来源公司名字以及姓氏是线索模块中的字段标签。

    2. v1 API只接受xml格式的输入。

    请参阅API方法来获取有关APIv1方法和APIv2方法区别的更多详细信息。

    v2

    curl "https://www.zohoapis.com.cn/crm/v2/Leads"
    														-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
    														-d "@newlead.json"
    														-X POST{
    														"data": [
    														    {
    														        "Company": "Zylker",
    														        "Last_Name": "Daly",
    														        "First_Name": "Paul",
    														        "Email": "p.daly@zylker.com",
    														        "Lead_Source": "Chat"
    														    }]}
    1. 所有v2 API都使用API名称而不是字段标签。在上面显示的‘创建记录’示例中,Company、Last_Name、First_Name和Lead_Source是线索模块中的字段API名称。

    2. v2 API只接受JSON格式的输入。

    请参阅API方法来获取有关APIv1方法和APIv2方法区别的更多详细信息。

    API响应

    • v1
    • v2
     

    v1

    <?xml version="1.0" encoding="UTF-8" ?>
    														<response uri="/crm/internal/xml/Leads/insertRecords">
    														 <result>
    														 <message>Record(s) added successfully</message>
    														 <recorddetail>
    														 <FL val="Id">525508000003633001</FL>
    														 <FL val="Created Time">2019-06-27 19:00:08</FL>
    														 <FL val="Modified Time">2019-06-27 19:00:08</FL>
    														 <FL val="Created By">
    														 <![CDATA[Patricia Boyle]]>
    														 </FL>
    														 <FL val="Modified By">
    														 <![CDATA[Patricia Boyle]]>
    														 </FL>
    														 </recorddetail>
    														 </result>
    1. v1 API返回xml、JSON或CSV格式的响应,所需格式在请求地址中指定为 "https://crm.zoho.com.cn/crm/private/xml/Leads/insertRecords..."

    2. 这里显示的示例是对创建记录请求的响应。

    v2

    {
    														"data": [
    														  {
    														    "code": "SUCCESS",
    														    "details": {
    														      "Modified_Time": "2019-05-02T11:17:33+05:30",
    														      "Modified_By": {
    														        "name": "Patricia Boyle",
    														        "id": "554023000000235011"
    														      },
    														      "Created_Time": "2019-05-02T11:17:33+05:30",
    														      "id": "554023000000527002",
    														      "Created_By": {
    														        "name": "Patricia Boyle",
    														        "id": "554023000000235011"
    														      }
    														    },
    														    "message": "record added",
    														    "status": "success"
    														  }
    1. 所有v2 API响应都是JSON格式的,响应包含的键是相应模块的API名称。

    2. v2 API只返回JSON或CSV格式的响应。

    请参阅API方法来获取有关APIv1方法和APIv2方法区别的更多详细信息。

    集成任务

    • v1
    • v2
     

    v1

    1. v1集成任务的语法在服务名称之后包含“v1”。

    2. 它们使用 "yyyy-mm-dd hh:mm:ss" 日期和时间格式。

    3. 您只能够通过集成任务来触发工作流规则。

    4. 更新多选查找字段只接受字符串中的值。

    欲了解更多信息,请参阅 集成任务 - 迁移到v2

    v2

    1. v2集成任务的语法中不包含版本号。

    2. 他们使用ISO时间和日期格式。

    3. 您可以通过集成任务触发工作流、蓝图和审批规则。

    4. 更新多选查找字段接受列表中的值。

    欲了解更多信息,请参阅 集成任务 - 迁移到v2

    限制

    • v1
    • v2
     

    v1

    1. v1 API对于企业版的API限制是25000个请求/天/机构或每个用户许可500个请求,以较低者为准。

    2. PST时区被用来计算限制,请求将在00:00 AM PST重置。

    欲了解更多信息,请参阅API限制

    v2

    1. V2 API使用并发限制来计算基于版本的API限制。这些限制在调用开始后有一个24小时滚动窗口。

    2. 根据CRM版本的不同,根据您进行的API调用的类型,将从总调用次数中扣除相应次数。

    3. v2 API还使用并发和子并发限制来限制在任何给定的时刻每个应用程序同时激活的最大调用次数。

    4. 企业版的v2 API限制为1,000,000次,超级版为2,000,000次

    5. 从调用开始计算,API调用限制有一个24小时的窗口滚动。

    6. V2 API还基于并发性来使用调用次数

    欲了解更多信息,请参阅API限制

     

    令牌迁移

    迁移API帮助您从现有的auth token获得访问权并刷新令牌。
    2种类型的迁移API是

    1. 基于重定向的应用程序迁移

    2. 为自客户端应用程序进行迁移

    • 基于重定向
    • 自客户端
     

    基于重定向的应用程序

    如果应用程序有多个用户,并且您获取了他们的用户名和密码以生成auth token,或者如果用户输入了他们的auth token,请使用此API。
    前提条件:

    1. 在访问此API之前,必须写邮件到support@zohocorp.com.cn来共享您到客户端ID(从开发人员控制台获得)、auth token、auth token作用域和所需的OAuth作用域,以进行验证。

    欲了解更多信息,请参阅基于重定向的应用程序迁移

    自客户端应用程序

    如果您的应用程序只使用一个auth token,请使用此API。
    欲了解更多信息,请参阅为自客户机应用程序进行迁移