BarTender REST API の概要
概要
BarTender 2022 では、RESTful API が導入され、REST コールを使って印刷ジョブの自動化が可能になりました。REST API は、アプリケーションやシステム同士がネットワークやインターネットを介してデータをやり取りするための最新の方法です。リクエストは、サーバー上のリソースの状態や形、ステータスを変更したり、関連するサーバー側のアクションを実行したりします。Print Portal REST API や他の REST API を使ったことがある方には、この API コールのスタイルは馴染みがあるかもしれません。ただし、これらの API コールの動作は、前述の API とは異なり、Integration や Process Builder のアクションに近いものとなっています。
対象製品
BarTender 2022 以降
Automation Edition 以上
情報
REST API の要件
- バージョン：BarTender 2022 R1 以降
- エディション：Automation または Enterprise エディション
- 送信アプリケーション：カスタム、Swagger、Insomnia、Postman
- IWA、NTLM、ベーシック認証に対応
- CORS 対応
- カスタムアプリケーションでは Curl、C#、.NET 言語に対応
- コマンドを受信するために BarTender がインストールされていること
API はポート 5159 を使用するため、このポートを開放して REST コマンドを受信できるようにしてください。
セキュリティ
REST API は複数の認証方式に対応しています。
- ベーシック認証
- 統合 Windows 認証（IWA）
- Windows チャレンジ/レスポンス（NTLM）
デフォルトでは、ベーシック認証は無効になっています。
Insomnia や Postman でリクエストを送信する場合は、認証方式を NTLM に設定してください。
IWA を使用する場合、REST リクエストを送信するアカウントには以下の権限が必要です：
- リクエストを送信するユーザーがサーバーにログインできる権限を持っていること
- ユーザーが管理コンソールで統合の管理権限を持っていること
ベーシック認証の有効化
ベーシック認証はデフォルトで無効になっています。有効にするには、以下の手順を実行してください：
- C:\Program Files\Seagull\BarTender 2022\net5.0（最新版の場合は \net6.0）に移動します。
- appsettings.json を探します。
- 下の方にある AuthenticationSchemes を見つけ、Basic の値を false から true に変更します（すべて小文字で記載してください）。
- ファイルを保存します。
- 管理コンソール を開きます。
- 左側のメニューから Windows サービス に移動し、BarTender Integration Service を再起動します。
HTTPS での送信
REST API は Windows の HTTP サーバー（Http.sys）上で動作しますが、HTTPS を使って接続を保護するように設定することもできます。
統合で HTTPS を設定する場合と同様に、REST リクエストも Print Portal 経由で転送します。この作業には、認証局発行または自己署名の SSL 証明書が必要です。
- まず、SSL 証明書を使って Print Portal を HTTPS で保護 してください。
- すべての REST コールを https://localhost/Bartender/api/actions に向けてください。必要に応じて localhost をサーバー名や IP アドレスに置き換えてください。
REST API コマンド
BarTender REST API では、POST、GET、PATCH の 3 種類の REST コマンドのみを使用します。それぞれのコマンドが API とどのようにやり取りするかを以下にまとめます。
| HTTP | URL パス | |
| POST | /api/actions | サーバーで実行するスクリプトを送信する |
| GET | /api/actions/{id} | 実行中のスクリプトのステータスやメッセージを取得する |
| PATCH | /api/actions/{Id} | スクリプトのキャンセルやプロパティの変更を行う |
| GET | /api/actions | サーバーに送信されたスクリプトの一覧を取得する |
| GET | /api/actions/{Id}/variables | スクリプトに関連付けられた変数を取得する |
| GET | /api/actions/{Id}/variables/{VariableName} | スクリプトに関連付けられた特定の変数の値を取得する |
ID は、現在デプロイされているアクションを操作する際に使用します。スクリプトを POST すると、API がスクリプトを受け付けた場合、レスポンス内に ID が含まれます。この ID はスクリプトが API サーバー上でアクティブな間のみ有効です。デフォルトでは 60 分間ですが、POST メッセージで変更可能です。
GET で取得できる変数は、統合で使う変数と同様です。統合変数やグローバル変数、POST アクションで作成したローカル変数も取得できます。取得する値は、送信したスクリプト ID に紐づきます。
POST スクリプト
POST コマンドを使うと、BarTender にさまざまなアクションを実行させることができ、送信後もこれらのアクションを継続して実行させることができます。デフォルトでは、アクションは 60 分間持続しますが、時間は変更可能です。
POST では、BarTender に実行してほしい内容をさまざまなアクションで指示できます。Integration Builder や Process Builder を使ったことがある方には、これらのカテゴリは見覚えがあるはずです。以下は主なカテゴリです：
- 印刷アクション - ドキュメント印刷、コマンドスクリプト、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 デザイナーでデータベースに接続します。接続が完了したら、データベースダイアログが開いていない場合は ファイル > データベース接続の設定 から開きます。ダイアログ下部の エクスポート ボタンをクリックします。
これで接続情報が XML 形式で保存されます。ユーザー名やパスワードなどの識別情報は難読化されており、平文では保存されません。
ファイルができたら、データベース接続を使うアクションの ConnectionSetup プロパティで利用できます。接続はそのアクション専用となるため、使用する各アクションごとに設定してください。
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 は ホスト名:5159/api/actions/reference/index.html にあります（ホスト名は BarTender をホストしているコンピューター名です）。この URL をブラウザで開くと、API の画面が表示されます。
各 API コマンドは、ページをスクロールするか、左側のメニューから目的のコマンドに移動して確認できます。各コマンドに移動すると、右側のバーが連動してスクロールし、API コールやレスポンスの例をインタラクティブに確認できます。
POST では、サンプルの BTXML が表示されます。コンテンツタイプを変更することで、BTXML、YAML、JSON の形式を切り替えられます。例によっては、追加のサンプルを選択できるドロップダウンメニューもあります。以下は、JSON の例が選択された POST コマンドのスクリーンショットです。
例とその動作説明の下には、APIから返される可能性のあるレスポンス一覧が表示されます。APIは一般的なHTTPレスポンスコードを使用しますが、それぞれのコードにはAPI独自の意味が割り当てられています。たとえば、スクリプトの形式が間違っている場合や、クライアントが認証されていないユーザーである場合などです。
コマンドの種類ごとに異なるレスポンスコードが用意されており、コマンドが成功したかどうかを色分けで示しています。緑色のものは展開して、成功時のレスポンス内容を確認できます。以下はPOSTコマンドのレスポンス例です。
Swagger
Swaggerは、BarTenderスイートのインストール時に同梱されているAPIリファレンスおよびツールです。スクリプトやRESTコマンドのリファレンスがすべて含まれており、さらにスクリプトのテストにも利用できるのが特徴です。
Swaggerはhostname:5159/swaggerで利用できます。ここでhostnameはBarTenderをホストしているコンピュータ名です。このアドレスをWebブラウザに入力すると、ドキュメントのトップページが表示されます。
各コマンドはクリック可能で、簡単な説明とテストツールが表示されます。右側のTry it Outボタンをクリックすると、サーバーに送信したい値を編集できます。Swaggerでは、カスタムスクリプトを含むテキストファイルを使うことも、下部のリクエストボディにあるサンプルをもとに編集することもできます。
値の編集が終わったら、下にスクロールして大きな青いExecuteボタンをクリックします。これでスクリプトがサーバーに送信され、サーバーからレスポンスが返ってきます。
例えば、POSTコマンドで成功した場合のレスポンスは以下のようになります。
ReDocと同様に、RESTツールの下にはレスポンス一覧が表示されます。すべての可能なレスポンスコードと簡単な説明が記載されており、成功時のレスポンスコードには返される内容の例も示されています。
Swaggerは、スクリプトを本番環境に投入する前に正しく動作するかテストするためのツールとして利用できます。トラブルシューティングや、システムのレスポンスパターンをリアルタイムで視覚的に確認するのにも便利です。