close

Вход

Забыли?

вход по аккаунту

?

PI Rest Adapter

код для вставки
описаны концепции и настройки SAP PI REST адаптера
PI REST ADAPTER. Не надо бояться.
Перевод статьи http://scn.sap.com/docs/DOC-60855
Оглавление
Введение ...................................................................................................................................................... 1
От REST к XI и обратно. ............................................................................................................................ 2
От HTTP к XI. ......................................................................................................................................... 2
От XI к HTTP. ......................................................................................................................................... 2
Входящие REST сервисы.......................................................................................................................... 3
Исходящие REST сервисы. Вызов REST API. .......................................................................................... 6
Этот блог из коллекции блогов, в которых описаны концепции и настройки SAP PI REST адаптера.
Мы также добавили примеры для более полного понимания, как можно использовать этот
адаптер в ваших сценариях.
Полный список блогов по этой теме доступен по ссылке: PI REST Adapter - Blog Overview
Введение
Если вы в первый раз столкнулись с REST адаптером, то его настройки могут быть для вас не
такими очевидными. В этом блоге я хочу рассказать вам про возможности REST адаптера, его
настройки и особенности.
На первый взгляд
REST сам по себе не является протоколом1, скорее это архитектурная возможность для
реализации веб-сервиса с использованием HTTP вызовов и JSON или XML в качестве полезной
нагрузки (payload).
Преимущество REST API в том, что используя простой HTTP - протокол на транспортном уровне и
JSON (XML) формат контента, этот контент может легко принять браузер или другая backend
система.
Недостатки REST в том, что не каждый REST сервис реализован так же как, другие.2
Т.е. REST требует, чтобы любой REST клиент должен быть адаптирован к REST API , либо должен
быть изменен, чтобы иметь возможность использовать REST API. SAP REST Adapter использует
второй подход, и это является одной из причин, почему в настройках REST адаптера так много
пунктов. SAP REST адаптер – как швейцарский нож для работы с REST API сервисами. Если вы с
одного взгляда не понимаете всех пунктов конфигурации адаптера - без паники! Это нормально.
1
2
does not represent a strict protocol (оригинал)
not every REST service is necessarily implemented the same way as others. (оригинал)
От REST к XI и обратно.
REST адаптер в основном занимается тем, что позволяет мэппить контент и заголовки XI в
параметры, необходимые при вызове HTTP и REST API (и наоборот).
При HTTP вызовах адаптер может получить доступ к информации в URL и параметрах URL, к HTTP
операциям (GET, POST, PUT, DELETE), к HTTP заголовкам (например cookie или параметрам
шифрования) и к полезной нагрузке. В XI сообщениях адаптер берет информацию из XI заголовков
и полезной нагрузки.
От HTTP к XI.
При преобразовании HTTP вызова к XI сообщению отмеченная (selected) информация, кроме
полезной нагрузки, берется из HTTP и пишется в XI заголовки.
Для удобства в REST адаптере по умолчанию установлены XI заголовки (url, service, resource, id,
operation, etc), которые могут быть заполнены из HTTP для дальнейшего использования в IFlow
или в целях диагностики/трейса.
Полезная нагрузка может быть использована как есть, сконвертирована в UTF-8 либо
преобразована из JSON в XML и наоборот.
Для XI, которые ожидают XML и привязаны к интерфейсу/операции, адаптер может добавить к
сообщению фиксированное или вычисленное на основе данных из HTTP сообщения имя
интерфейса/операции.
От XI к HTTP.
Как Receiver, адаптер динамически генерирует HTTP URL, основываясь на информации,
переданной в XI заголовках и полезной нагрузки. Основываясь на настройках имя
интерфейса/операции может быть использовано для определения HTTP операции, которую
необходимо использовать (POST, PUT, GET или DELETE). Полезная нагрузка может быть
преобразована в нужный формат (XML, JSON) и кодировку, которую ожидает REST сервис.
За кулисами
Перейдем к детальному описанию работы REST адаптера, какие выполняются шаги адаптера и как
эти шаги конфигурировать.
Общие для всех адаптеров настройки я описывать не буду (HTTP Security, Timeout, QoS и т.п)
Входящие REST сервисы.
Используя REST адаптер вы можете сконфигурировать IFlow с REST API на стороне отправителе (on
sender side). Адаптер будет конвертировать входящие HTTP сообщения в XI сообщения и наоборот
(для синхронных сценариев).
REST адаптер позволяет делать динамическое определение получателя (channel selection),
используя URL, название HTTP операции или на основе контента .3
По умолчанию адаптер принимает сообщения по следующему URL:
http:<myHost>:<myPort>/RESTAdapter/
На картинке показаны шаги при обработке входящего HTTP.
Шаг 1. Определение канала из URL, нагрузки и HTTP Операций.
Фиксированный URL.
В большинстве случаев вы будете привязывать фиксированный URL к определенному каналу.
Вы должны указать channel endpoint name, вроде:
http:<myHost>:<myPort>/RESTAdapter/API/V2.0/Customer
Динамический URL.
Если вы хотите принимать только один REST API, то динамический урл практически не отличается
от статического. http:<myHost>:<myPort>/RESTAdapter/API/V2.0/Customer_Create
Если вы хотите принимать на один канал несколько REST API, то можно использовать параметры
URL: …/RESTAdapter/API/V2.0/{resource}/{id}?operation={opname}
3
The REST Adapter allows dynamic dispatching of an incoming HTTP call to a sender channel, by using the URL, the
HTTP operation or parts of the content as selection criteria. (оригинал)
Канал будет принимать URL как
…/RESTAdapter/API/V2.0/customer/123?operation=create так и
…/RESTAdapter/API/V2.0/order/222?operation=delete
Но не будет принимать …/RESTAdapter/API/V2.0/order?operation=create, т.к. в
URL нет параметра {id}
Фильтр по контенту4
Фиксированный URL может быть использован в нескольких Sender каналах. Можно настраивать
будут или нет приниматься сообщения с этого URL на основе контента. Вы можете ограничить в
канале прием сообщений только с определенным значением в каком-то теге во входящем JSON
или XML сообщении.
Фильтр по HTTP операции.
Вы также можете использовать имя HTTP операции (GET,PUT,POST,DELETE) для определения
получателя. Это позволит вам к примеру создать два IFlow с одним URL в Sender каналах, но один
будет использоваться для insert операций (POST), а другой для update (PUT).
В результате адаптер определит, какой канал использовать на основе входящих данных. Если
адаптер не найдет подходящий канал, то будет возвращена ошибка HTTP.
Шаг 2. Трансформация полезной нагрузки.
REST сервисы обычно используют JSON как формат нагрузки, в то время как PI привык работать с
XML. REST адаптер позволяет осуществлять преобразование JSON <-> XML.
Так же можно указать кодировку для полезной нагрузки.
Т.к. адаптер позволяет использовать полезную нагрузку для динамической конфигурации,
преобразование полезной нагрузки осуществляется на ранней стадии.
Шаг 3. Извлечение информации из URL, заголовков и полезной нагрузки.
На этом шаге информация из HTTP сохраняется в переменных (сконфигурированных или
определенных по умолчанию). 5 The placeholders in the URL pattern allow specifying dynamic parts of
the URL. В добавок к этому адаптер позволяет мэппить из HTTP сообщения параметры в хранимые
переменные, которые могут быть потом использованы в IFlow. Эти переменные потом
передаются в XI Headers.
Шаг 4. Определение REST операции.
REST вызов имеет предопределенные операции, такие как :
GET для получения данных об объекте, POST для создания объекта, PUT для обновления объекта,
DELETE для удаления объекта.
4
5
Content based channel filter (оригинал)
processed and stored in custom or predefined variables(оригинал)
Для примера операция HTTP DELETE в http://myhost:myport/customer/99 это
стандартный шаблон для удаления объекта customer с ID = 99. Но вид операции может быть
закодирован в URL или параметре URL и переопределить выполняемую операцию.
Таким образом REST URL может выглядеть так: HTTP POST
http://myhost:myport/customer/99?operation=remove
На этом шаге REST адаптер устанавливает REST операцию, основываясь на пользовательской
конфигурации.
После этого шага мы смэппили всю необходимую информацию из HTTP вызова в XI.
Шаг 5. Определение интерфейса/операции PI.
XI каналы обычно привязаны к определенному интерфейсу/операции и XI ожидает, что полезная
нагрузка в XML формате и в ней указано имя интерфейса/операции.
Будем считать, что полезная нагрузка пришла в JSON. Таким образом адаптер должен
преобразовать сообщение в JSON формате в формат XML и добавить имя операции / интерфейса.
Так как канал может принимать разные REST URL (см. шаг 1), то пользователь должен
сконфигурировать добавление корректного имени интерфейса, основываясь на входящем
сообщении. В этих правилах можно использовать сохраненные на шаге 3 значения и
использовать паттерны6, называемые Glob.
Text pattern matching using Globs
Если вы хотите установить паттерн, а не фиксированные значения, используйте Glob выражения.
REST поддерживает два символа подстановки :
Wildcard
character
?
*
Description
Example
Match exactly one unknown character
?at matches Cat, cat, Bat
bat, but not at
Match any number of unknown characters
(regardless of the position where it
appears, including at the start and/or
multiple times)
or
*Law* matches Law, GrokLaw,
Lawyer
or
Шаг 6. Отправка сообщения в PI.
Это последний шаг, на котором сообщение уходит в PI messaging system.
Опционально: обработка ответа в случае синхронной передачи.
При синхронной передаче XI сообщение преобразуется обратно в нужный формат и кодировку и
возвращается в систему – отправитель как результат HTTP вызова с кодом 200.
6
simple pattern matching type (оригинал)
Опционально: Обработка ошибок7
Исходящие REST сервисы. Вызов REST API.
Используя REST адаптер, вы можете вызывать REST сервисы как часть вашего IFlow. Адаптер
преобразует исходящие XI сообщения в HTTP вызов (в случае синхронной передачи возвращает
HTTP ответ в XI сообщении).
Note: то, что описано в предыдущем разделе в этом разделе повторяться не будет.
На картинке показаны шаги при обработке исходящего HTTP.
Шаг 1. Чтение XI сообщения.
На этом шаге сообщение принимается адаптером из PI messaging system и из него извлекается
полезная нагрузки и заголовки.
Шаг 2. Определение правил Operation Rules.
Если входящий Payload это XML, то адаптер извлекает из него имя операции/интерфейса8
Вы можете добавить свои правила, каким образом мэппить интерфейс и его неймспейс в
динамические переменные.
Рассмотрим на примере, каким образом можно смэппить операцию/интерфейс в REST resource и
REST operation.
Operation
Customer*
Order*
*Delete
*Create
7
8
Namespace
http://sap.com/xi/XI/Demo/
http://sap.com/xi/XI/Demo/
http://sap.com/xi/XI/Demo/
http://sap.com/xi/XI/Demo/
Variable
resource
resource
operation
operation
Не переводил. Смотрите в источнике
extracts the interface / operation name from the outermost XML element
Value
customer
order
DELETE
POST
Используя эти правила адаптер может смэппить операции типа “CustomerCreate”,
“CustomerDelete”, “OrderCreate” или “OrderDelete” в переменные, которые потом могут быть
использованы для динамической генерации URL.
Следующий пример использует Globs. Вы можете использовать fixed settings.
Operation
CustomerCreate
CustomerCreate
Namespace
http://sap.com/xi/XI/Demo/
http://sap.com/xi/XI/Demo/
Variable
resource
operation
Value
customer
POST
Шаг 3. Динамическая генерация URL.
Вызываемый URL может быть как статическим, так и сгенерированным динамически, с
использованием переменных, сохраненных на предыдущем шаге.
Для динамической генерации URL вы должны определить в URL плейсхолдеры. Они указываются
в фигурных кавычках {}.9
Например: http://www.google.com/finance/info?q={stock_symbol}
Этот плейсхолдер необходимо будет привязать к источнику, откуда будет браться значение.
Источники могут быть следующие:





