印刷ジョブ完了確認 (DELETE)

本HTTPメソッドを利用するCloudPRNTプロトコル

CloudPRNT Version HTTP

✓

CloudPRNT Version MQTT (Trigger POST)

✓

CloudPRNT Version MQTT (Full MQTT / Pass URL)

-
クライアントはサーバーに印刷ジョブの完了を通知します。
これはクライアントがhttp DELETEリクエストを発行してサーバーに現在のジョブを消去するよう通知することで処理されます。
クエリ文字列は 印刷ジョブリクエスト (GET) 要求と同等になりますが、 code パラメーターが付加され、 type パラメーターはなくなります。
DELETE要求はクライアントによって完了した、または処理できない印刷ジョブを消すために使用されます。
サーバーはクライアントがジョブを完了できたかどうか、 code パラメーターにより確認することができます。
また、一部の機種では更新ジョブの実行結果を通知します。
詳細は firmware, skip, error クエリパラメーターの説明や application/vnd.star.starconfigurationメディアタイプのジョブ実行結果 を参照してください。
[http/https]://[cloudprntURL]?uid=<printer ID>&mac=<MAC address>&code=<status code>(&token=<job token>)((&firmware=<result>)(&config=<result>)&skip=<number>&error=<number>)(&retry=<number>)

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

Query Parameter

IFBD-HI01X/HI02X

mC-Print2/3

TSP100IV

TSP100IV SK

mC-Label3

token

1.8以上

3.2以上

1.0以上

2.0以上

1.0以上

firmware

利用不可

3.5以上

1.0以上

2.0以上

1.0以上

config

利用不可

利用不可

利用不可

利用不可

1.0以上

skip

利用不可

3.5以上

1.0以上

2.0以上

1.0以上 (*1)

error

利用不可

3.5以上

1.0以上

2.0以上

1.0以上

(*1) 取得値は0のみとなります。

注釈

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

  • uid
    サーバーで指定する”uniqueID”が設定されます。
    これはサーバーが Client Action 要求にて”uniqueID”を割り当てている場合にのみ含まれます。
  • code
    プリンターステータスコード に記載の"2"または"5"から始まるコードがURLエンコードされた文字列で設定されます。(例: "200 OK")
  • mac
    クライアントからのPOST要求の"printerMAC"フィールドに使用されているプリンターMACアドレスが設定されます。
  • token
    この機能は、一部機種は特定のファームウェアバージョンよりサポートしております。
    tokenはURLエンコードされた文字列で、サーバーよりPOST応答の"jobToken"文字列が提供された場合に付与されます。
    これは、ジョブを一意に識別するためにサーバーが使用することができます。
  • firmware
    この機能は、一部機種は特定のファームウェアバージョンよりサポートしております。
    プリンターが、application/vnd.star.starconfiguration メディアタイプのジョブをサーバーから取得しファームウェア更新処理を実施した場合に、その実行結果が設定されます。(例: &firmware=success)
  • config
    この機能は、一部機種は特定のファームウェアバージョンよりサポートしております。
    プリンターが、application/vnd.star.starconfiguration メディアタイプのジョブをサーバーから取得し設定更新処理を実施した場合に、その実行結果が設定されます。(例: &config=success)
    詳細は application/vnd.star.starconfigurationメディアタイプのジョブ実行結果 を参照してください。
  • skip
    この機能は、一部機種は特定のファームウェアバージョンよりサポートしております。
    プリンターが、application/vnd.star.starconfiguration メディアタイプのジョブをサーバーから取得し処理を実施した場合に、処理をスキップされた項目数が設定されます。(例: &skip=0)
    詳細は application/vnd.star.starconfigurationメディアタイプのジョブ実行結果 を参照してください。
  • error
    この機能は、一部機種は特定のファームウェアバージョンよりサポートしております。
    プリンターが、application/vnd.star.starconfiguration メディアタイプのジョブをサーバーから取得し処理を実施した場合に、処理がエラーとなった項目数が設定されます。(例: &error=0)
    詳細は application/vnd.star.starconfigurationメディアタイプのジョブ実行結果 を参照してください。
  • retry
    プリンターが、DELETE要求に対するサーバーからのレスポンスの受信を失敗した場合に、自動的にリクエストを再送した回数が示されます。(例: &retry=2)
    詳細は ネットワークの信頼性とリクエストの再送信 を参照してください。

