.. _sap_rest_manual_descr: Описание работы сервисов ======================== Для работы с сервисами через REST API со стороны SAP необходимо выполнять http-запросы. Для этого SAP предусмотрел стандартные ФМ HTTP_GET или HTTP2_GET (Get-запрос) и HTTP_POST или HTTP2_POST (Post-запрос), а также множество классов. В решении TerraLink используются два стандартных модуля HTTP2_GET и HTTP2_POST для работы с REST сервисом для ИМ. .. _global_class: Реализован глобальный класс ``/TRL/XDE_CL_REST``. Класс не имеет метода-конструктора, все его методы являются статическими. .. raw:: latex \begin{landscape} .. table:: Описание атрибутов класса :widths: 4 1 1 5 2 4 :class: longtable +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | Имя атрибута | Тип | Видимость | Технический тип | Описание | | +===================+===========+===============+==========================+===============+========================+ | MC_USERNAME | Конст. | Private | CHAR9 | Часть | 'username=' | | | | | | тела | | | | | | | запроса | | | | | | | для | | | | | | | получения | | | | | | | токена | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_PASSWORD | Конст. | Private | CHAR10 | Часть | '&password=' | | | | | | тела | | | | | | | запроса | | | | | | | для | | | | | | | получения | | | | | | | токена | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_GRANTTYPE | Конст. | Private | CHAR20 | Часть | '&grant_type=password' | | | | | | тела | | | | | | | запроса | | | | | | | для | | | | | | | получения | | | | | | | токена | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_AUTHORIZATION | Конст. | Private | CHAR30 | Начало | 'authorization:bearer' | | | | | | заголовка | | | | | | | запроса | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_REST_ARCH | Конст. | Private | /TRL/XDE_ED_REST_ID | Идентификатор | 'REST_IM' | | | | | | rest сервиса | | | | | | | архива | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_REST_IM | Конст. | Private | /TRL/XDE_ED_REST_ID | Имя | 'REST_IM' | | | | | | идентификатора| | | | | | | сервиса | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_PATH_TOKEN | Конст. | Private | CHAR10 | Часть адреса | 'Token' | | | | | | для получения | | | | | | | токена | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MS_REST_SV | Статич. | Private | /TRL/XDE_REST_SV | Данные из | | | | аттрибут | | | таблицы | | | | | | | сервисов | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MS_REST_ST | Статич. | Private | /TRL/XDE_REST_ST | Данные из | | | | аттрибут | | | таблицы | | | | | | | операций | | | | | | | | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_SLASH | Конст. | Private | CHAR1 | Знак слэш | '/' | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_ENCODING | Конст. | Private | /TRL/XDE_ED_SETTING_NAME | Имя | 'XML_ENCODING_FTS' | | | | | | настройки | | | | | | | | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_401 | Конст. | Private | CHAR4 | Код | '401' | | | | | | ошибки | | | | | | | проваленной | | | | | | | аутентифи | | | | | | | кации | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_200 | Конст. | Private | CHAR4 | Успешный | '200' | | | | | | код | | | | | | | запроса | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_403 | Конст. | Private | CHAR4 | Код ошибки | '403' | | | | | | проваленной | | | | | | | аутентификации| | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_CONT_TYPE | Конст. | Private | BCS_AD_STR | Content-type | 'content-type: | | | | | | в заголовке | application/json' | | | | | | запроса | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_GET | Конст. | Private | /TRL/XDE_ED_HTTPTYPE | Тип HTTP | 'GET' | | | | | | запроса | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_POST | Конст. | Private | /TRL/XDE_ED_HTTPTYPE | Тип HTTP | 'POST' | | | | | | запроса | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_FIGLEFT | Конст. | Private | CHAR1 | Левая фигур- | '{' | | | | | | ная скобка | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_FIGRIGHT | Конст. | Private | CHAR1 | Правая фигур- | '}' | | | | | | ная скобка | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MC_GCIN | Конст. | Private | TEXT5 | Коды компонен-| 'gCIN' | | | | | | тов типа | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ | MO_LOGGER | Статич | Private | /TRL/XDE_IF_LOGGER | Объект для | | | | атрибут | | | логирования | | +-------------------+-----------+---------------+--------------------------+---------------+------------------------+ Описание методов класса: 1. **GET_REST_SV** .. table:: GET_REST_SV :widths: auto +-----------------+-----------------+-----------------+----------------------+ | Имя метода | Вид метода | Видимость | Описание | +=================+=================+=================+======================+ | GET_REST_SV | Static Method | Private | Получить данные из | | | | | таблиц REST сервисов | | | | | и операций | +-----------------+-----------------+-----------------+----------------------+ .. table:: Параметры метода :widths: 4 1 4 2 +-----------------+-----------------+---------------------------+-----------------+ | Имя параметра | Вид | Ссылочный тип | Описание | +=================+=================+===========================+=================+ | IV_OPERATION | Importing | CHAR100 | Код операции | +-----------------+-----------------+---------------------------+-----------------+ | IV_ID | Importing | /TRL/XDE_ED_REST_ID | Тип REST | | | | | сервиса | +-----------------+-----------------+---------------------------+-----------------+ .. raw:: latex \end{landscape} Метод содержит две операции выбора данных из таблиц базы данных. Первая операция - выбор данных из таблицы настроек REST сервисов ``/TRL/XDE_REST_SV``. Найденные данные записываются в статический атрибут MS_REST_SV. Вторая операция - выбор данных по операции из таблицы настроек операции ``/TRL/XDE_REST_ST``. Найденные данные записываются в статический атрибут MS_REST_ST. 2. **GET_HEADER** .. table:: GET_HEADER :widths: auto +--------------+---------------+-----------+---------------------------+ | Имя метода | Вид метода | Видимость | Описание | +==============+===============+===========+===========================+ | GET_HEADER | Static Method | Private | Собрать заголовок запроса | +--------------+---------------+-----------+---------------------------+ .. table:: Параметры метода :widths: auto +-----------------+-----------+-------------------------+-----------------+ | Имя параметра | Вид | Ссылочный тип | Описание | +=================+===========+=========================+=================+ | ET_REQUEST_HEAD | Exporting | /TRL/XDE_T_REQUEST_HEAD | Таблица заголов-| | | | | ка для http-зап-| | | | | роса | +-----------------+-----------+-------------------------+-----------------+ В данном методе происходит конкатенация константы ``MC_AUTHORIZATION`` и значения токена из атрибута ``MS_REST_SV-TOKEN`` и добавление данной записи в таблицу с заголовками. Также в таблицу с заголовками в данном методе добавляется значение константы ``MC_CONT_TYPE``. 3. **SAVE_DATABASE** .. table:: SAVE_DATABASE :widths: auto +---------------+---------------+-----------+----------------------+ | Имя метода | Вид метода | Видимость | Описание | +===============+===============+===========+======================+ | SAVE_DATABASE | Static Method | Private | Сохранить токен в БД | +---------------+---------------+-----------+----------------------+ Метод не имеет параметров. Берется токен из атрибута ``MS_REST_SV-TOKEN`` и выполняется UPDATE таблицы БД ``/TRL/XDE_REST_SV`` по ключу ``REST_ID``. Обновляется только значение токена. 4. **GET_URI** .. table:: GET_URI :widths: auto +---------------+---------------+-----------+---------------------------+ | Имя метода | Вид метода | Видимость | Описание | +===============+===============+===========+===========================+ | GET_URI | Static Method | Private | Собрать URL адрес для вы- | | | | | полнения запроса | +---------------+---------------+-----------+---------------------------+ .. table:: Параметры метода :widths: auto +-----------------+-----------+------------------+-----------------------+ | Имя параметра | Вид | Ссылочный тип | Описание | +=================+===========+==================+=======================+ | I_INPUT | Importing | ANY | Данные в любой форме | +-----------------+-----------+------------------+-----------------------+ | ES_RETURN | Exporting | /TRL/XDE_RETURN | Код и текст сообщения | +-----------------+-----------+------------------+-----------------------+ | EV_URI | Exporting | STRING | URL для выполнения | | | | | запроса | +-----------------+-----------+------------------+-----------------------+ Проверяется заполненность данных в ``MS_REST_SV-PATH`` - если данных нет, то вызывается особая ситуация ``SETTINGS_ERROR``. Проверяется заполненность данных в ``MS_REST_ST`` - если данных нет, то вызывается особая ситуация ``SETTINGS_ERROR``. Далее выполняется конкатенация данных из ``MS_REST_SV-PATH`` и ``MS_REST_ST-METH_NAME``. После этого, если удается, значение из I_INPUT динамически подставляется на место имени метода, если такое было предусмотрено. 5. **GET_TOKEN** .. table:: GET_TOKEN :widths: auto +------------+---------------+-----------+-----------------------------------------+ | Имя метода | Вид метода | Видимость | Описание | +============+===============+===========+=========================================+ | GET_TOKEN | Static Method | Public | Получить токен из БД или ИМ по rest api | +------------+---------------+-----------+-----------------------------------------+ .. table:: Параметры метода :widths: auto +---------------+-----------+----------------------+-----------------------+ | Имя параметра | Вид | Ссылочный тип | Описание | +===============+===========+======================+=======================+ | ES_RETURN | Exporting | /TRL/XDE_RETURN | Код и текст сообщения | +---------------+-----------+----------------------+-----------------------+ В первую очередь проверяется заполненность токена в ``MS_REST_SV-TOKEN``. Если токен найден – работа метода заканчивается, в противном случае – выполняется получение нового токена. Для этого значение из атрибута ``MS_REST_SV-PATH`` объединяется в строку для URL для выполнения http-запроса. Другие атрибуты ``MS_REST_SV-USERNAME`` и ``MS_REST_ST-PASSWORD`` используются для обарзования заголовка для прохождения аутентификации в REST сервисе. Данная строка является телом запроса для получения токена. Содержимое строки (тело запроса) = «username=1&password=2&grant_type=password», где 1 = содержимое ``MS_REST_SV-USERNAME``, 2 = содержимое ``MS_REST_SV-PASSWORD``. Содержимое адреса = «1Token», где 1 = содержимое ``MS_REST_SV-PATH``. - Если при преобразовании возникли ошибки – работа метода заканчивается, а структура ``ES_RETURN`` будет содержать ``CODE`` = 2210 и TEXT = «Не удалось получить токен для авторизации». Затем выполняется вызов ФМ HTTP2_POST, на вход которого подается сформированный адрес запроса и тело запроса. - Если ФМ отрабатывает неуспешно (sy-subrc не равен 0) – заполняется поле ``ES_RETURN-CODE`` = 2210 и ``ES_RETURN-TEXT`` = «Не удалось получить токен для авторизации». Далее, с помощью метода ``GET_SETTING_SAFE`` класса ``/TRL/XDE_CL_SETTINGS`` достаем данные из настройки «XML_ENCODING_FTS» (атрибут ``MC_ENCODING``) .. image:: media/image8.png :scale: 95 :align: center Далее, с помощью ФМ ``SCP_CODEPAGE_BY_EXTERNAL_NAME``, получаем кодировку - Если результат работы ФМ не успешен (sy-subrc не равен 0) – заполняем поля ``ES_RETURN-CODE`` = 9999 и ``ES_RETURN-TEXT`` = «Не найден номер кодировки для конвертации данных запроса». Работа метода на этом заканчивается. Конвертируем тело ответа от http-запроса с указанием найденной кодировки в строку. Для этого используем метод ``HTMLBIN_TO_HTMLTXT`` класса ``CL_BCS_CONVERT``. И делаем попытку распарсить полученную строку с помощью вызова Simple Transformation ``/TRL/XDE_XSLT_IN_TOKEN``. - Если во время трансформации возникли ошибки, приведшие к вызову особой ситуации, заполняются поля ``ES_RETURN-CODE`` = 9999 и ``ES_RETURN-TEXT`` = «Не удалось получить токен для авторизации» Атрибуту ``MS_REST_SV-TOKEN`` присваиваем полученный токен и затем вызываем метод ``save_database`` и завершаем работу метода. 6. **DO_OPERATION** .. table:: DO_OPERATION :widths: auto +--------------+---------------+-----------+---------------------+ | Имя метода | Вид метода | Видимость | Описание | +==============+===============+===========+=====================+ | DO_OPERATION | Static Method | Public | Выполнить операцию | +--------------+---------------+-----------+---------------------+ .. table:: Параметры метода :widths: 3 2 4 2 +-----------------+-----------------+-----------------------+-----------------+ | Имя параметра | Вид | Ссылочный тип | Описание | +=================+=================+=======================+=================+ | IV_OPERATION | Importing | CHAR100 | Имя операции | +-----------------+-----------------+-----------------------+-----------------+ | I_INPUT | Importing | ANY | Данные в любом | | | | | виде | +-----------------+-----------------+-----------------------+-----------------+ | E_OUTPUT | Exporting | ANY | Данные в любом | | | | | виде | +-----------------+-----------------+-----------------------+-----------------+ | ES_RETURN | Exporting | /TRL/XDE_RETURN | Код и текст | | | | | сообщения | +-----------------+-----------------+-----------------------+-----------------+ Данный метод является универсальным методом для работы с REST сервисом интеграционного модуля. Сначала вызывается метод ``GET_REST_SV``, который заполняет нужные статические атрибуты класса. Далее выполняется ``MS_REST_SV-ITERATOR`` раз попытки выполнить запрос с ожиданиями между итерациями равными ``/TRL/XDE_REST_SV-WAIT`` секунд. Это сделано так как некоторые запросы только ставят задачу на выполнение, а результат получается по идентификатору данной задачи. Бывает так, что для получения результата необходимо подождать какое-то количество времени. С помощью вышеописанных настроек из атрибута ``MS_REST_SV`` можно задать максимальное время ожидания для таких задач. Каждая итерация состоит из двух выполнений определенного алгоритма. Выполнение дважды необходимо, так как если окажется, что имеющийся в БД токен, уже неактуален, то во время выполнения второго раза токен будет запрошен через REST сервис в обязательном порядке. Алгоритм для выполнения операции же состоит из следующих шагов: Получение токена через метод ``GET_TOKEN``. Получние URL для выполнения http-запроса с помощью метода ``GET_URI``. Получение тела запроса в бинарном виде с помощью ФМ, указанного в настройках и хранящегося в ``MS_REST_ST-CREATE_BODY``. Получение заголовочной части http-запроса с помощью метода ``GET_HEADER``. Выполнение http-запроса с помощью метода ``DO_REQUEST``. Обработка полученного результата с помощью ФМ, указанного в настройках и хранящегося в ``MS_REST_ST-INPUT_FM``. 7. **DO_REQUEST** .. table:: DO_REQUEST :widths: auto +------------+---------------+-----------+---------------------------+ | Имя метода | Вид метода | Видимость | Описание | +============+===============+===========+===========================+ | DO_REQUEST | Static Method | Private | Выполнить http запрос | +------------+---------------+-----------+---------------------------+ .. table:: Параметры метода :widths: 3 2 4 2 +-----------------+-----------+-------------------------+--------------------+ | Имя параметра | Вид | Ссылочный тип | Описание | +=================+===========+=========================+====================+ | IV_URI | Importing | STRING | Адрес запроса | +-----------------+-----------+-------------------------+--------------------+ | IV_REQ_SIZE | Importing | I (Integer) | Размер тела | | | | | запроса | +-----------------+-----------+-------------------------+--------------------+ | IT_REQ_BODY | Importing | SOLIX_TAB | Тело запроса | +-----------------+-----------+-------------------------+--------------------+ | IT_REQ_HEAD | Importing | /TRL/XDE_T_REQUEST_HEAD | Таблица заголовков | | | | | сообщения | +-----------------+-----------+-------------------------+--------------------+ | ES_RETURN | Exporting | /TRL/XDE_RETURN | Код и текст | | | | | сообщения | +-----------------+-----------+-------------------------+--------------------+ | EV_SIZE | Exporting | I (Integer) | Размер тела ответа | +-----------------+-----------+-------------------------+--------------------+ | ET_RESP_BODY | Exporting | SOLIX_TAB | Тело ответа в | | | | | бинарном виде | +-----------------+-----------+-------------------------+--------------------+ В зависимости от того, какой тип запроса настроен для операции в ``MS_REST_ST-HTTP_TYPE`` вызывается либо стандартный ФМ ``HTTP2_GET``, либо ``HTTP2_POST``. Если код sy-subrc не будет равен 0 - будет вызвана особая ситуация ``HTTP_ERROR``. Если же запрос будет выполнен, но вернется код 401 или 403 - будет вызвана особая ситуация ``AUTH_ERROR`` и будет очищено значение токена из ``MS_REST_SV-TOKEN``. Если вернется код отличный от 200 - произошла какая-то ошибка. Вызывается особая ситуация ``HTTP_ERROR``. Если вернется код 200, значит, что всё в порядке.