“Manual Value”: just provide a manual value yourself
“Adapter Specific Attribute”: refer to an XI Header variable
“XPath”: reference an XML element from the incoming XML payload
“JSON Expression”: reference a JSON object
“Binding”: specify a value from the channel interface binding
Для каждого входного XML будет сгенерирован новый URL.
Шаг 3. Определение HTTP операции.
Так же как на предыдущем шаге, HTTP операция может быть указана статически, либо вычислена
на основе входящего сообщения.
If the HTTP operation has to be determined dynamically you specify the source of the value to be used
as selection criteria and provide a matching value or GLOB expression for each of the four HTTP
operations. The source types are the same is in previous step when generating the URL.
For rare cases when you need more than one rule per HTTP operation, the UI provides a table where
you can add more rules
Шаг 5. Определение HTTP заголовков.
Если REST сервис требует определенных HTTP Headers, они могут быть установлены вручную, либо
на основе динамических переменных, сохранённых на предыдущих шагах.
9
dynamic parts of the URL with placeholder variables in curly brackets (similar to sender channel configuration)
Шаг 6. Конвертация полезной нагрузки.
В случае когда входящая нагрузка в XML формате и содержит имя операции/интерфейса в корне,
а REST сервис не ожидает этого, то вы можете настроить адаптер, чтобы он исключил этот
элемент.
Если формат XML не совпадает с ожидаемым REST сервисом, то можно настроить кодировку и
настроить format convertion на этом шаге.
Шаг 7. Вызов REST сервиса.
Последний шаг это вызов REST сервиса. По HTTP коду возврата можно определить, завершился он
успешно или нет.
Finally
If you were brave and made it through all the previous sections without cheating and scrolling
forward, you should have a quite good understanding of the PI REST adapter by now.
I hope I could clarify architecture and configuration options, so that you now are ready and get
your hands dirty by setting up your own REST scenarios with the PI REST adapter. For a more
“hands on” experience, please check out the other REST Scenario Blog pages PI REST Adapter
- Blog Overview.
Don’t be afraid, it doesn’t bite.
Автор
guest_asv
Документ
Категория
Техническая документация
Просмотров
385
Размер файла
79 Кб
Теги
rest, sap pi, rest adapter, adapter
1/--страниц
Пожаловаться на содержимое документа