JSONレスポンス

CloudPRNTにおけるクライアントからのPOSTリクエストに対する、サーバーからのレスポンスは以下を参考に設定してください。

レスポンスヘッダー	レスポンスボディ
HTTPステータスコード	CloudPRNTで定義されたJSONデータ

サーバーから返されるレスポンス body は JSON フォーマットであり、下記のように設定してください。

{
    "jobReady": true|false,
    "mediaTypes": [ "<content media type>" ],
    "jobToken": "<string token>",
    "deleteMethod": "DELETE"|"GET",
    "clientAction": [ {"request": "<request type>", "options": "<request parameters>"} ],
    "claimBarcodeReader": [ "<device name>" ],
    "claimKeyboard": [ "<device name>" ],
    "display": [ { "name": "<device name>", "message": "<message markup>" } ],
    "jobGetUrl": "<alternative URL for job GET>",
    "jobConfirmationUrl": "<alternative URL for job confirmation>"
}

サーバーの応答は待機中の印刷ジョブの有無、また Client Action 要求等をクライアントに通知します。

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

Key Name	IFBD-HI01X/HI02X	mC-Print2/3	TSP100IV	TSP100IV SK	mC-Label3
jobToken	1.8以上	3.2以上	1.0以上	2.0以上	1.0以上
claimBarcodeReader	1.4以上	1.2以上	1.0以上	2.0以上	1.0以上
claimKeyboard	1.4以上	利用不可	利用不可	利用不可	利用不可
display	1.4以上	1.2以上	1.0以上	2.0以上	1.0以上
jobGetUrl	1.8以上	3.5以上	1.0以上	2.0以上	1.0以上
jobGetjobConfirmationUrl	1.8以上	3.5以上	1.0以上	2.0以上	1.0以上

注釈

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

• "jobReady"

  "true"の場合、サーバーに印刷データがあることを示しており、クライアントより印刷データ取得のためのhttp GET要求が発行されます。

  注釈

  プリンターがオフラインの間はGET要求は発行されず、POST要求が継続して発行されます。

  プリンターがオンラインに復帰後は、サーバーからjobReadyがtrueに設定された応答を受け取ることでGET要求が発行されます。

• "mediaTypes"

  サーバーによって提供されうる利用可能な印刷データのメディア(MIME)タイプのリスト。

  例えば、サーバーが印刷データをPNGまたはtext/plain形式にて提供できる場合(*)、クライアントはこれらの選択可能なタイプから好ましいフォーマットを選択します。

  *このときサーバーはビットイメージタイプとテキストタイプのそれぞれの印刷ジョブを用意する準備ができていると仮定します。

• "jobToken"

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

  サーバーにてジョブの印刷を開始するためjobReadyをtrueに設定するときに、本フィールドにてそのジョブに関連するすべての通信でクライアントによって使用される文字列トークンを指定することができます。

  jobToken値を指定することで、サーバーは特定のジョブに対するGETおよびDELETEリクエストを同期させることができます。

  また、サーバーは自由にjobToken値を割り当てることができます。

  例えば、UUID、ジョブ名、ジョブのハッシュ値、シーケンス番号などです。

  注釈

  jobTokenの指定値がクライアントで設定されるのは、jobReadyにtrueを指定およびjobTokenに文字列を指定、かつプリンターASBステータスがオンライン、かつプリンターが待機中である(printingInProgressがfalse)ときのみです。

  なお、クライアントでのDELETEリクエスト処理完了後に、サーバーから指定されたjobTokenはクライアントから削除されます。

  印刷中にプリンターASBステータスにエラーが発生した(紙無し、カバーオープン)場合、DELETEリクエストは発生せずPOSTリクエストが発生します。

  その場合は、サーバーから次のjobReady:trueを受信するまでjobTokenは削除されずPOSTリクエストに反映されます。

• "deleteMethod"

  プリンターからの印刷ジョブ完了の確認に、http DELETEまたはhttp GETのどちらを使うか指定します。

  このフィールドはオプションで、デフォルトでは http DELETEを使用します。

  Webサーバーからリソースを取り除く標準的な方法として、DELETEを使用することを一般的に推奨していますが、Web サーバーによってはCGIスクリプトへDELETE要求を渡すことができない場合があります。

  その代替方法として、このフィールドの GET指定によりプリンターが特定のクエリ文字列パラメーターを付けて GET要求を送信するよう設定できます。

• "clientAction"

  クライアントの特別な動作を要求します。

  Client Action を参照してください。

