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>"}]
    }],
    "display": [{
    "name": "<device logical name>",
    "status": {"connected": bool}
    }]
}

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

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

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

Key Name	mC-Print2/3
`jobToken`	3.2以上

Note

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

"status" - Star ASB 形式にてサーバーへプリンター状態情報を提供します。これが提供されない場合、サーバーは"2"から始まる statusCode であればプリンターがオンラインとみなすことができます。(例: statusCode が"200" の場合プリンターはオンライン)
"printerMAC" - プリンターの MAC アドレスをサーバーに提供します。これは原則的にクライアントを認識するための固有情報であり、必ずしも MAC アドレスである必要はなく、複数のクライアントがサーバーへ接続する場合の要求になります。例えば、Ethernet MAC アドレスを使用しています。
"uniqueID" - サーバーに ID が割り当てられている場合の ID。この Field はサーバーが ID を割り当てている場合にのみ含まれます。
"statusCode" - 3 桁の status code (http status codes に基づきますが互換ではありません。)およびプリンター状態の記述を提供します。典型的にこれは"200 OK"でプリンターがオンラインかつ印刷準備完了を示します。印刷ジョブ失敗またはオフラインの場合、エラー状態が渡されます。詳細はプリンターステータスコード章を参照ください。例えばプリンターが DELETE リクエストを送るときなど、URL パラメーターとして StatusCode を送る場合があるため、 CloudPRNT クライアントからの Status codes は 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" - 利用可能なバーコードリーダーデバイスを表すオブジェクトの配列。詳細は周辺機器制御バーコードリーダー章を参照してください。
"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
}

サーバーから"clientAction"要求を利用してポーリングインターバルやサポートされているエンコードのリスト、クライアントに対する“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
mC-Print2/3	3.2以上
TSP100IV	1.0以上
TSP100IV SK	2.0以上
mC-Label3	1.0以上

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

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

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

Device Name	FW Version
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リクエストを発行しません。
この振る舞いはclientActionのPaperPresentStatusMonitorで変更可能です。

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

{
    status: '23 6 0 0 0 0 0 0 0 ',
    printerMAC: '00:11:62:0d:82:98',
    statusCode: '201%20Output%20Paper%20Taken',
    printingInProgress: false,
    clientAction: null
}

"201"ステータスコードは"200"ステータスコードと同義です。(次のPOSTリクエストから"200"ステータスコードがクライアントから通知されます)。
このステータスコードが通知された後は、クライアントはサーバーから"jobReady:ture"が応答された場合、GETリクエストを発行します。

概要に戻る