Python SDK

Zoho CRM 的 Python SDK

Zoho CRM API 的 Python SDK 是 Zoho CRM API 的包装器。因此,从您的客户端 python 应用程序调用 Zoho CRM API 只是方法调用。

Python SDK 支持单用户认证和多用户认证。

注册 Zoho 客户端

因为 Zoho CRM API 是使用 OAuth2 标准认证的,所以应该向 Zoho 注册您的客户端应用。按照下面步骤注册您的应用:

  1. 访问页面:https://accounts.zoho.com.cn/developerconsole。
  2. 点击“添加客户端 ID”。
  3. 输入客户端名称、客户端域和重定向 URI。
  4. 选择基于 Web 作为客户端类型。
  5. 点击“创建
  6. 将立即创建和显示客户端应用。
  7. 可以通过点击“选项”→“编辑”来找到新注册应用的客户端 ID 和客户端密钥。
    (“选项”在右侧显示为三个点的图标)。

设置

可以通过“pip”安装 Python SDK。pip 是 Python 中用于依赖项管理的一个工具。该 SDK 对客户端应用有以下要求:

  • 客户端应用必须使用 Python 2.7
    • https://www.python.org/downloads/
  • 客户端应用必须已安装 python requests
    • http://docs.python-requests.org/en/master/user/install/
  • 必须通过 pip 安装 Python SDK。
  • 必须在您的应用程序启动时调用 ZCRMRestClient.initialize() 方法
  • MySQL 应在同一台机器的默认端口 3306 运行。
    • 数据库名称应该为“zohooauth”。
    • 必须有一个名为“oauthtokens”的表,此表带有以下列:“user identifier”(varchar(100))、“accesstoken”(varchar(100))、“refreshtoken”(varchar(100)) 和“expirytime”(bigint)。

如果 oauth_configuration.properties 文件中提供了 token_persistence_path,那么持久化处理只保存在该文件中。在此情况下,不需要 MySQL。

在所提到的 token_persistence_path 中创建名为 zcrm_oauthtokens.pkl 的空文件。

通过 pip 安装 SDK

安装 pip(如果未安装)

请参阅以下文档来安装 pip

https://pip.pypa.io/en/stable/installing/

安装 SDK

以下介绍如何安装 Python SDK

  • 运行以下命令:

    pip install zcrmsdk

将安装 Python SDK,并将在 Python 的安装目录中创建名为“zcrmsdk”的包(例如,“/Library/Python/2.7/site-packages”)。

升级 SDK

  • 运行以下命令将 Python SDK 升级至最新版本。

    pip install --upgrade zcrmsdk

配置

OAuth 客户端信息将作为属性文件提供给 SDK。在 SDK 中,我们已提供了配置文件 (oauth_configuration.properties)。请在该文件中设置相应的值。可以在“zcrmsdk/resources”下找到该文件。

请填写以下键的值。

根据您的域(EU 或 CN),更改 accounts_url 的值。默认值设置为 US 域。

client_id=
client_secret=
redirect_uri=
accounts_url=https://accounts.zoho.com.cn/
token_persistence_path=

  • client_id、client_secretredirect_uri 是注册 Zoho 客户端后获取的 OAuth 客户端配置。
  • access_type 必须设置为 offline 的唯一原因是 Python SDK 目前不支持在线 OAuth 客户端。
  • token_persistence_path 是文件形式的 OAuth 相关令牌。如果设置了此项,那么不需要数据库来进行保存。持久化处理只在文件中进行。

在 configuration.properties 中对键“applicationLogFilePath”添加绝对路径以存储日志。可以在“zcrmsdk/resources”下找到该文件。该文件将记录使用 Python SDK 期间发生的异常。

请填写以下键的值。如果未提供日志路径,那么不会存储日志,但可以在控制台中查看它们。

applicationLogFilePath=

要对 sandbox 帐户进行 API 调用,请将以下键的值更改为 true。默认情况下,此值为 false。

sandbox=true

