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

クライアントはサーバーに印刷ジョブの完了を通知します。これは http DELETE 要求の発行によって行われ、サーバーに現在のジョブを消去することを通知します。クエリ文字列は http 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	mC-Print2/3	TSP100IV	TSP100IV SK	mC-Label3
`token`	3.2以上	1.0以上	2.0以上	1.0以上
`firmware`	3.5以上	1.0以上	2.0以上	1.0以上
`config`	n/a	n/a	n/a	1.0以上
`skip`	3.5以上	1.0以上	2.0以上	1.0以上(*1)
`error`	3.5以上	1.0以上	2.0以上	1.0以上

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

Note

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

uid - サーバーで指定する”uniqueID”が設定されます。これはサーバーが”clientAction”要求にて”uniqueID”を割り当てている場合にのみ含まれます。
code - プリンターステータスコード章に記載の"2"または"5"から始まるコードがURLエンコードされた文字列で設定されます。(例: "200 OK")
mac - クライアントからの POST 要求の"printerMAC"フィールドに使用されているプリンターMACアドレスが設定されます。
token - この機能は、一部機種は特定のファームウェアバージョンよりサポートしております。tokenは、サーバーよりPOST応答の"jobToken"文字列が提供された場合にURLエンコードされた文字列で付与されます。これは、ジョブを一意に識別するためにサーバーが使用することができます。
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の情報がある場合は削除されます。

印刷失敗またはエラー

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

関連するプリンターステータスコードを付けて POST 要求をサーバーに送る。ステータスが OK(“2”から始まる)ではない場合、サーバーは印刷が成功しなかったと認識します。
クライアントがプリントデータに関連した失敗ではないと認識した場合、通常のポーリングに入ります。プリンターの問題が解決して再びオンラインになったとき、ジョブデータがサーバーに残っていれば再び GET 要求によるジョブの取得を試みます。
クライアントが有効な印刷ジョブを扱うことができないための印刷失敗であったと認識した場合、DELETE 要求を送ります。その際に、対応する"code"をプリンターステータスコード章で述べられたコードとします。 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

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

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

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

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

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

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

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

Device Name	FW Version
mC-Print2/3	3.5以上
TSP100IV	1.0以上
TSP100IV SK	2.0以上
mC-Label3	1.0以上

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
mC-Print2/3	3.2以上
TSP100IV	1.0以上
TSP100IV SK	2.0以上
mC-Label3	1.0以上

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