Postman や OpenAPI から SAP CPI の HTTP レシーバーへ

SAP CPI から接続する REST API の多くには、OpenAPI や Swagger のファイル、Postman コレクション、またはその両方が付いています。HTTP レシーバーアダプターに必要なものはすべてそこにあります。サーバー、パス、パラメーター、header、ボディの形です。やるべきことは、各要素を 1 文字も落とさずに正しい欄に移すことです。

この記事では、OpenAPI の操作と Postman のリクエストを HTTP レシーバーに 1 ステップずつ対応させ、最初の呼び出しが失敗する原因になりやすい細かな点を挙げます。

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：API に送るメッセージ header の名前を | で区切って並べます。
• ボディ：アダプターに届いた時点のメッセージボディです。通常は 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）：Content Modifier でメッセージ header として設定し、その名前を Request Headers に並べます。
5. リクエストボディ：requestBody のスキーマに従って、Content Modifier で JSON を組み立てます。
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 property から取ります。Request Headers には API が受け取るべき 2 つの header だけを並べているので、それ以外の header はすべて tenant にとどまります。

Postman のリクエストから

Postman のリクエストにも同じ情報が、別の場所に入っています。

• URL は多くの場合 {{baseUrl}} のような Postman 変数で始まります。SAP CPI では同じ {{…}} 構文が外部化パラメーターを表し、デプロイ時に設定します。テスト環境と本番環境で変わるベース URL を置くのにぴったりの場所です。
• パス変数（:orderId）とクエリパラメーターは、先ほどと同じく Address 欄と Query 欄に入れます。
• Headers タブは、Content Modifier の header と、Request Headers に並べるその名前になります。
• raw の JSON ボディは Content Modifier のボディになり、テスト用の値はそれぞれ式に置き換えます。
• Authorization タブから、どの認証を設定すべきかがわかります。Postman のトークンを iFlow にコピーせず、認証情報は tenant に保存してください。

最初の呼び出しが失敗する細かな原因

• Request Headers に * を指定すると、内部用のものも含めてすべてのメッセージ header が API に送られます。API が必要とする header だけを並べてください。
• Content-Type header がない、または誤っている：多くの API は application/json のない JSON ボディを拒否します。
• URL 内の値は URL セーフである必要があります。スペースやスラッシュを含む ID は、アドレスに入れる前にエンコードが必要です。
• エラーレスポンス：Throw Exception on Failure をオフにするとフローは続行し、${header.CamelHttpResponseCode} にステータスコードが入るので、Router でエラーを処理できます。
• ほとんどの API では JSON ボディの項目名は大文字と小文字を区別します。記憶に頼らず、スキーマからコピーしてください。

REST API ではなく OData サービスを呼び出す場合は、OData レシーバーの記事を参照してください。アドレスとボディで使う式については、SAP CPI の Camel Simple 式を参照してください。

Kitegra でできること

ブラウザー拡張機能 Kitegra が API 仕様の扱いを引き受けます。JSON または YAML の OpenAPI や Swagger のファイル、または Postman コレクションを渡すと、SAP Integration Suite のデザイナーで、その仕様にある URL、パス、クエリパラメーター、リクエスト header、JSON ボディの例を候補表示します。

仕様はブラウザーの中にとどまります。Kitegra が API 仕様を保存することはありません。拡張機能が iFlow の内容を保存、デプロイ、編集することはありません。tenant が変更されるのは、名前の付いた 4 つの操作のいずれかをクリックしたときだけで、これらの操作はオフにすることもできます。

自分の iFlow の HTTPS エンドポイントを同じように呼び出す方法は、サービスキーで HTTPS iFlow をテストするを参照してください。

Kitegra アカウントがなくても、モジュールごとに 5 つの iFlow で使えます。Free プランは 50、Starter は 100、Pro は 300 まで対応します。チームプランではメンバー全員が Pro を使え、Startup Team はモジュールごとに 300 の iFlow、Growth Team と Scale Team は上限なしです。Kitegra のローンチ期間中は、Free プランを含め、サインインしているすべての人がすべてのツールを使えます。プランを比較する。

次の iFlow で試してみましょう

Kitegra が SAP Integration Suite のデザイナーで何をするのかを読むか、Kitegra のほかの Chrome 拡張機能と並べて確認できます。

よくある質問