Zoho CRM 的 Python SDK

注册 Zoho 客户端

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

访问页面：https://accounts.zoho.com.cn/developerconsole。
点击“添加客户端 ID”。
输入客户端名称、客户端域和重定向 URI。
选择基于 Web 作为客户端类型。
点击“创建”
将立即创建和显示客户端应用。
可以通过点击“选项”→“编辑”来找到新注册应用的客户端 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_secret 和 redirect_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) 生成自授权的授权令牌。

请访问 https://accounts.zoho.com.cn/developerconsole
点击要对其授权客户端的选项 → 独立客户端。
在“作用域”字段中输入您要授权的一个或多个（各项之间用逗号分隔）有效 Zoho CRM 作用域，然后选择到期日期。输入“aaaserver.profile.READ”作用域及 Zoho CRM 作用域。
复制授权令牌以进行备份。
借助创建带有以下 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
复制刷新令牌以进行备份。

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

生成访问令牌

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

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

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

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

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)。设置字段值时，请确保所设置值是您要设置字段的相应数据类型。

响应处理

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

DownloadFile 和 downloadPhoto 返回 FileAPIResponse 而不是 APIResponse。

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

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

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

response_headers 显示当天和窗口的余下 API 计数；以及当前窗口重置的经历时间。
info - 实际数据及 API 提供的任何其他信息。
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