如何增强 SuiteCRM REST API 以处理案例更新事务

M.M.Mohseni

5.00/5 (2投票s)

2016年10月25日

CPOL

6分钟阅读

11759

关于向 SuiteCRM API 添加新 API 方法的教程

下载源代码 - 7.3 KB

引言

近几个月来，我为 SuiteCRM 设计和开发了几个客户门户项目。这些应用程序基于 SuiteCRM REST API 工作。但是，SuiteCRM API 在响应我们所需的一切方面存在严重缺陷。

因此，正如您所知，每个通用客户门户最重要的部分是允许用户更新其工单或案例的部分。但不幸的是，SuiteCRM 中没有 REST API 方法允许开发人员选择案例的现有更新或为案例添加新更新。

Using the Code

好的，在这篇文章中，我将向您展示如何向 SuiteCRM 添加两个新的 API。

首先，您应该了解 SuiteCRM API 服务的结构。SuiteCRM API 具有核心和多个增强版本。因此，SuiteCRM API 的最新版本是 4.2。要查看每个版本的功能，您可以访问 SugarCRM 网站。

如果您打开 SuiteCRM 根文件夹中的“service”文件夹，您将看到如下结构

因此，名称以“v”开头的文件夹是 SuiteCRM API 的各种版本。了解每个版本都包含所有先前版本的功能以及它们各自的扩展类非常重要。
在每个版本文件夹中，您将看到此通用结构

要创建和开发您自己的 SuiteCRM API 版本，您需要在所有文件中更改一些代码。从最新的 SuiteCRM API 版本（v 4.1）扩展您的 SuiteCRM API 版本是合乎逻辑且实用的。所以，让我们开始吧。
要创建您自己的服务，请克隆 v4_1 文件夹并将其重命名为您的版本名称。我将其重命名为 fcc。
因此，重命名两个文件（SugarWebServiceImplv4_1.php、SugarWebServiceUtilv4_1.php）并将 v4_1 短语替换为您的版本名称。例如，我将它们重命名为 SugarWebServiceImplfcc.php 和 SugarWebServiceUtilfcc.php。供您参考，您扩展版本的主要代码将写在这两个文件中。

现在打开 rest.php 文件。在 rest.php 文件中，您应该注册并包含您所有的 API 版本。所以，这非常简单，并不复杂。正如我在下面提到的，我的 API 名称是 fcc。因此，您可以看到 fcc 的 rest.php 代码

    require_once('SugarWebServiceImplfcc.php');
    $webservice_class = 'SugarRestService';
    $webservice_path = 'service/core/SugarRestService.php';
    $webservice_impl_class = 'SugarWebServiceImplfcc';
    $registry_class = 'registry';
    $location = '/service/fcc/rest.php';
    $registry_path = 'service/fcc/registry.php';
    require_once('service/core/webservice.php');

您也应该对 soap.php 文件重复此步骤。

因此，我们接下来讨论的文件是 SugarWebServiceUtilfcc.php。SugarWebServiceUtil[version name].php 包含您将在主 API 方法中使用的所有实用程序和辅助函数。所以，这个文件包含一个从最新版本之一扩展而来的类。正如我提到的，最好从 SuiteCRM API 服务的最新版本 v4_1 扩展。所以，类结构将如下所示

