安全なウェブサービス統合の作成
概要
Web サービス統合は、Web リクエストを使って印刷を自動化するのに最適な方法です。これらのリクエストは HTTP 経由で行われますが、HTTP は安全ではありません。これを HTTPS で送信し、Web リクエスト内のデータを保護することは可能でしょうか？
可能ですが、Integration Builder や Administration Console から直接行うことはできません。代わりに、BarTender の Web アプリケーションである BarTender Print Portal に Web リクエストを送信します。BarTender Print Portal には安全な Integration Passthrough 機能があり、同じシステム上でリッスンしている統合に Web サービスリクエストを転送します。
この例では、BarTender Print Portal の下で動作する Internet Information Services (IIS)、統合、およびラベルファイルを安全に設定する方法を説明します。
対象バージョン
BarTender 2021 から BarTender 2022 R4
Print Portal
前提条件
BarTender Print Portal の Integration Passthrough 機能を使用するには、以下が必要です：
- Internet Information Services (IIS) マネージャー。これは Windows の機能で、Windows の機能の有効化または無効化 アプリケーションからインストールできます。
- BarTender Print Portal
- Web リクエストを送信するためのアプリケーション。このチュートリアルでは Postman と Insomnia を扱いますが、お好きなものを使用できます。
また、この例で使用するサンプルドキュメントはこちらです：
HTTPS の有効化
Integration Passthrough の接続を安全にするには、BarTender Print Portal に HTTPS をバインドする必要があります。これは IIS マネージャーで行います。
Microsoft では、HTTPS 用に Web サイトを構成する方法をステップバイステップで案内しています。デフォルトでは、BarTender Print Portal は IIS マネージャーのサイト一覧で BarTender として表示されます。この手順では自己署名証明書の作成と使用方法を説明していますが、認証局から取得した証明書がある場合は、自己署名証明書の部分を飛ばして同じ手順で証明書を使用できます。
バインドが完了すると、下のスクリーンショットのように、サイトバインディングのセクションに HTTP と HTTPS の両方が表示されます：
サイトやシステムの再起動は不要です。バインドは設定した時点ですぐに有効になります。
Integration Passthrough の有効化
Integration Passthrough は、BarTender Print Portal の設定ファイル内の設定です。デフォルトではこの設定はオフになっているため、今のまま Web リクエストを送信しても BarTender Print Portal は無視します。
設定を変更するには、管理者権限でテキストエディタを開くか、昇格できるアプリで設定ファイルを開く必要があります。Windows では標準ユーザーのままではファイルを保存できません。以下の手順を行ってください。
-
メモ帳を使う場合：
- スタートメニューからメモ帳を探します。
- 右クリックして管理者として実行を選択します。
- C:\inetpub\wwwroot\BarTender\ に移動し、settings.xml を開きます。
- 下の方までスクロールし、IntegrationPassthrough パラメータを探します。
- Enabled を "true" に変更します。
ファイルを保存したら、Passthrough を利用するすべてのコンポーネントが有効になったことを認識できるよう、いくつかのサービスを再起動する必要があります。
サービスの再起動
- サービス スナップインをスタートメニューまたはコントロールパネルから開きます。
- BarTender System Service を右クリックし、再起動 を選択します。
- 依存関係も再起動される旨の通知が表示されます。OK をクリックします。
- ダイアログが消えたら、すべての BarTender サービスの名前の横に「実行中」と表示されているはずです。
IIS アプリケーションプールの再起動
- IIS マネージャーを開きます。
- アプリケーションプールをクリックします。
- BPP_AppPool をクリックします。
- 右側のアクションリストで「停止」をクリックし、少し待ってから「開始」をクリックします。
統合の設定
統合自体は、他の Web サービス統合とほぼ同じように設定できます。各種 Web サービスリクエストのセットアップ概要は以下の通りです：
GET
- ラベルは名前付きデータソースを使用する必要があります。
- 統合では、Print Document アクションで名前付きデータソースを上書きする必要があります。
- 1 件のレコードがリクエスト URL の一部として送信されます。
POST
POST リクエストの場合、送信するレコード数によって 2 通りのセットアップがあります。
1 件のレコードを送信したい場合は、GET リクエストと同じ方法で統合とラベルファイルを設定できます。データは URL ではなくリクエストのボディに送信されます。
複数のレコードを送信したい場合は、以下のように設定します。
- ラベルは JSON や CSV などのテキストデータベースに接続します。
- 統合では、Print Document アクションでデータベースを %EventData% に上書きします。
- 1 件以上のレコードを、ラベルに接続したテキストデータベースと同じ形式でリクエストのボディに送信します。
この例では、サンプルファイルは 1 件のレコードで、GET または POST リクエストのどちらでも送信できます。これはよくある構成で、最もシンプルです。
詳細やトラブルシューティングについては、以下の記事もご参照ください：
サンプルの展開
サンプルを展開して設定するには、以下の手順に従ってください：
- サンプルパックをダウンロードします：TempIntegration.zip
- 統合ファイルとラベルファイルを C:\TempIntegration\ に展開します。
- 統合ファイルを開きます。
- Print Document アクションをクリックし、Print Options タブを開きます。
- プリンターをお使いのシステムにあるプリンターに変更します。
リクエストの設定
このセクションでは、Insomnia、Postman、または同様のアプリを使って Web リクエストを送信します。POST と GET のどちらでも、リクエストの URL には統合の URL が必要です。この URL は Integration Builder のサービスセクションで確認できます。下記のスクリーンショットはサンプル統合ファイルのものです。黄色でハイライトされている部分が統合の URL です：
Web サービス統合を使ったことがある方には、この URL はおなじみかもしれません。通常の Web サービスリクエストを送信する場合は、このフルパスの URL にリクエストを送って印刷をトリガーします。しかし、Passthrough を使う場合は、BarTender Print Portal にリクエストを送信し、どの統合に転送するかを指定する必要があります。そのために統合の URL を指定します。
GET と POST のどちらでも、Web リクエストの URL は以下の形式になります：
https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=[IntegrationURL]
この URL は統合ファイルに記載されているものとは異なります。Integration Passthrough を経由してリクエストが targetURL に転送される形です。
サンプルファイルの場合、統合 URL を埋め込むと、リクエストのフル URL は以下のようになります：
https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute
以下の例では上記の URL を使用しています。ご自身のファイルを使う場合は、サンプルの統合 URL をご自身の統合で確認した URL に置き換えてください。
http://localhost/BarTender/API/Integration/WebServiceIntegration/Execute
GET リクエストの作成
GET リクエストは、すべての情報を URL に含めて送信します。多くの場合、ヘッダー情報に入力しますが、Integration Passthrough では targetURL パラメータが必要なため、ラベルデータは別の場所に入力する必要があります。
Insomnia（下記スクリーンショット）では「Query」、Postman では「Params」が正しい入力場所です。
独自に URL を作成する場合は、各パラメータを & で区切ったキーと値のペアとして URL に追加してください（上記スクリーンショットの URL プレビュー参照）。
この例で使用しているデータは以下の通りです：
- URL: https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute
- キーと値のペア:
- Company: company
- IDNumber: 3
POST リクエストの作成
POST リクエストは、データを URL ではなくリクエストのボディに送信します。GET リクエストと同様に、POST リクエストにも targetURL パラメータが必要です。
統合ファイルの設定を確認すると、Input Data が JSON に設定されていることに気付くかもしれません。統合は JSON のキーと値のペアを自動的に変数として解析でき、追加の作業やアクションを追加する必要はありません。1 件のみレコードを送信する場合は、この方法が便利です。
この例で使用しているデータは以下の通りです：
- URL: https://localhost/BarTender/API/IntegrationServicePassthrough?targetURL=/Integration/Test1/Execute
- ボディデータ: {"Company": "The Company", "IDNumber": "3"}
リクエストの送信
すべての準備ができたら、リクエストを送信しましょう。
- 統合を開始します。テスト タブをクリックし、大きな緑色の 開始 ボタンをクリックします。
- Insomnia または Postman アプリで 送信 ボタンをクリックします。カスタムアプリを使う場合は、通常通りリクエストを実行してください。
- 統合画面に戻ると、メッセージ欄にメッセージが表示され始めるはずです。
- ジョブがスプーラーに送信されたというメッセージが表示されたら成功です。Integration Passthrough システムを通じてリクエストを送信し、ラベルの印刷ができました。
トラブルシューティング
思った通りに動作しませんか？よくある問題とその対処法を紹介します。
SSL ピア証明書または SSH リモートキーが正しくありません
初めてリクエストを送信した際に、次のようなエラーが表示されることがあります（スクリーンショットは Insomnia のものです）：
このエラーは自己署名証明書を使用している場合に表示されます。SSL 検証を無効にして、再度リクエストを送信してください。
404 Not Found
リクエストを送信した際、Integration Passthrough サービスから次のようなエラーメッセージが返されることがあります（スクリーンショットは Insomnia のものです）：
このエラーの主な原因は以下の通りです：
このエラーは、統合自体が起動していない場合に発生します。Passthrough が情報を転送しようとしても、受け取る統合が存在しないためです。Passthrough サービスは URL が間違っていると判断し、404 Not Found を返します。データを送信する前に、必ず統合を開始してください。
また、targetURL パラメータがない、または間違っている場合にもこのエラーが発生します。リクエストの設定 セクションを見直し、URL が正しいか、統合 URL の確認方法をチェックしてください。
さらに、Integration Passthrough が有効になっていない場合にもこのエラーが発生します。Integration Passthrough の有効化 セクションを参照し、設定方法を確認してください。
ラベルに %VariableName% のまま印刷される
ラベル上に % 付きの値が表示され、実際の情報が印刷されない場合があります。% 記号は統合で使われる変数を示しています。統合でこれらの変数に値が設定されていない場合、変数名そのものが印刷されます。
この場合、Web リクエストアプリで値（左側）が正しく入力されていないか、値が抜けている可能性があります。値は統合で設定されている変数名と一致している必要があります。これらの変数は Print Document アクションの Named Data Sources タブで確認できます。下記のスクリーンショットのように、Insomnia（黒字）の値が統合（白字）の変数名と一致していることに注目してください：
POST の JSON データでも同様です。
GET リクエストの場合のみ、Named Data Sources の設定が正しく、送信データとも一致しているのに変数名しか表示されない場合は、データの入力場所を確認してください。Insomnia や Postman で Header セクションにデータを入力している場合、このデータは Integration Passthrough サービスを通過しません。リクエストの設定 セクションに戻り、正しい場所にデータを入力しているか確認してください。
統合エラー
統合エラーが発生していますか？詳しいガイドはこちらをご覧ください：トラブルシューティングガイド：統合