PHP SDK

Zoho CRM 的 PHP SDK

目录

PHP SDK 是 Zoho CRM API 的包装器。因此，从您的客户端 PHP 应用程序调用 Zoho CRM API 只是函数调用。它支持单用户认证和多用户认证。

注册 Zoho 客户端

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

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

设置

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

  • 客户端应用必须使用 PHP 5.6 或以上版本，并且已启用 curl 扩展。
  • 必须通过 composer 将 PHP SDK 安装至客户端应用。
  • 启动应用时，必须调用 ZCRMRestClient::initialize() 函数。
  • MySQL 应在同一台机器的默认端口 3306 运行。
  • 数据库名称应该为“zohooauth”。
  • 必须有一个名为“oauthtokens”的表，此表带有以下列：“useridentifier”(varchar(100))、“accesstoken”(varchar(100))、“refreshtoken”(varchar(100)) 和“expirytime”(bigint)。

如果 oauth_configuration.properties 文件中提供了 token_persistence_path，那么持久化仅包含在该文件中。在这种情况下，不需要 MySQL。在前面提到的 token_persistence_path 中创建名为 zcrm_oauthtokens.txt 的空文件。

通过 composer 安装 PHP SDK

安装 composer（如果未安装）

运行以下命令以安装 composer

curl -sS https://getcomposer.org/installer | php

要使该 composer 可供全局访问，请遵循以下链接中的提示信息：

要在 mac/ linux 机器上安装 composer：

https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx

要在 windows 机器上安装 composer ：

https://getcomposer.org/doc/00-intro.md#installation-windows

安装 PHP SDK

以下显示如何安装该 SDK

  1. 访问客户端应用的工作空间
  2. 运行以下命令：

    composer require zohocrm/php-sdk

  3. 这样，就会安装 PHP SDK，并在您的客户端应用的工作空间中创建名为“vendor”的包。

配置

您的 OAuth 客户端信息将作为属性文件提供给 PHP SDK。在 PHP SDK 中，我们已提供了属性文件 (oauth_configuration.properties)，请在该文件中设置相应值。可以在“vendor/zohocrm/php-sdk/src/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 ，因为目前位置， PHP SDK 目前不支持在线 OAuth 客户端。
  • persistence_handler_class 是 ZohoOAuthPersistenceInterface 的实现，即 ZohoOAuthPersistenceHandler。
  • token_persistence_path 是文件形式的 OAuth 相关令牌。如果设置了此项，那么不需要数据库来进行保存。保存仅通过文件进行。

在客户端应用的机器上创建名为“ZCRMClientLibrary.log”的文件，并在 configuration.properties 中对键“applicationLogFilePath”指定所创建文件的绝对路径。可在“vendor/zohocrm/php-sdk/src/resources”下找到该文件。该文件将记录使用 PHP SDK 期间发生的异常。

请填写以下键值

applicationLogFilePath=

要对 sandobx 帐户进行 API 调用，请在 configurations.properties 文件中将以下键的值更改为 true。默认情况下，此值为 false。

sandbox=true

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

currentUserEmail=user@email.com

要使用多用户认证，您需要在 PHP 超级全局变量“$_SERVER”中按以下方式设置用户邮箱地址：

$_SERVER[‘user_email_id’]=“user@email.com”

也可以对单用户认证使用 $_SERVER 变量，但建议通过在 configuration.properties 文件中设置邮箱地址进行。

如果未将用户邮箱地址设置为超级全局变量，那么 SDK 要求它包含在 configuration.properties 文件中。如果未使用以上任何方式设置用户邮箱地址，那么 PHP 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();
$oAuthClient = ZohoOAuth::getClientInstance();
$grantToken = “paste_the_self_authorized_grant_token_here”;
$oAuthTokens = $oAuthClient->generateAccessToken($grantToken);

请注意，对于每个授权令牌，以上代码片段仅生效一次。成功执行以上代码片段后，所生成的访问令牌和刷新令牌将通过持久化处理类保存下来。

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

应该通过您的主类执行以下代码片段以获取访问令牌和刷新令牌。请将所生成的刷新令牌粘贴到下面显示的字符串中。这是一次性过程。

ZCRMRestClient::initialize();
$oAuthClient = ZohoOAuth::getClientInstance();
$refreshToken = "paste_the_refresh_token_here";
$userIdentifier = "provide_user_identifier_like_email_here";
$oAuthTokens = $oAuthClient->generateAccessTokenFromRefreshToken($refreshToken,$userIdentifier);

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

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

启动应用

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

ZCRMRestClient::initialize();

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

使用 PHP SDK

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

require ‘vendor/autoload.php’

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

类层次结构

所有 Zoho CRM 实体建模为具有适用于该特定实体的属性和函数的类。ZCRMRestClient 是 PHP SDK 的基本类。ZCRMRestClient 有一些函数可用于获取各种其他 Zoho CRM 实体的实例。

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 调用。为了解决此问题，每个实体类将具有用于获取自己的虚拟对象的 getInstance() 函数和用于获取其子实体的虚拟对象的函数。

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

总的来说，

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

因此，要从模块获取记录，不必从 ZCRMRestClient 开始。您可以使用 ZCRMModule::getInstance() 获取 ZCRMModule 实例，然后从所创建的实例调用它的非静态 getRecords() 函数。这可以避免本来被触发以填充 ZCRMModule 对象的 API 调用。

访问记录属性

因为记录属性在模块中是动态的，所以我们仅给出 createdTime、createdBy、owner 之类的字段作为 ZCRMRecord 的默认属性。所有其他记录属性在 ZCRMRecord 对象中以映射形式提供。

要访问某个记录的各个字段值，请使用所提供的 getter 和 setter 函数。记录属性映射的键为模块字段的 API 名称。所有模块中的所有字段的 API 名称位于以下位置：设置 → 应用市场 → API → CRM API → API 名称。

  • 要获取字段值，请使用 $record → getFieldValue($fieldAPIName);
  • 要设置字段值，请使用 $record → setFieldValue($fieldAPIName, $newValue);
    设置字段值时，请确保所设置的值为您要设置字段的相应数据类型。

响应处理

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

  • DownloadFile 和 downloadPhoto 返回 FileAPIResponse 而不是 APIResponse。
  • 搜寻单个实体的函数将返回 APIResponse 对象，搜寻实体列表的函数将返回 BulkAPIResponse 对象。
  • 使用 getData() 函数可单独从响应包装器对象获取实体数据。APIResponse → getData() 将返回单个 Zoho CRM 实体对象，BulkAPIResponse → getData() 将返回 Zoho CRM 实体对象列表。

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

  1. ResponseHeaders 显示当天和窗口的余下 API 计数；以及当前窗口重置的经历时间。
  2. ResponseInfo - 实际数据及 API 提供的任何其他信息。
  3. Array of EntityResponse(s) - 批量 API 中的各个实体的状态。例如，插入记录 API 可能因为几个记录而部分失败。此数组给出各个记录的创建状态。

异常

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

还没有找到您需要的内容？

请发送邮件给我们：support-crm@zohocorp.com.cn