印刷ジョブ成功

印刷が正しく完了した場合、クライアントは code パラメーターを"200 OK"としてDELETE 要求をサーバーに送信し、 uid と mac , token パラメーターはGET要求の処理と同じものとします。
次にクライアントはPOST要求による通常のポーリングを始めます。
このとき、クライアントにてtokenの情報がある場合は削除されます。

印刷失敗またはエラー

印刷に失敗した場合、または印刷中にエラーが発生した場合、クライアントは下記のパターンに従います。

  1. 関連するプリンターステータスコードを付けてPOST要求をサーバーに送る。

    ステータスが OK(“2”から始まる)ではない場合、サーバーは印刷が成功しなかったと認識します。

  2. クライアントがプリントデータに関連した失敗ではないと認識した場合、通常のポーリングに入ります。

    プリンターの問題が解決して再びオンラインになったとき、ジョブデータがサーバーに残っていれば再びGET要求によるジョブの取得を試みます。

  3. クライアントが有効な印刷ジョブを処理できないために印刷が失敗したと判断した場合、対応するプリンターステータスコードを含むDELETE要求を送ります。

    DELETE 後、クライアントは通常のPOSTポーリングを再開します。 このとき、クライアントにてtokenの情報がある場合は削除されます。

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

レスポンスヘッダー

レスポンスBody

HTTPステータスコード

無し (JSONデータは含みません)

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

ステータスコード

プリンター動作

200 / 200以外

サーバーポーリング (POST) を発行します。

ネットワークの信頼性とリクエストの再送信

もしDELETE要求(もしくは代替方法のGET要求)に対するサーバーからのレスポンスの受信を失敗した場合、クライアントはそのリクエストの再送信を行います。
この場合、クエリパラメーターが追加され("retry= <x> "、 <x> は再試行の回数)、再送信であることが示されます。
この機能はリクエストが時々ロストしてしまうような信頼性の低いネットワークでの防護策を提供します。
しかし、ネットワークが不安定で完全な障害が発生した場合、サーバーが常に最終的なDELETE要求を受信できるとは限りません。

対応機種ファームウェアバージョンとリトライ回数:

FW Version

Retry (times)

mC-Print2/3 (3.4以下)

3

mC-Print2/3 (3.5以上)

5

TSP100IV (1.0以上)

5

TSP100IV SK (2.0以上)

5

mC-Label3 (1.0以上)

5

IFBD-HI01X/HI02X (1.5以上)

5

サーバーは、定期的なポーリング(POST)要求の”printingInProgress”フィールドを監視することによって、DELETE要求が失敗している状況をさらに補足することもできます。

もしDELETEもしくはエラーステータスコード付きのPOSTを受け取ってないにもかかわらず、この”printingInProgress”フィールドがtrueからfalseに変わったとき、サーバーはクライアントからのhttpリクエストがロストしたこと、および印刷が完了したことを推測することができます。

また、上記"printingInProgress"フィールドの監視と同様に、jobTokenを監視することでの推測も可能です。
通常、DELETE要求が発行されると以降のPOST要求からjobTokenの情報は削除されます。
そのため、プリンターでの実際の印刷が完了しているにもかかわらずDELETE要求がサーバー側で受け取れていないケースにて、GET要求の後にjobTokenが付与されていないPOST要求を受信した場合に、印刷が完了したことを推測することができます。

印刷ジョブ完了確認の代用 (GET)

