概要

BarTender 2022 では、REST 呼び出しを使用して印刷ジョブを自動化できる RESTful API が導入されています。REST API は、アプリケーションとシステムがネットワークまたはインターネットを介してデータを相互にやり取りする最新の方法です。要求は、サーバーベースのリソースの機能を実行します (リソースの状態、形式、ステータスは変化することがあります)。また、関連するサーバー側の操作も実行します。このスタイルの API 呼び出しは、Print Portal REST API またはその他の REST API に非常に似ています。 上記の API には似ていませんが、これらの API 呼び出しの機能は、Integration Builder または Process Builder 操作の方に似ています。

対象

BarTender 2022 以降

Automation エディション以上

情報

REST API の要件

• バージョン: BarTender 2022 R1 以降
• エディション: Automation または Enterprise エディション
• 送信元のアプリケーション: カスタム、Swagger、Insomnia、Postman
  • IWA、NTLM、および基本認証をサポート
  • CORS をサポート
  • カスタムアプリケーションでは Curl、C#、および .NET 言語をサポート
• コマンドを受信する BarTender のインストール

API はポート 5159 を使用して機能します。API が REST コマンドを受信できるように、このポートを開く必要があります。

セキュリティ

REST API は、複数の種類の認証をサポートします。

• 基本認証
• 統合 Windows 認証 (IWA)
• Windows チャレンジ/レスポンス (NTLM)

既定では、基本認証は無効化されています。

Insomnia または Postman を使用して要求を送信する場合、認証を NLTM に設定します。

IWA を使用する場合、REST 要求を送信するアカウントには以下のプロパティが必要です。

• 要求を送信するユーザーには、サーバーにログインするアクセス許可が必要です。
• ユーザーには、Administration Console で設定される統合を管理するアクセス許可が必要です。

基本認証の使用

基本認証は既定で無効化されています。有効にするには、以下の手順を実行します。

1. C:\Program Files\Seagull\BarTender 2022\net5.0 に移動します。
2. appsettings.json を見つけます。
3. 末尾近くにある AuthenticationSchemes までスクロールして、Basic を False から True に変更します。
4. ファイルに保存します。
5. Administration Console を開きます。
6. 左側のメニューで [Windows サービス] に移動し、BarTender Integration Service を再起動します。

HTTPS を介した送信

REST API は Window の HTTP サーバー (Http.sys) 上に構築されています。しかし、接続を保護するために、HTTPS を使用するように REST API を設定できます。これは、内部 RESTful 要求でのみ機能します。現時点では、外部要求では機能しません。

統合で HTTPS を設定した場合と同様に、REST 要求は Print Portal で拒否されます。この処理には、証明機関からの SSL 証明書または自己署名済み SSL 証明書のいずれかが必要です。

1. 最初に、SSL 証明書を使用してHTTPS で Print Portal を保護します。
2. すべての RESTful 呼び出しを https://localhost/Bartender/api/actions に転送します。localhost の部分は、サーバー名または IP で置き換えます。

REST API コマンド

BarTender REST API で使用される REST コマンドは、POST、GET、および PATCH の 3 つだけです。各コマンドにおける API の動作を以下に示します。

現在展開されている操作を実行するために ID が使用されます。スクリプトを POST する際、スクリプトが API によって受け入れられた場合、ID は応答内に含まれます。 ID は、API サーバー上でスクリプトがアクティブな間だけ有効です。既定では 60 分ですが、POST メッセージで変更することができます。

GET を使用して取得できる変数は、統合の変数と同様です。 統合変数とグローバル変数に加えて、POST 操作で作成したローカル変数も取得できます。取得する値は、送信したスクリプト ID に相対的です。

POST スクリプト

POST コマンドを使用する際、BarTender でさまざまな操作を実行し、送信した後、これらの操作を実行したままにすることができます。既定では、操作は 60 分間持続しますが、この時間は変更できます。

POST では、BarTender で実行するさまざまな操作を指示できます。Integration Builder や Process Builder を使用したことがある場合、これらのカテゴリは、この 2 つのアプリケーションの両方で使用されるコマンドと同じ種類なので比較的見慣れたものです。カテゴリのリストを以下に示します。

• 印刷操作 - ドキュメント、コマンドスクリプト、BTXML スクリプトの印刷
• 入力操作 - ファイルの読み取り、シリアルポートのリスンなど
• 出力操作 - ログへのメッセージ書き込み、Web サービス要求の送信など
• 実行操作 - 変数の設定、シェルコマンドの実行など
• ファイル操作 - フォルダの作成、ファイルのコピー、ファイルの削除など
• 変換操作 - 検索と置換の操作、検索と削除など
• データベース操作 - SQL の実行、テキストからレコードセットへの変換、データベースレコードごとの操作など (以下の「データベース操作」セクションを参照)

POST を送信する場合、これらの操作は BTXML スクリプト、YAML、または JSON で記述できます。 稼働中の BTXML 統合がある場合、BTXML を使用するのが最もすばやい遷移である可能性があります。BTXML スクリプトの印刷の例を以下に示します。

以前に REST API を操作したことがある場合、新しい API インターフェイスを作成している場合、または JSON や YAML の操作経験が豊富な場合、API は、これらの呼び出しも受け入れます。 BTXML よりも読み取りが少しシンプルで簡単です。両方の形式の例をいくつか以下に示します。

POST を送信すると API が応答を返します。この応答には、スクリプトが受け入れられたかどうかを示す状態コードが含まれます。コード 201 を参照してください。このコードは、スクリプトが受け入れられ、実行がスケジュールされていることを示します。処理が正常に行われたことを示す応答を受信した場合、応答にはスクリプトの ID も含まれます。