• "claimBarcodeReader"

  文字列の配列で、文字列はバーコードデータ読取用に要求されるバーコードリーダーデバイスの論理デバイス名を指定します。

  また代替的に、’true’のBoolean値を指定することもできます。

  この場合クライアント側で定義されているデフォルトのバーコードリーダーを要求します。

  バーコードリーダーの要求とは、読み取られたバーコードデータがサーバーへ通知されることを意味します。

  この要求の有効範囲は次のポーリングまでのため、バーコードデータを継続的に受け取りたい場合は毎回このフィールドを設定してください。

• "claimKeyboard"

  Some models are supported from specific firmware versions.

  An array of strings, each string is the logical device name of a Keyboard device to be claimed for input.

  Alternatively, a Boolean response of 'true' can be sent to claim the 'default' keyboard.

  Claiming a keyboard means that key presses will be reported to the server. The claim lasts only until the next poll, therefore the server should set this field every time if it wishes to receive keyboard activity continuously.

• "display"

  クライアント側で定義されたデフォルトカスタマーディスプレイに対するメッセージの文字列もしくはメッセージ表示用のカスタマーディスプレイの論理デバイス名およびメッセージの文字列の配列を指定してください。

  文字列の配列は以下2つの文字列フィールドを含みます。

  • "name"

    メッセージの送り先であるディスプレイデバイスの論理デバイス名を設定してください。

  • "message"

    ディスプレイに送信するためのメッセージで、CloudPRNTディスプレイマークアップに準じた文字列を設定してください。

    詳細は カスタマーディスプレイ を参照してください。

• "jobGetUrl"

  このフィールドはURL文字列を指定するオプションです(一部機種は特定のファームウェアバージョンよりサポート)。

  このフィールドはjobReadyがtrueに設定されている時、印刷ジョブファイルのダウンロードを管理するためのBLOBデータサーバーのような別サーバーへGET要求を実行するための代替URLを指定することができます。

  なお、プリンタ内部の指定されたURLの情報はGET要求発行後に削除されます。

• "jobConfirmationUrl"

  このフィールドはURL文字列を指定するオプションです(一部機種は特定のファームウェアバージョンよりサポート)。

  このフィールドはjobReadyがtrueに設定されている時、印刷完了確認のDELETE要求("deleteMethod"が"GET"に指定されている場合はGET要求)を実行するための代替URLを指定することができます。

  なお、プリンタ内部の指定されたURLの情報はDELETE要求発行後に削除されます。

クライアントとサーバー間の取り決めを簡素化するため、サーバーはclientAction要求と印刷を同時に設定すべきではありません。

もし、"jobReady"が trueで1 つ以上のclientAction要求があった場合、クライアントはまず印刷ジョブの取得(GET)を実行します。

印刷ジョブの取得後、clientAction要求を処理します。

なお、サーバーからのPOST応答に関する各HTTPレスポンスステータスコードを受け取り後のプリンターの動作例は下記となります。

ステータスコード	プリンター動作
200	サーバーからのレスポンスを解析し、内容に応じて各種リクエストを発行します。 印刷要求がない場合、印刷要求があるがプリンターがオフライン状態の場合： 特別な処理はせず、サーバーポーリング (POST) を継続します。 印刷要求がありプリンターがオンライン状態の場合： 印刷ジョブリクエスト (GET) を発行します。 clientAction要求がある場合： clientAction要求の実施、および結果を含めた サーバーポーリング (POST) を行います。
200以外	サーバーからのレスポンスを解析せず、サーバーポーリング (POST) を継続します。

サーバー POST レスポンスサンプル

印刷要求がない場合の通常サーバーレスポンスは以下のように設定してください。

{
    "jobReady": false
}

印刷要求がある場合の通常サーバーレスポンスは以下のように設定してください。

サーバーが印刷ジョブをテキストまたはPNG データ等にて生成した場合の例となります。(mediaTypesはサーバーで用意したジョブのメディアタイプを指定してください)

{
    "jobReady": true,
    "mediaTypes": ["text/plain", "image/png"]
}

jobToken付きの印刷要求がある場合の通常サーバーレスポンスは以下のように設定してください。

サーバーが印刷ジョブをPNG データを生成した場合の例となります。(mediaTypesはサーバーで用意したジョブのメディアタイプを指定してください)

{
    "jobReady": true,
    "mediaTypes": ["image/png"],
    "jobToken": "PrintJob1"
}

プリンターへポーリング間隔とサポートされる印刷ジョブのエンコードリストを通知するための要求付きサーバーレスポンスは以下のように設定してください。

{
    "jobReady": false,
    "clientAction": [
        {"request": "GetPollInterval", "options": ""},
        {"request": "Encodings", "options": ""}
    ]
}