walker-development/zoho-oauth-sdk

该包的最新版本（1.2.0）没有可用的许可信息。

Zoho CRM API SDK for Laravel

维护者

详细信息

github.com/WalkerDevelopment/zcrm-php-sdk

主页

源代码

安装: 17

依赖者: 0

建议者: 0

安全性: 0

星星: 0

关注者: 1

分支: 132

类型:sdk

1.2.0 2018-10-10 20:15 UTC

Requires

Requires (Dev)

Unknown License 0b0a73c07a7a9b33951c6bc81af06066020488fa

This package is auto-updated.

Last update: 2024-09-11 15:03:06 UTC

README

PHP SDK for Zoho CRM APIs提供Zoho CRM APIs的包装器。因此，从您的客户端应用程序调用Zoho CRM API只是一个方法调用。它支持单用户和多用户身份验证。

注册Zoho客户端

由于Zoho CRM API使用OAuth2标准进行认证，您应该将您的客户端应用程序注册到Zoho。要注册应用程序

  1. 访问此页面 https://accounts.zoho.com/developerconsole。
  2. 点击添加Client ID。
  3. 输入客户端名称、客户端域名和重定向URI，然后点击创建。
  4. 您的客户端应用程序已创建并显示。
  5. 通过点击选项 → 编辑可以找到新注册应用程序的Client ID和Client Secret。（选项是右上角的三个点图标）。

设置

PHP SDK可以通过composer安装。Composer是PHP中依赖管理的工具。SDK期望客户端应用程序提供以下内容。

客户端应用程序必须具有PHP 7.0或更高版本，并启用curl扩展。客户端库必须通过composer安装到客户端应用程序中。在应用程序启动时必须调用ZCRMRestClient::initialize()函数。

CREATE TABLE public.oauthtokens ( useridentifier character varying(100), accesstoken character varying(100), refreshtoken character varying(100), expirytime bigint, PRIMARY KEY (useridentifier) ).

数据库参数来自laravel的设置。

安装PHP SDK

以下是安装SDK的方法：导航到您的客户端应用程序的工作区，运行以下命令

composer require walker-development/zoho-oauth-sdk

因此，SDK将被安装，并在客户端应用程序的工作区中创建一个名为vendor的包。

配置

您的OAuth客户端详细信息应在ENV中设置。

请仅填写以下密钥。根据您的域（EU、CN），请更改zoho_accounts_url的值。默认值设置为US域

zoho_client_id= zoho_client_secret= zoho_redirect_uri= zoho_accounts_url=https://accounts.zoho.com

仅填写上述显示的密钥。zoho_client_id、zoho_client_secret和zoho_redirect_uri是您在注册Zoho客户端后获得的OAuth客户端配置。access_type必须设置为离线，因为SDK目前不支持在线OAuth客户端。persistence_handler_class是实现ZohoOAuthPersistenceInterface的实例。

要向沙箱帐户进行API调用，请在configurations.properties中将以下密钥的值更改为true。默认值为false

sandbox=true

如果您的应用程序只需要单用户身份验证，则必须在configurations.properties文件中将用户EmailId设置为以下内容

currentUserEmail=user@email.com

为了使用多用户身份验证，您需要将用户EmailId设置为PHP超级全局变量‘$_SERVER’中，如下所示

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

您还可以使用 $_SERVER 变量进行单用户身份验证，但建议在 configuration.properties 文件中设置电子邮件 ID。

如果您没有在全局超级变量中设置用户电子邮件，则 SDK 会从 configuration.properties 文件中获取它。如果在这两个地方都没有设置用户电子邮件，则 SDK 将抛出异常。

初始化

在定义 OAuth 配置文件后，应用程序将准备就绪以进行初始化。

生成自授权授权令牌

对于自客户端应用程序，自授权授权令牌应从 Zoho 开发者控制台（https://accounts.zoho.com/developerconsole）生成。

  1. 访问 https://accounts.zoho.com/developerconsole
  1. 单击“选项”→“客户端的自客户端”，为您希望授权的客户端。
  2. 在“作用域”字段中输入一个或多个（用逗号分隔）有效的 Zoho CRM 作用域，您希望授权，并选择过期时间。
  3. 复制授权令牌。
  4. 使用以下 URL 从授权令牌生成 refresh_token

https://accounts.zoho.com/oauth/v2/token?code={grant_token}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}&grant_type=authorization_code 这是一个 POST 请求

复制 refresh_token 以进行备份