しかし、別の応答を受信した場合は、各応答コードの完全なリストを含むヘルプドキュメントを参照して問題の診断を行ってください。このヘルプドキュメントの場所は、以下の「API リファレンス」セクションに記載されています。

データベース操作

データベース操作を実行する場合、データベース接続を指定する必要があります。 統合とは異なり、操作のダイアログからこれを指定することはできません。 この指定は、操作のプロパティのいずれかで行います。

接続を設定するには、API に操作を伝える接続ファイルが必要です。この接続ファイルは、データベース接続に加えて、カスタム SQL やエイリアスなど、指定した設定を定義します。 

データベース接続ファイルを作成するには、まず、データベースに接続して BarTender Designer で接続を設定します。接続を作成した後にデータベースのダイアログが開かない場合は、[ファイル] > [データベース接続設定] からダイアログを開きます。ダイアログの下部にある [エクスポート] ボタンをクリックします。

接続情報が XML 形式で保存されます。ユーザー名、パスワード、およびその他の識別情報はマスクされ、プレーンテキストでは保存されません。

作成したファイルは、データベース接続を使用する操作の ConnectionSetup プロパティで使用できます。接続は、その特定の操作でのみ機能するので、使用する各操作に対して 1 つ設定します。

API リファレンス

開始する際、ヘルプドキュメントのいくつかの場所を参照できます。このヘルプドキュメントは、BarTender Designer またはオンラインで参照できます。 Designer を開いた後、ポップアップを閉じて [ヘルプ] > [BarTender ヘルプ] に移動します。REST API のマニュアルにアクセスできる主な場所を以下に示します。

BTXML リファレンス

BTXML を使用してスクリプトを送信する場合、BarTender ヘルプファイルで完全な BTXML スクリプトリファレンスにアクセスできます。

ここには、BTXML の概要に加えて、タグの完全なリストを含む完全なリファレンスが含まれています。

YAML および JSON リファレンス

形式が若干異なることがありますが、YAML と JSON は同じ種類の変数と設定を使用します。ヘルプファイルの BarTender の YAML リファレンスには、ユーザーが使用できるすべての変数、スクリプト、および呼び出しの包括的なリストが含まれています。このリファレンスには、ここからアクセスできます。

YAML リファレンスには、API 内で使用可能なすべての操作が種類ごとにまとめられたリストが含まれています。各操作の短い説明も含まれています。 操作をクリックすると、各操作で使用可能なすべてのプロパティのリストおよび実践的な例を含むページが開きます。

この YAML リファレンスのメインページには、複数の操作をグループにまとめて、1 つのスクリプトとして API に送信するための操作の配列を作成する方法の一覧も含まれています。

ReDoc

ReDoc は API で使用できる 2 つのツールのうちの 1 つです。これには、例、各コマンドの種類に関する短い説明、および受信する可能性のある応答パターンと説明のリストが含まれています。

ReDoc には、hostname:5159/api/actions/reference/index.html からアクセスできます。hostname の部分は、BarTender をホストするコンピュータの名前で置き換えてください。この URL にブラウザでアクセスすると、API からのメッセージが表示されます。

各 API コマンドは、ページを下にスクロールするか、左側のメニューを使用して目的のコマンドを選択することによって見つけることができます。各コマンドにナビゲートする際は、スクロールのある右側のバーも移動し、API 呼び出しと応答の例を参照できる対話型のセクションが表示されます。

POST の場合、サンプル BTXML が表示されます。内容の種類を変更して、BTXML、YAML、および JSON の間で形式を切り替えることができます。一部の例には追加の例を含む 2 番目のドロップダウンメニューがあります。JSON の例が選択された POST コマンドのスクリーンショットを以下に示します。

例と例の仕組みの説明の下には、API から返される可能性のある応答のリストがあります。API は一般的な HTTP 応答コードを使用しますが、各コードは API に固有なものを示すためにカスタマイズされています (スクリプトの形式が間違っていることや、クライアントに認証済みのユーザーでないことなど)。

コマンドが正常に処理されたかどうかを示すために色分けされたコマンドの種類ごとの応答コードのセットがあります。緑の応答コードは展開して、正常に処理された応答コードの内容を参照できます。POST からの応答の例を以下に示します。

Swagger

Swagger は、BarTender Suite と共にパッケージ化されている API リファレンスおよびツールです。これには、完全なスクリプトと REST コマンドリファレンスが含まれています。Swagger を使用してスクリプトをテストすることもできます。

Swagger には、hostname:5159/swagger からアクセスできます。hostname の部分は、BarTender をホストするコンピュータの名前で置き換えてください。このアドレスを Web ブラウザに入力すると、マニュアルのフロントページが表示されます。

各コマンドをクリックすると、短い説明とテストツールが表示されます。右側にある [お試しください] ボタンをクリックすると、サーバーに送信する値を編集できます。Swagger では、カスタムスクリプトを含む 1 つのファイルを使用するか、下部にある要求本文の例を作り直すことができます。

値を編集した後、下にスクロールして大きな青い [実行] ボタンをクリックします。スクリプトがサーバーに送信され、応答が戻されます。POST コマンドで正常に処理された応答の例を以下に示します。

ReDoc と同様に、REST ツールの下に応答のリストがあります。返される可能性のあるすべての応答コードと短い説明が含まれています。処理が正常に行われたことを示す応答コードには、返される可能性のある例も含まれています。

スクリプトをテストするツールとして Swagger を使用して、運用環境で使用する前にスクリプトが正しく動作することを確認できます。システムの視覚的な表現を使用して、リアルタイムでのトラブルシューティングと応答パターンのチェックにも使用できます。