Центр документации
Карта сайта

Создай визитку сам!


Самоучитель по интеграции дизайна и настройке Amiro.CMS на примере демонстрационной версии пакета Визитка »


Веб-сервисы

Любой устанавливаемый модуль Amiro.CMS может быть интегрирован в REST API и выполнять роль веб-сервиса.

Для этого модуль должен содержать код добавления и исполнения действий сервиса, а так же указать системе требуемый режим доступа.

Обращение к сервису происходит через единую точку входа /ami_service.php

Набор параметров для вызова действия веб-сервиса модуля:

Параметр
Значение
Обязательное
Описание
serviceami_webservice+ 
version1.1+ 
modId#string+ID модуля
action#string+Имя выполняемого действия веб-сервиса
appToken#string+Токен доступа к API
userToken#string Токен авторизации пользователя
amiFull#int Если 1, то действие веб-сервиса будет исполняться в полном окружении
ami_locale#string Язык данных окружения (ru, en, ...)

Допускается передача других произвольных параметров, которые возможно получить в обработчике дейстивия через AMI_Request.

Для добавления обработчиков действий веб-сервиса, требуется создать класс {Hyper}_{Config}_Service, наследник AMI_Module_Service.
Где {Hyper} и {Config} - имена гипермодуля и конфигурации в camelcase соответственно. 

Добавление обработчиков происходит в методе addWebserviceHandlers.

class AmiClean_MyModule_Service extends AMI_Module_Service{
    /**
     * Метод добавления обработчиков модуля.
     */
    public function addWebserviceHandlers(array &$aEvent){
        parent::addWebserviceHandlers($aEvent);
        // Добавляем обработчик действия 'my_module.action'
        AMI_Event::addHandler(
            'on_webservice_{my_module.action}_action',
            array($this, 'handleAction'),
            AMI_Event::MOD_ANY
        );
        return $aEvent;
    }
 
    /**
     * Код обработчика действия.
     */
    public function handleAction($name, array &$aEvent){
        // Условие которое должно быть выполнено
        $someCondition = TRUE;
        if($someCondition){
            // Добавляем результат в ответ сервиса
            $aEvent['result'] = 'Some result';
            // Отправка результата в формате JSON
            $this->oWebService->ok($aEvent);
        }else{
            // Ошибка, в случае если условие не выполнено
            $this->oWebService->error(
                // Код ошибки
                AmiClean_Webservice_Service::ERR_FAIL,
                // Сообщение об ошибке
                'Error message'
            );
        }
        return $aEvent;
    }
}

 

Веб-сервисы поддерживают следующие режимы доступа:
 

Доступ на уровне приложения.

Данный режим доступа предполагает использование веб-сервиса в качестве серверной составляющей клиент-серверного приложения.
Например, в качестве поставщика данных для мобильного приложения.

В этом режиме, для того чтобы получить доступ к веб-сервису, приложение должно быть авторизовано по ключу API Key и иметь доступ к установленному модулю.

Из кода режим доступа включается следующим образом:

AmiClean_Webservice_Service::createApiKey($this->oArgs->modId, 'MY_API_KEY');

При этом, будет создан ключ 'MY_API_KEY', а модуль будет добавлен в список модулей, к которым есть доступ по указанному ключу.

Данное действие должно выполняться один раз, обычно при установке модуля в файле install_after.php

Когда ключ API Key создан, и связь между ключом и модулем установлена, приложение должно авторизоваться с данным ключом на сайте, где установлен модуль, получить токен доступа appToken, и с ним уже сможет обратиться к действию модуля.

Например:

1. Авторизация
 
Запрос: /ami_service.php?service=ami_webservice&version=1.1&action=sys.auth&fullEnv=1&apiKey=MY_API_KEY
Ответ: {"data":{"errorCode":"OK","errorMessage":"","version":"1.1","appToken":"a5357899a4bbe16-491672430"}}
 
2. Обращение к веб-сервису
 
Запрос: /ami_service.php?service=ami_webservice&version=1.1&action=my_module.action&modId=inst_my_module&appToken=a5357899a4bbe16-491672430
Ответ: {"data":{"errorCode":"OK","errorMessage":"","version":"1.1","result":"Some result"}}

 

Открытый доступ

Данный режим доступа предполагает что сервис модуля может быть использован любым внешним приложением.
Например, использоваться в качестве AJAX бэкенда для публичной части модуля.

В этом режиме, для получения доступа к модулю необходимо передать только публичный токен app_token_public.

Включение данного режима производится при установке модуля в файле install_after.php

AmiClean_Webservice_Service::allowPublicAccess($this->oArgs->modId);

По умолчанию, открытый доступ к действиям веб-сервиса модуля запрещен.

Для открытия доступа к действиям веб-сервиса, необходимо это явно указать для каждого из действий в методе addWebserviceHandlers класса {Hyper}_{Config}_Service.

/**
 * Метод добавления обработчиков модуля.
 */
public function addWebserviceHandlers(array &$aEvent){
    parent::addWebserviceHandlers($aEvent);
    // Разрешаем открытый доступ
    $this->oWebService->setPublicAccess('my_module.action', TRUE);
    // Добавляем обработчик действия 'my_module.action'
    AMI_Event::addHandler(
        'on_webservice_{my_module.action}_action',
        array($this, 'handleAction'),
        AMI_Event::MOD_ANY
    );
    return $aEvent;
}


Управление доступом к веб-сервисам модулей возможно из панели администратора в модуле "Настройка системы : Веб-сервисы".


Авторизация

Действия веб-сервиса могут требовать авторизацию пользователя.

Как и в случае с открытым доступом, это требование необходимо прописывать для каждого из действий отдельно. По умолчанию авторизация не требуется.

$this->oWebService->setAuthRequired('my_module.action', TRUE);

Доступ к такому действию возможен только для авторизованного пользователя, либо через передачу параметра userToken.

 

Окружение

Если по каким-то причинам для выполнения действия требуется полное окружение,  нужно указать это в обработчике действия.

public function handleAction($name, array &$aEvent){
    $this->oWebservice->requireFullEnv();
 
    // Действия требующие полного окружения
    // ....
    return $aEvent;
}

 

Пример реализации модуля, использующего собственный веб-сервис для получения и отображения динамических данных на странице: Спецблок "Кто сейчас на сайте".

Установка и настройка Руководство пользователя Интеграция дизайна Разработчикам (API)
 2000 – 2021 © Amiro.CMS Все права защищены.