319  /  381

Добавление своих методов REST API

Просмотров: 18966
Дата последнего изменения: 25.10.2020
Роберт Басыров
Сложность урока:
4 уровень - сложно, требуется сосредоточится, внимание деталям и точному следованию инструкции.
1
2
3
4
5
Недоступно в редакциях:
Ограничений нет

При создании собственных приложений для коробочных редакций возникает потребность в добавлении новых методов для них в REST API.

Порядок действий:

  1. Регистрируется обработчик события OnRestServiceBuildDescription модуля rest. Обработчик возвращает массив вот такой структуры::
    return array(
       'имя_scope' => array(
          'имя_метода' => array(
             'callback' => обработчик_метода,
             'options' => array(),
          ),
          'имя_метода' => array(
             'callback' => обработчик_метода,
             'options' => array(),
          ),
       )
    );

    Имя scope - произвольное. Если регистрируется собственный scope, то он будет доступен в списке разрешений для локальных приложений. Для добавления методов в существующий scope, укажите имя метода. Если добавляются методы, доступные всем приложениям, то вместо имени указывается константа \CRestUtil::GLOBAL_SCOPE.

    Имя метода также произвольное, допускается использование как верхнего, так и нижнего регистра. Но рекомендуется придерживаться нижнего регистра. Традиционное именование - имя_scope.имя_сущности.действие.

    Обработчик метода - стандартный PHP псевдо-тип callback. Анонимные функции пока не поддерживаются.

  2. Функция-обработчик получит на вход 3 параметра:
    • ассоциативный массив данных вызова без авторизационных параметров;
    • параметр для возврата постранички;
    • экземпляр класса \CRestServer, из которого получаются некоторые полезные данные.
  3. Функция-обработчик может:
    • либо вернуть ответ (массив или скалярное значение), которые будут приведены к json- или xml-виду,
    • либо бросить исключение, которое будет перехвачено и отображено в виде REST-ошибки.

    Если требуется указать HTTP-статус ошибки, то воспользуйтесь классом \Bitrix\Rest\RestException. Если при этом ранее ядром было сгенерировано старое исключение ($APPLICATION->ThrowException()), то оно перезапишет ошибку в ответе.

  4. К моменту вызова функции-обработчика проверки прав доступа уже выполнены, а объект $USER уже проинициализирован с авторизацией привязанного к токену пользователя.

    Пример:

    class RestTest
    {
       public static function OnRestServiceBuildDescription()
       {
          return array(
             'sigurdtest' => array(
                'sigurdtest.test' => array(
                   'callback' => array(__CLASS__, 'test'),
                   'options' => array(),
                ),
             )
          );
       }
    
       public static function test($query, $n, \CRestServer $server)
       {
          if($query['error'])
          {
             throw new \Bitrix\Rest\RestException(
                'Message',
                'ERROR_CODE',
                \CRestServer::STATUS_PAYMENT_REQUIRED
             );
          }
    
          return array('yourquery' => $query, 'myresponse' => 'My own response');
       }
    }
    
    AddEventHandler('rest', 'OnRestServiceBuildDescription', array('\RestTest', 'OnRestServiceBuildDescription'));

    http://cp.sigurd.bx/rest/sigurdtest.test?auth=qcdfzzjtp8hvcbjl42eg93wuw5n0mvsb&test=222
    
    HTTP/1.1 200 OK
    
    Content-Type: application/json; charset=utf-8
    
    {
        "result": {
           "myresponse": "My own response",  
           "yourquery": {
               "test": "222"
           }
       }
    }
    
    http://cp.sigurd.bx/rest/sigurdtest.test.xml?auth=qcdfzzjtp8hvcbjl42eg93wuw5n0mvsb&error=1
    
    HTTP/1.1 402 Payment Required
    
    Content-Type: text/xml; charset=utf-8
    
    <?xml version="1.0" ?>
    <response>
       <error>ERROR_CODE</error>
       <error_description>Message</error_description>
    </response>

Как определить обработчик отсутствующего в описании REST-метода "на лету"

Для этого используйте событие onFindMethodDescription, вызываемое перед отдачей ошибки METHOD_NOT_FOUND. Оно позволяет подставить описание метода "на лету".

Как работать с навигацией в своих методах реста

\Bitrix\Main\Loader::includeModule('rest');
class ApiTest extends \IRestService
{
    public static function OnRestServiceBuildDescription()
    {
        return array(
            'apitest' => array(
                'api.test.list' => array(
                    'callback' => array(__CLASS__, 'getList'),
                    'options' => array(),
                ),
            )
        );
    }

    public static function getList($query, $nav, \CRestServer $server)
    {
        $navData = static::getNavData($nav, true);

        $res = \Bitrix\Main\UserTable::getList(
            [
                'filter' => $query['filter']?:[],
                'select' => $query['select']?:['*'],
                'order' => $query['order']?:['ID' => 'ASC'],
                'limit' => $navData['limit'],
                'offset' => $navData['offset'],
                'count_total' => true,
            ]
        );

        $result = array();
        while($user = $res->fetch())
        {
            $result[] = $user;
        }

        return static::setNavData(
            $result,
            array(
                "count" => $res->getCount(),
                "offset" => $navData['offset']
            )
        );
    }
}

AddEventHandler('rest', 'OnRestServiceBuildDescription', array('\ApiTest', 'OnRestServiceBuildDescription'));

На примере ORM класс работы с пользователями показывается как зарегистрировать свой метод для работы с таблицами пользователей. Если вам необходимо сделать постраничную навигацию для методов не ORM-классов, например, для getNavData(), то вторым параметром передайте: false ($navData = static::getNavData($nav, false);), тогда вернётся навигация соответствующая методам старого ядра.

Пример запроса:

/rest/api.test.list?order[ID]=ASC&filter[<ID]=1000&select[]=ID&select[]=NAME&start=200

Так же необходимо выставление прав доступа в вашем локальном приложении для scope примера apitest:


8
Курсы разработаны в компании «1С-Битрикс»

Если вы нашли неточность в тексте, непонятное объяснение, пожалуйста, сообщите нам об этом в комментариях.
Развернуть комментарии