JSONリクエスト

クライアントから送られるリクエストbodyはJSON フォーマットであり、下記のテンプレートに従います。

{
    "status": "<ASB Hex format>",
    "printerMAC": "<Ethernet MAC address>",
    "uniqueID": "<server assigned ID>",
    "statusCode": " <description>",
    "jobToken": "<token string>",
    "printingInProgress": bool,
    "clientAction": [{
    "request": "<request type>",
    "result": "<request result>"
    }],
    "barcodeReader": [{
    "name": "<device logical name>",
    "status": { "connected": bool, "claimed": bool },
    "scan": [ {"data": "<scanned barcode character sequence>",
    "symbology": "<symbology of scanned barcode>"}]
    }],
    "keyboard": [{
    "name": "<device logical name>",
    "status": { "connected": bool, "claimed": bool },
    "keyPresses": "<key presses since last poll>"
    }],
    "display": [{
    "name": "<device logical name>",
    "status": {"connected": bool}
    }]
}

statusCode 以外の全てのフィールドは任意オプションであり、必要により設定された場合にのみ特定されますが、NULLである場合もあるため、サーバーはどちらの場合も扱うことができる必要があります。

clientAction フィールドはサーバーが設定の詳細の問い合わせのために Client Action リクエストを送ったときに設定されます。 (例えば ファームウェアバージョンなど)、またはエンコードされていないプリンター装置の状態イベントをサーバーに通知するためにリクエストを送ったときに設定されます。

対応機種によっては、一部のJSONパラメーターは特定のファームウェアバージョンからサポートされています:

Key Name	IFBD-HI01X/HI02X	mC-Print2/3	TSP100IV	TSP100IV SK	mC-Label3
printingInProgress	1.4以上	1.2以上	1.0以上	2.0以上	1.0以上
jobToken	1.8以上	3.2以上	1.0以上	2.0以上	1.0以上
barcodeReader	1.4以上	1.2以上	1.0以上	2.0以上	1.0以上
keyboard	1.4以上	利用不可	利用不可	利用不可	利用不可
display	1.4以上	1.2以上	1.0以上	2.0以上	1.0以上

注釈

表に記載のないJSONパラメーター、対応機種については全てのファームウェアバージョンでサポートされています。

"status"

Star ASB形式にてサーバーへプリンター状態情報を提供します。

Star ASB形式のプリンターステータスについては、プリンターのコマンド仕様書を参照ください。

これが提供されない場合、サーバーは"2"から始まるstatusCodeであればプリンターがオンラインとみなすことができます。(例: statusCodeが"200"の場合プリンターはオンライン)
"printerMAC"

プリンターのMACアドレスをサーバーに提供します。

これは原則的にクライアントを認識するための固有情報であり、必ずしもMACアドレスである必要はなく、複数のクライアントがサーバーへ接続する場合の要求になります。

例えば、Ethernet MACアドレスを使用しています。
"uniqueID"

サーバーにIDが割り当てられている場合のID。

このFieldはサーバーがIDを割り当てている場合にのみ含まれます。
"statusCode"

3桁または4桁のstatus codeおよびプリンター状態の記述を提供します。

典型的にこれは"200 OK"でプリンターがオンラインかつ印刷準備完了を示します。

印刷ジョブ失敗またはオフラインの場合、エラー状態が渡されます。

詳細はプリンターステータスコードを参照ください。

例えばプリンターが DELETEリクエストを送るときなど、URLパラメーターとしてStatusCodeを送る場合があるため、CloudPRNTクライアントからのStatus codeはURL エンコードされています。
"jobToken"

オプションのフィールドとしてサポートしております(一部機種は特定のファームウェアバージョンよりサポート)。

CloudPRNTサーバーが、true値が設定された"jobReady"フィールド及び文字列値が設定された"jobToken"フィールドを含むPOSTレスポンスを返信した場合、以降の印刷ジョブ処理中(GETリクエストからDELETEリクエストまで)のCloudPRNTクライアントからのPOSTリクエストに本フィールドが含まれます。

CloudPRNTクライアントにてDELETE処理が終了後このフィールドは以降のPOSTリクエストから削除されます。

なお、CloudPRNTサーバーが"jobToken"フィールドを指定したときに印刷中にプリンターがオフラインステータス(紙無し、カバーオープン)になった場合このフィールドは、プリンターがオンラインステータスに復帰し、CloudPRNTサーバーからtrue値が設定された"jobReady"フィールドを含むPOSTレスポンスをCloudPRNTクライアントが受け取るまで通知されます。
"printingInProgress"

boolean値によって印刷操作が現在進行中であるかを示します。

これは印刷操作中にCloudPRNTサーバーにポーリングを発行するCloudPRNTクライアントによって提供されます。

これにより、例えばTrue値を示した場合には”jobReady”レスポンスフィールドを無視することができ、サーバーにて印刷ジョブが使用可能かどうかデータベース等の確認をすることを避けられます。

