Из Postman или OpenAPI в получатель HTTP в SAP CPI

Большинство REST API, к которым вы подключаетесь из SAP CPI, поставляются с файлом OpenAPI или Swagger, коллекцией Postman или и тем и другим. В них есть всё, что нужно адаптеру-получателю HTTP: сервер, путь, параметры, headers и структура тела. Задача — перенести каждую часть в нужное поле, не потеряв ни символа.

В этой статье операция OpenAPI и запрос Postman шаг за шагом сопоставляются с получателем HTTP, а также перечислены мелочи, из-за которых чаще всего падает первый вызов.

Что нужно получателю HTTP

• Address: полный URL операции. Может содержать выражения Simple, например ${property.orderId} для параметра пути.
• Query: строка запроса без ?, например notify=true.
• Method: GET, POST, PUT, PATCH или DELETE.
• Authentication: нет, Basic, Client Certificate, OAuth2 Client Credentials и другие, с учётными данными, хранящимися в tenant, а не прописанными в канале.
• Request Headers: имена headers сообщения, отправляемых в API, через |.
• Тело: то, чем является тело сообщения в момент, когда оно доходит до адаптера; обычно его собирают в Content Modifier или в маппинге.

Как читать операцию OpenAPI или Swagger

Возьмём операцию OpenAPI 3, которая создаёт отгрузку для заказа:

openapi: 3.0.3
servers:
  - url: https://api.example.com/v1
paths:
  /orders/{orderId}/shipments:
    post:
      parameters:
        - { name: orderId, in: path, required: true, schema: { type: string } }
        - { name: notify, in: query, schema: { type: boolean } }
        - { name: X-Request-Id, in: header, schema: { type: string } }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                carrier: { type: string }
                trackingNumber: { type: string }

1. Address: соедините URL сервера и путь. В Swagger 2.0 сервер разбит на schemes, host и basePath.
2. Параметры пути вроде {orderId}: замените каждый выражением, например ${property.orderId}.
3. Параметры запроса (in: query): перенесите их в поле Query.
4. Параметры header (in: header): задайте их как headers сообщения в Content Modifier и перечислите их имена в Request Headers.
5. Тело запроса: соберите JSON в Content Modifier по схеме из requestBody.
6. Схемы безопасности: создайте соответствующие учётные данные в tenant и выберите их в Authentication.

Результат: Content Modifier и канал

Для этой операции Content Modifier перед адаптером и канал-получатель HTTP выглядят так:

Content Modifier
  Header   Content-Type   application/json
  Header   X-Request-Id   ${property.requestId}
  Body     {
             "carrier": "${property.carrier}",
             "trackingNumber": "${property.trackingNumber}"
           }

HTTP receiver
  Address           https://api.example.com/v1/orders/${property.orderId}/shipments
  Query             notify=true
  Method            POST
  Request Headers   Content-Type|X-Request-Id

Content Modifier задаёт header Content-Type со значением application/json, header X-Request-Id и тело JSON со значениями из exchange properties, заданных раньше в потоке. В Request Headers перечислены ровно те два headers, которые должен получить API, поэтому все остальные headers остаются в tenant.

Из запроса Postman

Запрос Postman содержит ту же информацию, только в других местах:

• URL часто начинается с переменной Postman вроде {{baseUrl}}. В SAP CPI тот же синтаксис {{…}} обозначает вынесенный параметр, который задаётся при развёртывании, — естественное место для базового URL, который отличается в тестовой и продуктивной средах.
• Переменные пути (:orderId) и параметры запроса уходят в поля Address и Query, как и раньше.
• Вкладка Headers превращается в headers Content Modifier плюс их имена в Request Headers.
• Сырое (raw) тело JSON становится телом Content Modifier, где каждое тестовое значение заменено выражением.
• Вкладка Authorization подсказывает, какую аутентификацию настроить. Не копируйте токен из Postman в iFlow; храните учётные данные в tenant.

Мелочи, из-за которых падает первый вызов

• Request Headers со значением * отправляет в API все headers сообщения, включая внутренние. Перечисляйте только те headers, которые ожидает API.
• Отсутствующий или неверный header Content-Type: многие API отклоняют тело JSON без application/json.
• Значения в URL должны быть безопасны для URL: ID с пробелами или слешами нужно закодировать, прежде чем подставлять в адрес.
• Ответы с ошибкой: при выключенном Throw Exception on Failure поток продолжается, а ${header.CamelHttpResponseCode} содержит код состояния, так что Router может обработать ошибки.
• В большинстве API имена полей тела JSON чувствительны к регистру; копируйте их из схемы, а не по памяти.

Вызываете сервис OData? См. статью о получателе OData. О выражениях в адресе и теле — в статье Выражения Camel Simple в SAP CPI.

Чем помогает Kitegra

Расширение браузера Kitegra берёт работу со спецификацией API на себя. Передайте ему файл OpenAPI или Swagger в JSON или YAML либо коллекцию Postman, и в дизайнере SAP Integration Suite оно будет подсказывать URL, пути, параметры запроса, headers запроса и примеры тел JSON из этой спецификации.

Спецификация остаётся в вашем браузере: Kitegra никогда не сохраняет спецификации API. Расширение никогда не сохраняет, не развёртывает и не редактирует содержимое iFlow, а ваш tenant меняется только тогда, когда вы нажимаете одно из четырёх названных действий, и их можно отключить.

Как так же вызвать HTTPS-эндпоинт собственного iFlow, показано в статье о тестировании HTTPS iFlow с сервисным ключом.

Без аккаунта Kitegra расширение работает на 5 iFlow в каждом модуле. Тариф Free охватывает 50, Starter — 100, Pro — 300. На командных тарифах каждый участник получает Pro: 300 iFlow на модуль на Startup Team и без ограничений на Growth Team и Scale Team. Пока Kitegra запускается, все инструменты открыты для всех, кто вошёл в аккаунт, в том числе на тарифе Free. Сравните тарифы.

Попробуйте в следующем iFlow

Узнайте, что делает Kitegra в дизайнере SAP Integration Suite, или посмотрите его рядом с другими расширениями Kitegra для Chrome.

Частые вопросы