因此，根据您的 API 函数需求，您可以在此类中编写自己的函数。另外，正如您所见，您需要在脚本中包含 SugarWebServicecUtilv4_1.php。它指向您扩展 API 的版本。
```
    require_once('service/v4_1/SugarWebServiceUtilv4_1.php');
    
    class SugarWebServiceUtilfcc extends SugarWebServiceUtilv4_1
    {
        // Your functiions
    }
```
在此步骤中，我们开始编写自己的 API 方法函数。主 API 方法和函数写在 SugarWebServiceImpl[Version Name].php 中。所以，我们想添加两个新的 API 方法（我假设您熟悉 SuiteCRM 的通用函数）；
- set_case_update
- get_case_updates
首先，我们编写两个新函数的原型
```
    function get_case_updates($session, $module_name, $name_value_list) {
    	// API code
    }
    And
    function set_case_update($session, $module_name, $name_value_list) {
        // API code
    }
```
两个新函数具有相同的参数
- $session：所有 SuiteCRM API 方法的通用参数。此参数包含登录函数返回的会话 ID，并表明请求具有足够的凭据。
- $module_name：此参数属于适用于所有模块的方法，例如 get_entry_list、set_entry 等。它包含正在为其数据执行请求的模块的名称。在我们的案例中，此参数不是必需的，因为这两个方法都在 Case_Updates 模块上工作。但我没有从方法原型中删除此参数。
- $name_value_list：此参数是一个数组，包含所有从客户端发送的数据，例如查询、字段值等。
因此，我们已成功编写了 API 方法原型，现在让我们开始编写方法。
如其所示，set_case_update 方法负责在案例记录上插入或更新一个 case_update。所以，该方法将如下所示
```
	    $case_update = new AOP_Case_Updates();

        $GLOBALS['log']->info('Begin: SugarWebServiceImpl->set_case_update');

        if (!self::$helperObject->checkSessionAndModuleAccess
           ($session, 'invalid_session', 
           "AOP_Case_Updates", 'read', 'no_access', $error)) {
            return;
        }

        foreach ($name_value_list as &$value) {
            $name = $value['name'];
            $case_update->$name = $value['value'];
        }

        $case_update->save();

        $GLOBALS['log']->info('End: SugarWebServiceImpl->set_case_update');
        return array('id'=> $case_update->id);	
```
在第一行，我们创建 AOP_Case_Update 的新实例。众所周知，在 SuiteCRM 中，要插入或更新一条新记录，您只需要获取一个模块类的新实例。因此，当您调用 Save 方法时，如果 id 字段为空，则将创建一条新记录；如果 id 已填写，则该方法将更新 id 所属的记录。

下一行代码只是在 SuiteCRM 日志文件中写入新的一行。
```
    $GLOBALS['log']->info('Begin: SugarWebServiceImpl->set_case_update');
```
下一个条件语句用于检查凭据和用户访问权限。如果 sessionId 为空或值不正确，则方法返回。在另一种情况下，如果用户没有足够的模块访问权限，方法也会返回。在下一个语句中，有一个 foreach 循环遍历 $anem_value_list 数组并填充 $case_update 参数。

最后一条语句调用 case_update 实例的 save 方法。正如我在下面说的，这个方法根据 Id 属性的值工作。如果 Id 为空，该方法将添加一条新记录；如果 id 属性具有正确的 id 值，该方法将更新该记录。

方法的最后一行返回新记录或已更新记录的 Id。这是所有 insert 或 update 方法的必要部分，用于返回调用它的代码的 id 值。

这个 API 的下一个方法是 get_case_updates。此方法获取一个 Case ID 并返回其所有 case_updates。所以，这个方法非常简单

	    function get_case_updates($session, $module_name, $name_value_list){

        $caseUpdateBean = BeanFactory::getBean('AOP_Case_Updates');
        $caseUpdate = $caseUpdateBean->get_full_list
                      ('date_entered desc',"case_id = '" . 
                      $name_value_list[0]['value'] . "' ");

        $counter = 0;
        
        foreach ($caseUpdate as &$value) {
            $item = array();
            $i = 1;
            foreach ($value as $key => $val)
            {
                try
                {
                    if ($i < 22)
                    {
                        array_push($item, array
                        ("name" => $key, "value" => $val));
                    }
                }
                catch (Exception $e) { 
                    
                }
                $i++;
            }
            if ($counter == 0)
                $items = array($item);
            else
                array_push($items, $item);
            
            $counter++;
        }

        $result = array("count" => $i, "items" => $items);

        return array('entry_list'=> $result);
    }

在第一行，我们创建 Case_Update 的新实例。这是使用 BeanFactory::getBean 方法完成的。因此，在下一行，我们调用 get_full_list 方法。此方法接收两个 string 参数，排序顺序和查询语句，并返回与查询匹配的记录列表。

下一步的循环根据客户端可以处理的合适返回值填充一个新数组。

最后一行，该方法将数组返回给客户端。

现在，我们编写了两个新的 API 方法。但客户端无法访问它们。因为我们应该将这些新方法注册为 REST 方法。因此，为了完成这项任务，我们应该在 registry.php 中编写一些新的代码行。此文件有两个方法用于注册当前 API 版本的函数和类型。我必须提到这些新方法非常简单。有一些复杂 API 需要新的变量类型等等……

因此，我写了一个示例，说明如何在 registry.php 中注册 API
```
    $this->serviceClass->registerFunction(
                'set_case_update',
                array('session'=>'xsd:string', 'module_name'=>'xsd:string', 
                      'name_value_list'=>'tns:name_value_list'),
                array('return'=>'tns:new_set_entry_result'));
```

关注点

在这个项目中，我增强了 SuiteCRM API，这有助于我扩展 SuiteCRM 的第三方应用程序。重要的是，您不要局限于 SuiteCRM 的内置 API，而是可以创建自己的 API。