また、必要に応じてユーザーへのステータス表示にも使うことができます。

ただし、このフィールドはオプションであり全てのCloudPRNTクライアントに含まれない可能性があるので、印刷が完了したことを示すシグナルとして使用しないでください(印刷完了に関してはGET/DELETEおよびPOSTリクエストを監視してください)。
"clientAction"

サーバー要求に対する応答列。

Client Action を参照ください。

応答の必要がない場合、このフィールドは NULL値になります。
"barcodeReader"

利用可能なバーコードリーダーデバイスを表すオブジェクトの配列。

詳細は周辺機器制御バーコードリーダーを参照してください。
"keyboard"

利用可能なキーボードデバイスを表すオブジェクトの配列。

詳細は周辺機器制御キーボードを参照してください。.
"display"

利用可能なカスタマーディスプレイデバイスを表すオブジェクトの配列。

詳細は周辺機器制御カスタマーディスプレイを参照してください。

クライアント POST リクエストサンプル

通常のクライアントリクエストは、プリンターステータスおよび MAC アドレスを含みます。

{
    "status": "23 6 0 0 0 0 0 0 0 ",
    "printerMAC": "00:11:e5:06:04:ff",
    "statusCode": "200%20OK",
    "clientAction": null
}

サーバーから Client Action 要求を利用してポーリングインターバルやサポートされているエンコードのリスト、クライアントに対する“uniqueID”(例では”Star1”)の要求を含むレスポンスを受け取ったあと送信されるクライアントリクエストの例は以下になります。

{
    "status": "23 6 0 0 0 0 0 0 0 ",
    "printerMAC": "00:11:e5:06:04:ff",
    "uniqueID": "Star1",
    "statusCode": "200%20OK",
    "clientAction": [
    {"request":"GetPollInterval","result":"10"},
    {"request":"Encodings","result":"image/png; image/jpeg; application/vnd.star.raster;
    application/vnd.star.line; application/vnd.star.linematrix; text/plain; application/octet-stream"}
    ]
}

サーバーから"jobReady":"true"及び"jobToken":"PrintJob1"を含むPOSTレスポンスを受け取ったあと、クライアントからのGETリクエストによって取得した印刷ジョブを印刷中に送信される"jobToken"が含まれるクライアントPOSTリクエストの例は以下になります。

{
    "status": "23 6 0 0 0 0 0 0 0 ",
    "printerMAC": "00:11:e5:06:04:ff",
    "uniqueID": "Star1",
    "statusCode": "200%20OK",
    "jobToken": "PrintJob1",
    "printingInProgress": true,
    "clientAction": null
}

クライアント HTTP リクエストヘッダー

対応機種ファームウェアバージョン:

Device Name	FW Version
IFBD-HI01X/HI02X	1.8以上
mC-Print2/3	3.2以上
TSP100IV	1.0以上
TSP100IV SK	2.0以上
mC-Label3	1.0以上

詳細はクライアント HTTP リクエストヘッダーを参照してください。

用紙保持制御機能をサポートするプリンターのステータスコード

対応機種ファームウェアバージョン:

Device Name	FW Version
IFBD-HI01X/HI02X with TSP650IISK	1.9以上
TSP100IV SK	2.0以上
mC-Label3	1.0以上

用紙保持制御機能を持つプリンターは、排紙口に印刷した用紙が残っているかどうかを検知できます。

Star CloudPRNTクライアントは、"status" / "statusCode" パラメーターによって通知します。

参考: プリンターステータスコード

印刷中の場合

{
    "status": "23 6 0 0 0 0 0(or 2) 0 0 ",
    "printerMAC": "00:11:62:0d:82:98",
    "statusCode": "220%20Printing%20In%20Progress",
    "printingInProgress": true,
    "clientAction": null
}

この"220"ステータスコードは、"printingInProgress: true"と同義です。

印刷ジョブの印刷が完了した後（DELETEリクエスト後）、排紙口に用紙が残っている場合:

{
    "status": "23 6 0 0 0 0 2 0 0 ",
    "printerMAC": "00:11:62:0d:82:98",
    "statusCode": "221%20Output%20Paper%20Present",
    "printingInProgress": false,
    "clientAction": null
}

"221"ステータスコードが通知されている場合、クライアントはGETリクエストを発行しません。

この振る舞いは Client Action のPaperPresentStatusMonitorで変更可能です。

排紙口から用紙を取り出した後

{
    "status": "23 6 0 0 0 0 0 0 0 ",
    "printerMAC": "00:11:e5:06:04:ff",
    "uniqueID": "Star1",
    "statusCode": "200%20OK",
    "jobToken": "PrintJob1",
    "printingInProgress": true,
    "clientAction": null
}

"201"ステータスコードは"200"ステータスコードと同義です。(次のPOSTリクエストから"200"ステータスコードがクライアントから通知されます)。

このステータスコードが通知された後は、クライアントはサーバーから"jobReady:true"が応答された場合、GETリクエストを発行します。