如果您的应用程序只需要单用户认证,那么您必须在 configurations.properties 文件中按以下方式设置用户邮箱地址。

currentUserEmail=user@email.com

要使用多用户认证,您需要在当前线程中将用户邮箱地址设置为属性。

threading.current_thread().__setattr__('current_user_email','user@email.com')

也可以对单用户认证使用以上方法,但建议通过在 configuration.properties 文件中设置邮箱地址进行。

如果未在当前线程中设置用户邮箱地址,那么 SDK 要求它包含在 configuration.properties 文件中。如果未使用以上任何方式设置用户邮箱地址,那么 Python SDK 将抛出异常。

初始化

在定义了 OAuth 配置文件之后,就可以对应用进行初始化了。

生成自授权的授权和刷新令牌

对于独立客户端应用,应通过 Zoho 开发者控制台 (https://accounts.zoho.com.cn/developerconsole) 生成自授权的授权令牌。

  1. 请访问 https://accounts.zoho.com.cn/developerconsole
  2. 点击要对其授权客户端的选项独立客户端
  3. 在“作用域”字段中输入您要授权的一个或多个(各项之间用逗号分隔)有效 Zoho CRM 作用域,然后选择到期日期。输入“aaaserver.profile.READ”作用域及 Zoho CRM 作用域。
  4. 复制授权令牌以进行备份。
  5. 借助创建带有以下 URL 的 POST 请求,通过授权令牌生成刷新令牌

    https://accounts.zoho.com.cn/oauth/v2/token?code={grant_token}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}&grant_type=authorization_code

  6. 复制刷新令牌以进行备份。

请注意,所生成授权令牌仅在您生成它时选择的约定期限内有效。因此,应在该时间范围内生成访问令牌和刷新令牌。

生成访问令牌

可以通过授权令牌或刷新令牌生成访问令牌。按照下面任意一种方法操作就可以了。

通过授权令牌生成访问令牌

应该通过您的主类执行以下代码片段以获取访问令牌。

请将所生成的授权令牌粘贴到所显示的字符串中。它是一次性过程。

ZCRMRestClient.initialize()
oauth_client = ZohoOAuth.get_client_instance()
grant_token="paste_grant_token_here"
oauth_tokens = oauth_client.generate_access_token(grant_token)

通过刷新令牌生成访问令牌

应该通过您的主类执行以下代码片段以获取访问令牌。

请将所生成的刷新令牌粘贴到所显示的字符串中。它是一次性过程。

ZCRMRestClient.initialize()
oauth_client = ZohoOAuth.get_client_instance()
refresh_token="paste_refresh_token_here"
user_identifier="provide_user_identifier_like_email_here"
oauth_tokens = oauth_client.generate_access_token_from_refresh_token(refresh_token,user_identifier)

成功执行以上代码片段后,所生成的访问令牌和刷新令牌将通过持久性处理类保存下来。

保存 OAuth 令牌后,后续 API 令牌将使用所保存的访问令牌和刷新令牌。必要时,Python SDK 将负责使用刷新令牌来刷新访问令牌。

启动应用

每次启用您的客户端应用时,Python SDK 需要调用以下代码行。

ZCRMRestClient.initialize()

以上代码行初始化该 SDK 后,您可以使用该 SDK 的任意 API 来获取相应结果。

使用 SDK

在客户端应用 Python 文件中您想要使用 Python SDK 的位置添加以下行。

import zcrmsdk

通过此行,您可以访问 Python SDK 的所有功能。

要访问模块或类,请使用 zcrmsdk.ClassName

类层次结构

所有 Zoho CRM 实体建模为具有适用于该特定实体的类、方法和实例变量的模块。ZCRMRestClient 是 Python SDK 的基本类。ZCRMRestClient 有一些方法可用于获取各种其他 Zoho CRM 实体的实例。它包含在 RestClient 模块中。

SDK 的类关系和层次结构遵循 Zoho CRM 中的实体层次结构。各种 Zoho CRM 实体的类层次结构如下所示:

ZCRMRestClient
   -ZCRMOrganization
    -ZCRMUser
     -ZCRMUserTheme
     -ZCRMUserCustomizeInfo
    -ZCRMRole
    -ZCRMProfile
     -ZCRMPermission
     -ZCRMProfileSection
      -ZCRMProfileCategory
   -ZCRMModule
    -ZCRMLayout
     -ZCRMSection
      -ZCRMField
      -ZCRMPickListValue
      -ZCRMLookupField
     -ZCRMLeadConvertMapping
      -ZCRMLeadConvertMappingField
    -ZCRMCustomView
     -ZCRMCustomViewCategory
     -ZCRMCustomViewCriteria
    -ZCRMRelatedListProperties
    -ZCRMModuleRelatedList
    -ZCRMRecord
     -ZCRMNote
     -ZCRMAttachment
     -ZCRMInventoryLineItem
      -ZCRMTax
     -ZCRMEventParticipant
     -ZCRMPriceBookPricing
     -ZCRMModuleRelation
     -ZCRMJunctionRecord
     -ZCRMTrashRecord

按此层次结构中所示,每个实体类有一些实例变量用于获取它自己的属性及通过 API 调用获取其直接子实体的数据。

例如,Zoho CRM 模块 (ZCRMModule) 对象有一些实例变量用于获取模块的属性(例如,显示名称,模块 ID 等等),它还有一些实例变量用于获取其所有子对象(例如,ZCRMLayout)。

实例化对象

遵循完整类层次结构(从顶部开始)来获取位于较低级别的实体数据并非始终有效,因为这会涉及到在每个级别进行 API 调用。为了解决此问题,每个实体类将具有用于获取自己的虚拟对象的 get_instance() 方法和用于获取其子实体的虚拟对象的实例变量。

请注意,get_instance() 方法不会填写任何属性,因为它不会触发 API 调用。它仅返回一个虚拟对象,该对象仅应用于访问该类的非静态方法。

总的来说,

  • ZCRMRestClient.get_module(“Contacts”) 将返回实际“联系人”模块,它包含通过 API 调用填写的“联系人”模块的所有属性。
  • ZCRMRestClient.get_module_instance(“Contacts”) 将返回虚拟 ZCRMModule 对象,此对象将引用“联系人”模块,不填写任何属性,因为此对象不会进行 API 调用。

因此,要从模块获取记录,您不必一直从 ZCRMRestClient 启动。您可以使用 ZCRMModule.get_instance() 获取 ZCRMModule 实例,然后从所创建的实例调用它的非静态 get_records() 方法。这可以避免本来被触发以填充 ZCRMModule 对象的 API 调用。

访问记录属性

因为记录属性在模块中是动态的,所以我们仅给出常规字段(例如,created_time、created_by、owner 等等)作为 ZCRMRecord 的默认属性。所有其他记录属性在 ZCRMRecord 对象中以字典形式提供。

要访问某个记录的各个字段值,请使用所提供的 getter 和 setter 方法。记录属性字典的键为模块字段的 API 名称。所有模块中的所有字段的 API 名称位于以下位置:设置 → 扩展和 API → API → CRM API → API 名称。

要获取字段值,请使用 record.get_field_value(field_api_name)。要设置字段值,请使用 record.set_field_value(field_api_name,new_value)。设置字段值时,请确保所设置值是您要设置字段的相应数据类型。

响应处理

APIResponseBulkAPIResponse 是 Zoho CRM API 响应的包装器对象。所有 API 调用方法将返回其中一个对象。

DownloadFiledownloadPhoto 返回 FileAPIResponse 而不是 APIResponse。

搜寻单个实体的方法将返回 APIResponse 对象,搜寻实体列表的方法将返回 BulkAPIResponse 对象。

使用实例变量“data”可以单独从响应包装器对象中获取实体数据。APIResponse.data 将返回单个 Zoho CRM 实体对象,BulkAPIResponse.data 将返回 Zoho CRM 实体对象列表。

这些响应包装器对象具有以下属性而不是数据:

  1. response_headers 显示当天和窗口的余下 API 计数;以及当前窗口重置的经历时间。
  2. info - 实际数据及 API 提供的任何其他信息。
  3. bulk_entity_response(EntityResponse 实例的列表) - 批量 API 中各个实体的状态。例如,在插入记录中,API 可能因为某些记录而部分失效。此数组给出各个记录的创建状态。

异常

所有意外行为(例如,故障 API 响应、SDK 异常)由 Python SDK 处理,并仅作为单个异常抛出 - ZCRMException。因此,在客户端应用代码中单独捕获此异常已经足够了。

类及其实例变量

模块名称 类名 实例变量 方法
RestClient ZCRMRestClient  
  • get_instance()
  • initialize()
  • get_all_modules()
  • get_module(module_api_name)
  • get_organization_instance()
  • get_module_instance(module_api_name)
  • get_record_instance(module_api_name,entity_id)
  • get_current_user()
  • get_organization_details()
Org ZCRMOrganization
  • org_id
  • alias
  • primary_zuid
  • zgid
  • primary_email
  • website
  • mobile
  • phone
  • employee_count
  • description
  • time_zone
  • iso_code
  • currency_locale
  • currency_symbol
  • street
  • state
  • city
  • country
  • zip_code
  • country_code
  • fax
  • mc_status
  • is_gapps_enabled
  • paid_expiry
  • trial_type
  • trial_expiry
  • is_paid_account
  • paid_type
  • get_instance(org_name=None,org_id=None)
  • get_user(self,user_id)
  • get_current_user()
  • get_all_users()
  • get_all_active_users()
  • get_all_deactive_users()
  • get_all_confirmed_users()
  • get_all_not_confirmed_users()
  • get_all_deleted_users()
  • get_all_active_confirmed_users()
  • get_all_admin_users()
  • get_all_active_confirmed_admin_users()
  • get_all_profiles()
  • get_profile(profile_id)
  • get_all_roles()
  • get_role(role_id)
  • create_user(user_instance)
  • update_user(user_instance)
  • delete_user(user_id)
操作 ZCRMModule
  • api_name
  • is_convertable
  • is_creatable
  • is_editable
  • is_deletable
  • web_link
  • singular_label
  • plural_label
  • modified_by
  • modified_time
  • is_viewable
  • is_api_supported
  • is_custom_module
  • is_scoring_suppored
  • id
  • module_name
  • business_card_field_limit
  • business_card_fields
  • profiles
  • display_field_name
  • display_field_id
  • related_lists
  • layouts
  • fields
  • related_list_properties
  • properties
  • per_page
  • search_layout_fields
  • default_territory_name
  • default_territory_id
  • default_custom_view_id
  • default_custom_view
  • is_global_search_supported
  • sequence_number
  • get_instance(module_apiname)
  • get_record(entityID)
  • get_records(cvid= None,sort_by=None,sort_order=None,page=0,per_page=200)
  • create_records(record_ins_list)
  • upsert_records(record_ins_list)
  • update_records(entityid_list,field_api_name,value)
  • delete_records(entityid_list)
  • get_all_deleted_records()
  • get_recyclebin_records()
  • get_permanently_ deleted_records()
  • search_records(search_word,page=0,per_page=200)
  • get_all_fields()
  • get_field(field_id)
  • get_all_layouts()
  • get_layout(layout_ id)
  • get_all_customviews()
  • get_customview(customview_id)
  • get_all_relatedlists ()
  • get_relatedlist(relatedlist_id)
  • update_module_settings()
  • update_customview(customview_instance)
ZCRMRecord
  • module_api_name
  • entity_id
  • line_items
  • lookup_label
  • owner
  • created_by
  • modified_by
  • created_time
  • modified_time
  • field_data
  • properties
  • participants
  • price_details
  • layout
  • tax_list
  • last_activity_time
  • get_instance(module_apiname,entity_id=None)
  • set_field_value(key,value)
  • get_field_value(key)
  • add_line_item(line_item)
  • get()
  • create()
  • update()
  • delete()
  • convert(potential_record=None,assign_to_user=None)
  • upload_attachment(file_path)
  • upload_link_as_attachment(link_url)
  • download_attachment(attachment_id)
  • delete_attachment(attachment_id)
  • upload_photo(file_path)
  • download_photo()
  • delete_photo()
  • add_relation(junction_record)
  • remove_relation(junction_record)
  • add_note(note_ins)
  • update_note(note_ins)
  • delete_note(note_ins)
  • get_notes(sort_by=None,sort_order=None,page=1,per_page=20)
  • get_attachments(page=1,per_page=20)
  • get_relatedlist_records(relatedlist_api_name,sort_by=None,sort_order=None,page=1,per_page=20)
ZCRMInventoryLineItem
  • product
  • id
  • list_price
  • quantity
  • description
  • total
  • discount
  • discount_percentage
  • total_after_discount
  • tax_amount
  • net_total
  • delete_flag
  • line_tax
  • get_instance(zcrm_record_instance)
ZCRMTax
  • name
  • percentage
  • value
  • get_instance(name)
ZCRMEventParticipant
  • id
  • type
  • email
  • name
  • is_invited
  • status
  • get_instance(participant_type,participant_id)
ZCRMPriceBookPricing
  • id
  • to_range
  • from_range
  • discount
  • get_instance(price_book_id)
ZCRMUser
  • id
  • name
  • signature
  • country
  • role
  • customize_info
  • city
  • name_format
  • language
  • locale
  • is_personal_account
  • default_tab_group
  • street
  • alias
  • theme
  • state
  • country_locale
  • fax
  • first_name
  • email
  • zip
  • decimal_separator
  • website
  • time_format
  • profile
  • mobile
  • last_name
  • time_zone
  • zuid
  • is_confirm
  • full_name
  • phone
  • dob
  • date_format
  • status
  • get_instance(user_id=None,name=None)
ZCRMUserCustomizeInfo
  • notes_desc
  • is_to_show_right_panel
  • is_bc_view
  • is_to_show_home
  • is_to_show_detail_view
  • unpin_recent_item
  • get_instance()
ZCRMUserTheme
  • normal_tab_font_color
  • normal_tab_background
  • selected_tab_font_color
  • selected_tab_background
  • get_instance()
ZCRMRole
  • name
  • id
  • reporting_to
  • label
  • is_admin
  • get_instance(role_id,role_name=None)
ZCRMLayout
  • id
  • name
  • created_time
  • modified_time
  • is_visible
  • modified_by
  • accessible_profiles
  • created_by
  • sections
  • status
  • convert_mapping
  • get_instance(layout_id)
ZCRMAttachment
  • id
  • parent_record
  • file_name
  • file_type
  • size
  • owner
  • created_by
  • created_time
  • modified_by
  • modified_time
  • parent_module
  • attachment_type
  • parent_name
  • parent_id
  • get_instance(parent_record,attachment_id=None)
ZCRMCustomView
  • id
  • module_api_name
  • display_value
  • is_default
  • name
  • system_name
  • sort_by
  • category
  • fields
  • favorite
  • sort_order
  • criteria_pattern
  • criteria
  • categories
  • is_off_line
  • get_instance(custom_view_id,module_apiname=None)
ZCRMCustomViewCategory
  • display_value
  • actual_value
  • get_instance()
ZCRMCustomViewCriteria
  • comparator
  • field
  • value
  • get_instance()
ZCRMField
  • api_name
  • is_custom_field
  • lookup_field
  • convert_mapping
  • is_visible
  • field_label
  • length
  • created_source
  • default_value
  • is_mandatory
  • sequence_number
  • is_read_only
  • is_unique_field
  • is_case_sensitive
  • data_type
  • is_formula_field
  • is_currency_field
  • id
  • picklist_values
  • is_auto_number
  • is_business_card_supported
  • field_layout_permissions
  • decimal_place
  • precision
  • rounding_option
  • formula_return_type
  • formula_expression
  • prefix
  • suffix
  • start_number
  • json_type
  • get_instance(api_name)
ZCRMJunctionRecord
  • id
  • api_name
  • related_data=dict()
  • get_instance(api_name,record_id)
  • set_related_data(key,value)
  • get_related_data()
ZCRMLeadConvertMapping
  • id
  • name
  • fields
  • get_instance(name ,converted_id)
ZCRMLeadConvertMappingField
  • id
  • api_name
  • field_label
  • is_required
  • get_instance(api_name,field_id)
ZCRMLookupField
  • api_name
  • display_label
  • module
  • id
  • get_instance(api_name)
ZCRMModuleRelatedList
  • api_name
  • module
  • display_label
  • is_visible
  • name
  • id
  • href
  • type
  • get_instance(api_name)
ZCRMModuleRelation
  • parent_record
  • parent_module_api_name
  • junction_record
  • api_name
  • label
  • id
  • is_visible
  • get_instance(parentmodule_apiname_or_parentrecord,related_list_apiname_or_junction_record)
  • get_records(sort_by_field=None,sort_order=None,page=1,per_page=20)
  • upload_attachment(file_path)
  • upload_link_as_attachment(link_url)
  • download_attachment(attachment_id)
  • delete_attachment(attachment_id)
  • add_relation()
  • remove_relation()
  • add_note(zcrm_note_ins)
  • update_note(zcrm_note_ins)
  • delete_note(zcrm_note_ins)
  • get_notes(sort_by,sort_order,page,per_page)
  • get_attachments(page,per_page)
ZCRMNote
  • id
  • parent_record
  • title
  • content
  • owner
  • created_by
  • created_time
  • modified_by
  • modified_time
  • attachments
  • size
  • is_voice_note
  • parent_module
  • parent_name
  • parent_id
  • get_instance(parent_record,note_id=None)
ZCRMPermission
  • id
  • name
  • display_label
  • module
  • is_enabled
  • get_instance(permission_name,permission_id)
ZCRMPickListValue
  • display_value
  • sequence_number
  • actual_value
  • maps
  • get_instance()
ZCRMProfile
  • name
  • id
  • is_default
  • created_time
  • modified_time
  • modified_by
  • description
  • created_by
  • category
  • permissions
  • sections
  • get_instance(profile_id,profile_name=None)
ZCRMProfileCategory
  • name
  • module
  • display_label
  • permission_ids
  • get_instance(profile_category_name)
ZCRMProfileSection
  • name
  • categories
  • get_instance(section_name)
ZCRMRelatedListProperties
  • sort_by
  • sort_order
  • fields
  • get_instance()
ZCRMSection
  • name
  • display_name
  • column_count
  • sequence_number
  • fields
  • get_instance(section_name)
ZCRMTrashRecord
  • id
  • type
  • display_name
  • deleted_time
  • created_by
  • deleted_by
  • get_instance(entity_type,entity_id=None)
Response APIResponse
  • response_json
  • response_headers
  • status_code
  • data
  • status
  • code
  • message
  • details
 
BulkApiRepsponse
  • response_json
  • response_headers
  • status_code
  • data
  • info(ResponseInfo instance)
  • bulk_entity_response(EntityResponse instances as list)
  • status
  • code
  • message
  • details
 
EntityRepsponse
  • data
  • status
  • code
  • message
  • details
  • upsert_action
  • upsert_duplicate_field
 
RepsponseInfo
  • is_more_records
  • page
  • per_page
  • count
 
FileApiRepsponse
  • response
  • status_code
  • file_name
  • response_headers
  • status
  • code
  • message
  • details
 
CLException ZCRMException
  • URL
  • status_code
  • error_content
  • error_message
  • error_code
  • error_details
 

分享此文章:Facebook Twitter

还是没有找到您要寻找的内容?

写信给我们:support-crm@zohocorp.com.cn