あるWebサーバーはサーバー側のCGIスクリプトを経由したhttp DELETE要求をサポートしていません。
そのため、代用的な方法が提供されます。
このモードをサーバーが要求すると(詳しくは サーバーポーリング (POST) JSONレスポンス を参照してください)、クライアントはDELETE要求の代わりにhttp GET要求を送ります。
クライアントは“delete”をクエリ文字列パラメーターとして付加するため、この要求は 印刷ジョブリクエスト (GET) 要求とは異なります。
なお、他のクエリ文字列と動作は通常のDELETE要求と同等になります。

application/vnd.star.starconfigurationメディアタイプのジョブ実行結果

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

FW Version

Retry (times)

mC-Print2/3

3.5以上

TSP100IV

1.0以上

TSP100IV SK

2.0以上

mC-Label3

1.0以上

IFBD-HI01X/HI02X

利用不可
application/vnd.star.starconfiguration メディアタイプは、Star Configuration Format仕様に基づくJSON形式のデータ(仕様の詳細は こちら を参照してください)であり、その他のメディアタイプと異なりプリンターではジョブを取得した際に内部の更新処理を実施します。
また、その実行結果は以下のクエリパラメーターによりサーバーへ通知されます。
  • firmware =success (or failed)

    ファームウェア更新処理の結果を示します。

    • success: ファームウェア更新処理は成功しました

    • failed: ファームウェア更新処理は失敗しました(更新処理は中止)

  • config =success (or failed)

    設定更新処理の結果を示します。

    • success: 設定更新処理は成功しました

    • failed: 設定更新処理は失敗しました(更新処理は中止)

  • skip =<x> (<x>は数字)
    設定された数値はスキップされた項目の数を示します。
    DELETE要求で"firmware=success"と"skip=1 (任意の数)"が返された場合は、ジョブのデータに認識できない設定項目等が1つありその処理がスキップされたことを示します。
    (例えば、プリンターが未サポートのキー名がデータに書かれていた場合等)
  • error =<x> (<x>は数字)
    設定された数値は処理がエラーとなった項目の数を示します。
    DELETE要求で"firmware=failed"と"error=1 (任意の数)"が返された場合は、ジョブのデータの処理中に何らかのエラーが1つ発生し、処理全体が中止されたことを示します。
    起こる可能性のあるエラーについては下記例を参考にしてください。

[更新処理の失敗例]

application/vnd.star.starconfiguration メディアタイプのデータの更新処理でエラーとなるパターンは、以下のようにジョブデータ自体のエラー( code クエリパラメーターで511を通知)とジョブデータ解析・更新処理中のエラー( firmware / config クエリパラメーターがfailedを通知)があります。

ジョブデータ自体のエラー例 ( code=511%20Media%20Decoding%20Error ):

  • Star Configuration Format仕様のデータがJSON形式でない

  • Star Configuration Format仕様のデータに必須キー名"title"が未記載

  • Star Configuration Format仕様のデータの必須キー"version"がサポート外の値

    例：

    • "1.32" (リビジョンがない)

    • "1.3.a" (数字以外が含まれる)

    • "2.0.0" (メジャーバージョンが非対応の数値)

ジョブデータ解析・ファームウェア更新処理中のエラー例 ( code=200%20OK&firmware=failed ):

  • Star Configuration Format仕様のデータに"firmware"オブジェクトが5個以上含まれる

  • 必須キー名の記載がない、必須キー名の値が不正(例: "action": "up")

  • ファームウェアのダウンロードに失敗

  • ダウンロードしたファームウェアデータが不正(例: モトローラSレコード形式でなかった、機種ID不正(他機種のファームウエア)、モデル名、バージョン情報が不正)

ジョブデータ解析・設定更新処理中のエラー例 ( code=200%20OK&config=failed ):

  • パスワード保護項目にて入力したパスワードが不正 (パスワードはWeb Configuration UIで利用の値)

  • ジョブデータにファームウェア更新関連と設定更新関連が含まれている場合にて、ファームウェア更新処理に失敗した場合

クライアント 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 リクエストヘッダー を参照してください。