.. _arch_api: **Веб-сервис REST API для работы с архивом на стороне SAP** =========================================================== Для доступа к архиву SAP реализован сервис через транзакцию ``SICF``. Узел в данной транзакции называется ``/TRL/XDE_SERV``. Авторизация ----------- Для выполнения запросов необходимо сначала :ref:`получить ключ (токен) авторизации`. Для получения токена нужно создать или использовать уже существующего пользователя ``XDEWSUSER``, поскольку при запросе токена указывается имя пользователя и его актуальный пароль в системе SAP. .. important:: У пользователя должна быть заведена роль ``/TRL/XDE_ARCHIVEUSER``. Классы-обработчики ------------------ Для обработки входящих запросов созданы классы-обработчики ``/TRL/XDE_CL_REST_HANDLER`` и ``/TRL/XDE_CL_REST_RESOURCE``. Класс ``/TRL/XDE_CL_REST_HANDLER`` наследует два стандартных интерфейса ``IF_HTTP_EXTENSION`` и ``IF_REST_APPLICATION``. Внутри класса переопределен метод ``GET_ROOT_HANDLER``, который позволяет указать, какой класс-обработчик использовать для входящего запроса. В данном случае это класс ``/TRL/XDE_CL_REST_RESOURCE``. Класс ``/TRL/XDE_CL_REST_RESOURCE`` наследует два стандартных интерфейса ``IF_REST_RESOURCE`` и ``IF_REST_HANDLER``. Внутри класса переопределены методы ``GET`` и ``POST``, которые позволяют выполнять обработку соответствующих запросов. Запросы к сервису ----------------- Для того чтобы выполнить http-запрос, необходимо указать путь. Для этого нужно зайти в транзакцию ``SICF``, найти узел ``trl_xde_serv`` и убедиться, что он активирован. .. image:: media/pic7.png :scale: 100 :align: center Затем вызовите тест узла через контекстное меню. Если узел активирован, откроется браузер. Скопируйте часть из адресной строки, как показано на рисунке (часть, выделенная зеленым, до знака вопроса) и добавьте требуемый тип запроса и параметры (при необходимости), как описано ниже. .. image:: media/pic8.png :scale: 100 :align: center Возможно выполнение трех типов запросов: * :ref:`Запрос на получение токена (авторизация)`; * :ref:`Запрос на сохранение файла в архив `; * :ref:`Запрос на получение файла из архива`. .. _Token: Получение токена ~~~~~~~~~~~~~~~~ Для выполнения данного GET-запроса необходимо в заголовке запроса (Headers) указать **Authorization:Basic** и **X-CSRF-Token:Fetch**. .. image:: media/pic3.png :scale: 100 :align: center Для авторизации в параметрах авторизации (Authorization) необходимо указать имя пользователя и пароль, актуальный для SAP системы. .. image:: media/pic1.png :scale: 100 :align: center В строке запроса нужно указать сервис ``trl_xde_serv`` и имя операции ``Token``. Запрос на получение токена может содержать параметр: * значение манданта SAP-системы (``sap-client``). .. attention:: Указание данных манданта с помощью строки ``sap-client=NNN`` не является обязательным, однако, если в системе существует несколько мандантов, нужно указывать тот, в котором ожидается обработка запросов. Пример запроса: ``http://xde-xxx-111.name.company:1010/trl_xde_serv/Token?sap-client=100`` Значение токена придет в заголовке ответа. .. image:: media/pic2.png :scale: 100 :align: center Полученный токен авторизации действителен в течение 24 часов. После истечения срока действия токена сервис возвращает код ошибки ``403``. В этом случае следует запросить токен авторизации повторно. .. _PutDocument: Сохранение файла в архив SAP ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Запрос на передачу файла в архив должен содержать следующие параметры: * тип хранилища (``astype``); * имя файла (``filename``); * размер файла (``filesize``); * ссылка (``linkid``); * значение манданта SAP-системы (``sap-client``). .. note:: Если не указать тип хранилища, то будет использован настроенный по умолчанию тип хранилища из таблицы ``/TRL/XDE_CUST`` (настройка ``ASTYPE``). .. note:: Параметр ссылки (``linkid``) не является обязательным для заполнения и как правило не применяется для выполнения операции сохранения файла в хранилище. .. attention:: Указание данных манданта с помощью строки ``sap-client=NNN`` не является обязательным, однако, если в системе существует несколько мандантов, нужно указывать тот, в котором ожидается обработка запросов. В заголовке запроса необходимо указать токен (**X-CSRF-TOKEN:<значение_токена>**), полученный ранее через запрос авторизации. .. image:: media/pic4.png :scale: 100 :align: center В строке запроса нужно также указать сервис ``trl_xde_serv`` и имя операции ``PutDocument``. Пример запроса: ``http://xde-xxx-111.name.company:1010/trl_xde_serv/PutDocument?astype=AL&filename=st.pdf&filesize=99&sap-client=100`` Ответ придет в теле ответа в формате JSON: * ``LINKID`` - ссылка на файл; * ``ASTYPE`` - тип используемого хранилища; * ``CR_USER`` - имя пользователя SAP, под которым была выполнена операция; * ``CR_DATE`` - дата выполнения операции; * ``CR_TIME`` - время выполнения операции; * ``RETURN-CODE`` - поле структуры, содержащее код ошибки; * ``RETURN-TEXT`` - поле структуры, содержащее описание ошибки. .. image:: media/pic6.png :scale: 100 :align: center .. _get_document: Получение файла из архива SAP ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Запрос на получение файла из архива SAP должен содержать следующие параметры: * ссылка на файл (``linkid``); * тип хранилища (``astype``); * значение манданта SAP-системы (``sap-client``). .. note:: Если не указать тип хранилища, то будет использован настроенный по умолчанию тип хранилища из таблицы ``/TRL/XDE_CUST`` (настройка ``ASTYPE``). .. attention:: Указание данных манданта с помощью строки ``sap-client=NNN`` не является обязательным, однако, если в системе существует несколько мандантов, нужно указывать тот, в котором ожидается обработка запросов. В заголовке запроса необходимо указать токен (**X-CSRF-TOKEN:<значение_токена>**), полученный ранее через запрос авторизации. .. image:: media/pic4.png :scale: 100 :align: center В строке запроса нужно также указать сервис ``trl_xde_serv`` и имя операции ``GetDocument``. Пример запроса: ``http://xde-xxx-111.name.company:1010/trl_xde_serv/GetDocument?linkid=1356&astype=IM&sap-client=100`` В случае успешного выполнения запроса будет получен код ``200`` и файл в бинарном виде в теле ответа. .. image:: media/pic5.png :scale: 100 :align: center Обработка ошибок ~~~~~~~~~~~~~~~~ В случае, если токен более не актуален, сервис возвращает код ошибки ``403``. Для внутренних ошибок возвращается код ``500`` и заполняется структура ``RETURN``.