请注意，生成的授权令牌仅在其生成时指定的期限内有效。因此，应在该时间内生成 refresh_token。

生成访问令牌

访问令牌可以由授权令牌或 refresh_token 生成。以下两种方法中的任何一种都足够。

从授权令牌获取访问令牌

以下代码片段应从您的主类中执行以获取访问令牌。请将复制的授权令牌粘贴到下面的字符串字面量中。这是一个一次性过程。

ZCRMRestClient::initialize(); $oAuthClient = ZohoOAuth::getClientInstance(); $grantToken = "paste_the_grant_token_here"; $oAuthTokens = $oAuthClient->generateAccessToken($grantToken);

从 refresh_token 获取访问令牌

以下代码片段应从您的主类中执行以获取访问令牌。请将复制的 refresh_token 粘贴到下面的字符串字面量中。这是一个一次性过程。

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

在上述代码片段成功执行后，生成的访问令牌和提供的 refresh_token 将通过我们的持久化处理类持久保存。

一旦 OAuth 令牌已持久保存，后续的 API 调用将使用持久保存的访问和 refresh_token。SDK 将负责在需要时使用 refresh_token 刷新访问令牌。

应用程序启动

SDK 需要在每次启动客户端应用程序时调用以下代码行。

ZCRMRestClient::initialize();

通过上述行初始化 SDK 后，您可以使用库中的任何 API 获取正确的结果。

使用 SDK

在您的客户端应用程序 PHP 文件中添加以下行，您希望使用 SDK 的位置。

require 'vendor/autoload.php'

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

类层次结构

所有 Zoho CRM 实体都建模为具有适用特定实体的属性和函数的类。ZCRMRestClient 是 SDK 的基类。ZCRMRestClient 有获取各种其他 Zoho CRM 实体实例的功能。

该库的类关系和层次结构遵循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、createBy、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实体对象列表。除了数据之外，这些响应包装对象还具有以下属性

ResponseHeaders - 当天/窗口剩余的API计数和当前窗口重置所经过的时间。 ResponseInfo - API提供的除实际数据外的任何其他信息。 EntityResponse(s)的数组 - 批量API中单个实体的状态。例如：插入记录的API可能因几条记录而部分失败。此数组提供了单个记录的创建状态。

异常

SDK处理所有意外行为，如错误的API响应、库异常，并以单个异常 ZCRMException 的形式抛出。因此，在客户端应用程序代码中只需要捕获此异常即可。

示例

插入记录的样本请求

$zcrmModuleIns = ZCRMModule::getInstance("Invoices"); $bulkAPIResponse=$zcrmModuleIns->createRecords($recordsArray); // $recordsArray - 填充有创建所需数据的ZCRMRecord实例的数组。 $entityResponses = $bulkAPIResponse->getEntityResponses(); foreach($entityResponses as $entityResponse) { if("success"==$entityResponse->getStatus()) { echo "Status:".$entityResponse->getStatus(); echo "Message:".$entityResponse->getMessage(); echo "Code:".$entityResponse->getCode(); $createdRecordInstance=$entityResponse->getData(); echo "EntityID:".$createdRecordInstance->getEntityId(); echo "moduleAPIName:".$createdRecordInstance->getModuleAPIName(); …. } }}

Sample Invoice record instance with filled data
-----------------------------------------------

$record=ZCRMRecord::getInstance("Invoices",null); $record->setFieldValue("Subject","Iphone sale to John"); $record->setFieldValue("Account_Name","410405000001016021"); $productInstance=ZCRMRecord::getInstance("Products",410405000001108011); $lineItem=ZCRMInventoryLineItem::getInstance($productInstance); $taxInstance1=ZCRMTax::getInstance("Sales Tax"); $taxInstance1->setPercentage(2); $taxInstance1->setValue(10); $lineItem->addLineTax($taxInstance1); $taxInstance1=ZCRMTax::getInstance("Vat"); $taxInstance1->setPercentage(12); $taxInstance1->setValue(60); $lineItem->addLineTax($taxInstance1); $lineItem->setQuantity(100); $lineItem->setDiscount(0.5); $record->addLineItem($lineItem);

获取记录的样本请求

$zcrmModuleIns = ZCRMModule::getInstance("Contacts"); $bulkAPIResponse=$zcrmModuleIns->getRecords(); $recordsArray = $bulkAPIResponse->getData(); // $recordsArray - ZCRMRecord实例的数组

有关更多API，请参阅此链接