ตั้งแต่วันที่ 31 ธันวาคม 2020 ระบบจะไม่รองรับ Google Cloud Print อีกต่อไป โปรดดูบทความสนับสนุนเพื่อรับความช่วยเหลือในการย้ายข้อมูล

หน้านี้ได้รับการแปลโดย Cloud Translation API

พริเวต

Privet คือ Cloud Device Local Discovery API ที่บริการระบบคลาวด์ใช้ เอกสารนี้จัดระเบียบ เป็นส่วนต่างๆ ดังนี้

บทนำ: ข้อมูลเบื้องต้นเกี่ยวกับ Privet
การค้นพบ: กลไกการค้นพบในพื้นที่
ประกาศ: ประกาศการค้นพบในพื้นที่
API: API ส่วนตัวสำหรับอุปกรณ์ระบบคลาวด์ทั่วไป
Printer API: Privet API ที่เครื่องพิมพ์ใช้
ภาคผนวก: แผนภาพเสริม

1. บทนำ

อุปกรณ์ที่เชื่อมต่อกับระบบคลาวด์มีประโยชน์มากมาย โดยสามารถใช้บริการ Conversion ออนไลน์ โฮสต์คิวงานขณะที่อุปกรณ์ออฟไลน์ และเข้าถึงได้จากทุกที่ทั่วโลก อย่างไรก็ตาม เนื่องจากผู้ใช้รายหนึ่งๆ สามารถเข้าถึงอุปกรณ์ระบบคลาวด์ได้หลายเครื่อง เราจึงต้องมีวิธีค้นหาอุปกรณ์ที่อยู่ใกล้ที่สุดตามตำแหน่ง วัตถุประสงค์ของโปรโตคอล Privet คือการผสานความยืดหยุ่นของ อุปกรณ์ระบบคลาวด์เข้ากับกลไกการค้นหาในเครือข่ายที่เหมาะสม เพื่อให้อุปกรณ์ค้นพบได้ง่ายใน สภาพแวดล้อมใหม่

เป้าหมายของโปรโตคอลนี้มีดังนี้

ทำให้อุปกรณ์ในระบบคลาวด์ค้นพบได้ในพื้นที่
ลงทะเบียนอุปกรณ์ระบบคลาวด์กับบริการระบบคลาวด์
เชื่อมโยงอุปกรณ์ที่ลงทะเบียนกับตัวแทนในระบบคลาวด์
เปิดใช้ฟังก์ชันการทำงานแบบออฟไลน์
ลดความซับซ้อนในการติดตั้งใช้งานเพื่อให้สามารถใช้อุปกรณ์ขนาดเล็กได้

โปรโตคอล Privet ประกอบด้วย 2 ส่วนหลักๆ ได้แก่ การค้นพบและ API การค้นหาใช้เพื่อค้นหา อุปกรณ์ในเครือข่ายเฉพาะที่ และ API ใช้เพื่อรับข้อมูลเกี่ยวกับอุปกรณ์และ ดำเนินการบางอย่าง ในเอกสารนี้ อุปกรณ์หมายถึงอุปกรณ์ที่เชื่อมต่อกับระบบคลาวด์ ซึ่งใช้โปรโตคอล Privet

2. Discovery

การค้นหาเป็นโปรโตคอลที่อิงตาม Zeroconf (mDNS + DNS-SD) อุปกรณ์ต้องใช้การกำหนดที่อยู่ IPv4 Link-Local อุปกรณ์ต้องเป็นไปตามข้อกำหนด mDNS และ DNS-SD

http://www.rfc-editor.org/rfc/rfc3927.txt (IPv4 Link-local)
http://www.rfc-editor.org/rfc/rfc4862.txt (IPv6 Link-local)
http://www.rfc-editor.org/rfc/rfc6762.txt (mDNS)
http://www.rfc-editor.org/rfc/rfc6763.txt (DNS-SD)

อุปกรณ์ต้องแก้ไขชื่อที่ซ้ำกันตามข้อกำหนดข้างต้น

2.1 ประเภทบริการ

การค้นพบบริการ DNS ใช้รูปแบบต่อไปนี้สำหรับประเภทบริการ _applicationprotocol._transportprotocol ในกรณีของโปรโตคอล Privet ประเภทบริการสำหรับ DNS-SD ควรเป็น _privet._tcp

อุปกรณ์ยังสามารถใช้บริการประเภทอื่นๆ ได้ด้วย ขอแนะนำให้ใช้ชื่ออินสแตนซ์ของบริการเดียวกันสำหรับบริการทุกประเภทที่อุปกรณ์ใช้ เช่น เครื่องพิมพ์อาจใช้บริการ "Printer XYZ._privet._tcp" และ "Printer XYZ._printer._tcp" ซึ่งจะช่วยให้ผู้ใช้ตั้งค่าได้ง่ายขึ้น อย่างไรก็ตาม ไคลเอ็นต์ Privet จะค้นหาเฉพาะ "_privet._tcp"

นอกจากประเภทบริการหลักแล้ว อุปกรณ์ต้องโฆษณาระเบียน PTR สำหรับ ประเภทย่อยที่เกี่ยวข้อง (ดูข้อกำหนด DNS-SD: "7.1. Selective Instance Enumeration (Subtypes)") รูปแบบควรเป็นดังนี้ _<subtype>._sub._privet._tcp

ปัจจุบันระบบรองรับเฉพาะประเภทย่อยของอุปกรณ์ที่เป็นเครื่องพิมพ์ ดังนั้น เครื่องพิมพ์ทั้งหมดต้องประกาศระเบียน PTR 2 รายการ ดังนี้

_privet._tcp.local.
_printer._sub._privet._tcp.local.

2.2 ระเบียน TXT

การค้นหาบริการ DNS จะกำหนดฟิลด์เพื่อเพิ่มข้อมูลที่ไม่บังคับเกี่ยวกับบริการใน ระเบียน TXT ระเบียน TXT ประกอบด้วยคู่คีย์/ค่า คู่คีย์/ค่าแต่ละคู่จะเริ่มต้นจากไบต์ความยาว ตามด้วยข้อความสูงสุด 255 ไบต์ คีย์คือข้อความก่อนอักขระ "=" ตัวแรก และค่าคือข้อความหลังอักขระ "=" ตัวแรก จนถึงจุดสิ้นสุด ข้อกำหนดอนุญาตให้ไม่มีค่าในระเบียน ในกรณีดังกล่าวจะไม่มีอักขระ "=" หรือไม่มีข้อความหลังอักขระ "=" (ดูข้อกำหนด DNS-SD: "6.1. General Format Rules for DNS TXT Records" สำหรับรูปแบบระเบียน DNS TXT และ "6.2. ขนาดระเบียน DNS-SD TXT (สำหรับความยาวที่แนะนำ)

Privet กำหนดให้อุปกรณ์ส่งคู่คีย์/ค่าต่อไปนี้ในระเบียน TXT สตริงคีย์/ค่า ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ เช่น "CS=online" และ "cs=ONLINE" ถือเป็น สตริงเดียวกัน ข้อมูลในระเบียน TXT ต้องเหมือนกับข้อมูลที่เข้าถึงได้ผ่าน /info API (ดู 4.1 ส่วน API)

ขอแนะนำให้ระเบียน TXT มีขนาดไม่เกิน 512 ไบต์

2.2.1. txtvers

เวอร์ชันของโครงสร้าง TXT txtvers ต้องเป็นระเบียนแรกของโครงสร้าง TXT ปัจจุบัน รองรับเฉพาะเวอร์ชัน 1 เท่านั้น

txtvers=1

2.2.2. ty

ระบุชื่ออุปกรณ์ที่ผู้ใช้อ่านได้ เช่น

ty=Google Cloud Ready Printer Model XYZ

2.2.3. note (ไม่บังคับ)

ระบุชื่ออุปกรณ์ที่ผู้ใช้อ่านได้ เช่น

note=1st floor lobby printer

หมายเหตุ: คีย์นี้เป็นคีย์ที่ไม่บังคับและอาจข้ามได้ อย่างไรก็ตาม หากมีอยู่ ผู้ใช้ ควรแก้ไขค่านี้ได้ คุณต้องใช้คำอธิบายเดียวกันเมื่อลงทะเบียนอุปกรณ์

2.2.4. url

URL ของเซิร์ฟเวอร์ที่อุปกรณ์นี้เชื่อมต่ออยู่ (รวมถึงโปรโตคอล) เช่น

url=https://www.google.com/cloudprint

2.2.5. ประเภท

รายการประเภทย่อยของอุปกรณ์ที่อุปกรณ์นี้รองรับ (คั่นด้วยจุลภาค) รูปแบบคือ "type=_subtype1,_subtype2" ปัจจุบันระบบรองรับเฉพาะอุปกรณ์ย่อยประเภทเครื่องพิมพ์

type=printer

ควรโฆษณาสับไทป์แต่ละรายการที่ระบุโดยใช้ระเบียน PTR ที่เกี่ยวข้อง สำหรับบริการย่อยที่รองรับแต่ละรายการ ควรมีรายการที่สอดคล้องกัน 1 รายการ ชื่อประเภทย่อยของบริการ (<subtype>._sub._privet._tcp) ควรเท่ากับประเภทอุปกรณ์ที่นี่

2.2.6. id

รหัสอุปกรณ์ หากยังไม่ได้ลงทะเบียนอุปกรณ์ คีย์นี้ควรมีอยู่ แต่ค่า ควรว่างเปล่า เช่น

  id=11111111-2222-3333-4444-555555555555
  id=

2.2.7. cs

ระบุสถานะการเชื่อมต่อปัจจุบันของอุปกรณ์ ค่าที่เป็นไปได้ 4 ค่าได้รับการกำหนดไว้ใน ข้อกำหนดนี้

"ออนไลน์" หมายความว่าอุปกรณ์เชื่อมต่อกับระบบคลาวด์อยู่
"ออฟไลน์" หมายความว่าอุปกรณ์พร้อมใช้งานในเครือข่ายภายใน แต่ สื่อสารกับเซิร์ฟเวอร์ไม่ได้
"กำลังเชื่อมต่อ" แสดงว่าอุปกรณ์กำลังดำเนินการตามลำดับการเริ่มต้นระบบและยัง ไม่ได้ออนไลน์อย่างเต็มรูปแบบ
"not-configured" แสดงว่ายังไม่ได้กำหนดค่าการเข้าถึงอินเทอร์เน็ตของอุปกรณ์ ปัจจุบันยังไม่มีการใช้ค่านี้ แต่อาจมีประโยชน์ในข้อกำหนดเวอร์ชันอนาคต

ตัวอย่าง

cs=online
cs=offline
cs=connecting

หากอุปกรณ์ลงทะเบียนกับระบบคลาวด์แล้ว เมื่อเริ่มต้นระบบ อุปกรณ์ควรตรวจสอบการเชื่อมต่อกับเซิร์ฟเวอร์เพื่อตรวจหาสถานะการเชื่อมต่อ (เช่น เรียกใช้ Cloud API เพื่อรับการตั้งค่าอุปกรณ์) อุปกรณ์อาจใช้สถานะการเชื่อมต่อแชแนลการแจ้งเตือน (เช่น XMPP) เพื่อรายงานค่านี้ อุปกรณ์ที่ไม่ได้ลงทะเบียนเมื่อเริ่มต้นระบบอาจส่งคำสั่ง ping ไปยังโดเมนเพื่อตรวจหาสถานะการเชื่อมต่อ (เช่น ping www.google.com สำหรับอุปกรณ์ Cloud Print)

3. ประกาศ

เมื่อเปิดเครื่อง ปิดเครื่อง หรือเปลี่ยนสถานะ อุปกรณ์ต้องดำเนินการตามขั้นตอนการประกาศตามที่อธิบายไว้ในข้อกำหนด mDNS โดย ควรส่งประกาศที่เกี่ยวข้องอย่างน้อย 2 ครั้งโดยมีช่วงเวลาอย่างน้อย 1 วินาที ระหว่างประกาศ

3.1 สตาร์ทอัพ

เมื่อเริ่มต้นระบบ อุปกรณ์ต้องดำเนินการตามขั้นตอนการตรวจสอบและการประกาศตามที่อธิบายไว้ในข้อกำหนด mDNS ในกรณีนี้ควรส่งระเบียน SRV, PTR และ TXT ขอแนะนำให้จัดกลุ่มระเบียนทั้งหมดไว้ในการตอบกลับ DNS รายการเดียวหากเป็นไปได้ หากไม่ได้ใช้ เราขอแนะนำให้ใช้ลำดับต่อไปนี้ SRV, ระเบียน PTR และ TXT

3.2 ปิดการทำงาน

เมื่อปิดอุปกรณ์ ระบบควรพยายามแจ้งให้ทุกฝ่ายที่เกี่ยวข้องทราบโดยการส่ง "แพ็กเก็ตบอกลา" ที่มี TTL=0 (ตามที่อธิบายไว้ในเอกสารประกอบ mDNS)

3.3. อัปเดต

ในกรณีที่ข้อมูลใดๆ ที่อธิบายไว้ใน TXT มีการเปลี่ยนแปลง อุปกรณ์ต้องส่งประกาศอัปเดต ในกรณีนี้ คุณเพียงแค่ส่งระเบียน TXT ใหม่ก็เพียงพอแล้ว ตัวอย่างเช่น หลังจากลงทะเบียนอุปกรณ์แล้ว อุปกรณ์จะต้องส่งประกาศการอัปเดตซึ่งมีรหัสอุปกรณ์ใหม่

4. API

หลังจากค้นพบอุปกรณ์ในระบบคลาวด์แล้ว ระบบจะเปิดใช้การสื่อสารของไคลเอ็นต์กับอุปกรณ์ โดยตรงผ่านเครือข่ายท้องถิ่น API ทั้งหมดใช้ HTTP 1.1 รูปแบบข้อมูลอิงตาม JSON คำขอ API อาจเป็นคำขอ GET หรือ POST

คำขอแต่ละรายการต้องมีส่วนหัว "X-Privet-Token" ที่ถูกต้อง คำขอเดียว ที่อนุญาตให้มีส่วนหัว "X-Privet-Token" ว่างเปล่าคือคำขอ /privet/info (โปรดทราบ ว่าส่วนหัวยังคงต้องมีอยู่) หากไม่มีส่วนหัว "X-Privet-Token" อุปกรณ์ ต้องตอบกลับด้วยข้อผิดพลาด HTTP 400 ต่อไปนี้

HTTP/1.1 400 Missing X-Privet-Token header.

หากส่วนหัว "X-Privet-Token" ว่างเปล่าหรือไม่ถูกต้อง อุปกรณ์ต้องตอบกลับด้วย "ข้อผิดพลาด X-Privet-Token ไม่ถูกต้อง" (invalid_x_privet_token โปรดดูรายละเอียดในส่วนข้อผิดพลาด) ยกเว้น /info API ดูข้อมูลเพิ่มเติมเกี่ยวกับสาเหตุที่ต้องดำเนินการเช่นนี้และวิธีสร้างโทเค็น ได้ที่ภาคผนวก ก: การโจมตีและการป้องกัน XSSI และ XSRF

หาก API ที่ขอไม่มีอยู่หรือระบบไม่รองรับ อุปกรณ์ต้องแสดงข้อผิดพลาด HTTP 404

4.1 ความพร้อมใช้งานของ API

ก่อนที่จะเปิดเผย API ใดๆ (รวมถึง /info API) อุปกรณ์ต้องติดต่อเซิร์ฟเวอร์เพื่อตรวจสอบการตั้งค่าในเครื่อง การตั้งค่าในเครื่องต้องคงอยู่ระหว่างการรีสตาร์ท หากเซิร์ฟเวอร์ไม่พร้อมใช้งาน ควรใช้การตั้งค่าภาษาท้องถิ่นที่ทราบล่าสุด หากยังไม่ได้ลงทะเบียนอุปกรณ์ อุปกรณ์ควรใช้การตั้งค่าเริ่มต้น

อุปกรณ์ Cloud Print ต้องทำตามขั้นตอนด้านล่างเพื่อลงทะเบียน รับ และอัปเดตการตั้งค่าในเครื่อง

4.1.1. การลงทะเบียน

เมื่อลงทะเบียนอุปกรณ์ จะต้องระบุพารามิเตอร์ "local_settings" ดังนี้

{
       "current": {
                "local_discovery": true,
                "access_token_enabled": true,
                "printer/local_printing_enabled": true,
                "printer/conversion_printing_enabled": true,
                "xmpp_timeout_value": 300
        }
}

คุณตั้งค่าต่อไปนี้ได้

ชื่อค่า	ประเภทค่า	คำอธิบาย
local_discovery	บูลีน	ระบุว่าอนุญาตฟังก์ชันการค้นหาในเครือข่ายเดียวกันหรือไม่ หากเป็น "false" จะต้องปิดใช้ API ในเครื่องทั้งหมด (รวมถึง /info) และการค้นหา DNS-SD โดย ค่าเริ่มต้น อุปกรณ์ที่ลงทะเบียนใหม่ควรส่งค่า "จริง"
access_token_enabled	บูลีน (ไม่บังคับ)	ระบุว่าควรแสดง API /accesstoken ในเครือข่าย LAN หรือไม่ ค่าเริ่มต้นควรเป็น "true"
printer/local_printing_enabled	บูลีน (ไม่บังคับ)	ระบุว่าควรแสดงฟังก์ชันการพิมพ์ในเครื่อง (/printer/createjob, /printer/submitdoc, /printer/jobstate) ในเครือข่ายภายในหรือไม่ ค่าเริ่มต้นควรเป็น "true"
printer/conversion_printing_enabled	บูลีน (ไม่บังคับ)	ระบุว่าการพิมพ์ในเครื่อง อาจส่งงานไปยังเซิร์ฟเวอร์เพื่อทำการแปลงหรือไม่ ใช้ได้เมื่อเปิดใช้การพิมพ์ในพื้นที่เท่านั้น
xmpp_timeout_value	int (ไม่บังคับ)	ระบุจำนวนวินาทีระหว่าง การ Ping ช่อง XMPP โดยค่าเริ่มต้นต้องเป็น 300 (5 นาที) ขึ้นไป

สำคัญ: การไม่มีค่าใดๆ ที่เป็นค่าที่ไม่บังคับแสดงว่าอุปกรณ์ไม่รองรับฟังก์ชันที่เกี่ยวข้องเลย

4.1.2. สตาร์ทอัพ

เมื่อเริ่มต้นอุปกรณ์ อุปกรณ์ควรติดต่อเซิร์ฟเวอร์เพื่อตรวจสอบว่ามี API ใดบ้างที่พร้อมใช้งานในเครือข่ายท้องถิ่น สำหรับเครื่องพิมพ์ที่เชื่อมต่อกับ Cloud Print ควรโทรหา

/cloudprint/printer?printerid=<printer_id>

หรือ

/cloudprint/list

เราขอแนะนำให้ใช้ /cloudprint/printer มากกว่า /cloudprint/list แต่ทั้ง 2 รายการจะใช้งานได้

API นี้จะแสดงผลพารามิเตอร์ปัจจุบันของอุปกรณ์ รวมถึงการตั้งค่าสำหรับ Local API การตอบกลับจากเซิร์ฟเวอร์ จะมีรูปแบบดังนี้

"local_settings": {
        "current": {
                "local_discovery": true,
                "access_token_enabled": true,
                "printer/local_printing_enabled": true,
                "printer/conversion_printing_enabled": true,
                "xmpp_timeout_value": 300
         },
         "pending": {
                "local_discovery": true,
                "access_token_enabled": true,
                "printer/local_printing_enabled": false,
                "printer/conversion_printing_enabled": false,
                "xmpp_timeout_value": 500
         }
}

ออบเจ็กต์ "current" จะระบุการตั้งค่าที่มีผลในขณะนี้

ออบเจ็กต์ "pending" บ่งบอกถึงการตั้งค่าที่ควรใช้กับอุปกรณ์ (ออบเจ็กต์นี้อาจไม่มี)

เมื่ออุปกรณ์เห็นการตั้งค่า "รอดำเนินการ" อุปกรณ์จะต้องอัปเดตสถานะ (ดูด้านล่าง)

4.1.3. อัปเดต

หากต้องอัปเดตการตั้งค่า ระบบจะส่งการแจ้งเตือน XMPP ไปยังอุปกรณ์ การแจ้งเตือน จะอยู่ในรูปแบบต่อไปนี้

<device_id>/update_settings

เมื่อได้รับการแจ้งเตือนดังกล่าว อุปกรณ์ต้องส่งคำค้นหาไปยังเซิร์ฟเวอร์เพื่อรับการตั้งค่าล่าสุด อุปกรณ์ Cloud Print ต้องใช้

/cloudprint/printer?printerid=<printer_id>

เมื่ออุปกรณ์เห็นส่วน "รอดำเนินการ" เป็นผลลัพธ์ของ API /cloudprint/printer (เมื่อ เริ่มต้นหรือเนื่องจากการแจ้งเตือน) อุปกรณ์จะต้องอัปเดตสถานะภายในเพื่อจดจำการตั้งค่าใหม่ โดยจะต้องเรียกใช้ Server API เพื่อยืนยันการตั้งค่าใหม่ สำหรับเครื่องพิมพ์ระบบคลาวด์ อุปกรณ์ ต้องเรียกใช้ API /cloudprint/update และใช้พารามิเตอร์ "local_settings" เหมือนกับในระหว่าง การลงทะเบียน

เมื่อเชื่อมต่อกับช่อง XMPP อีกครั้ง อุปกรณ์ต้องเรียกใช้ API /cloudprint/printer เพื่อตรวจสอบว่ามีการเปลี่ยนแปลงการตั้งค่าในเครื่องตั้งแต่ครั้งล่าสุดหรือไม่

4.1.3.1. การตั้งค่าในเครื่องที่รอดำเนินการ

พารามิเตอร์ "local_settings" ที่อุปกรณ์ใช้เรียก API ของเซิร์ฟเวอร์ต้องไม่มีส่วน "pending"

4.1.3.2. การตั้งค่าในพื้นที่ปัจจุบัน

มีเพียงอุปกรณ์เท่านั้นที่เปลี่ยนส่วน "ปัจจุบัน" ของ "local_settings" ได้ ส่วนคนอื่นๆ จะเปลี่ยนส่วน "รอดำเนินการ" และรอจนกว่าอุปกรณ์จะเผยแพร่การเปลี่ยนแปลงไปยังส่วน "ปัจจุบัน"

4.1.4. ออฟไลน์

เมื่อติดต่อเซิร์ฟเวอร์ไม่ได้ในระหว่างการเริ่มต้นระบบ หลังจากได้รับการแจ้งเตือนแล้ว อุปกรณ์ต้องใช้การตั้งค่า ในเครื่องที่ทราบล่าสุด

4.1.5. การลบอุปกรณ์ออกจากบริการ

หากมีการลบอุปกรณ์ออกจากบริการ (เช่น GCP) ระบบจะส่งการแจ้งเตือน XMPP ไปยังอุปกรณ์ การแจ้งเตือนจะอยู่ในรูปแบบต่อไปนี้

<device_id>/delete

เมื่อได้รับการแจ้งเตือนดังกล่าว อุปกรณ์ต้องไปที่เซิร์ฟเวอร์เพื่อตรวจสอบสถานะ อุปกรณ์ Cloud Print ต้องใช้

/cloudprint/printer?printerid=<printer_id>

อุปกรณ์ต้องได้รับการตอบกลับ HTTP ที่สำเร็จโดยมี success=false และไม่มีคำอธิบายอุปกรณ์/เครื่องพิมพ์ ซึ่งหมายความว่าระบบได้นำอุปกรณ์ออกจากเซิร์ฟเวอร์แล้ว และอุปกรณ์ต้องลบข้อมูลเข้าสู่ระบบ และเข้าสู่โหมดการตั้งค่าเริ่มต้นจากโรงงาน

เมื่อใดก็ตามที่อุปกรณ์ได้รับการตอบกลับซึ่งระบุว่ามีการลบอุปกรณ์เนื่องจาก /cloudprint/printer API (การเริ่มต้น การแจ้งเตือนการตั้งค่าอัปเดต การ Ping รายวัน) อุปกรณ์จะต้องลบข้อมูลเข้าสู่ระบบ และเข้าสู่โหมดเริ่มต้น

4.2 /privet/info API

API ข้อมูลเป็น API ที่จำเป็นและอุปกรณ์ทุกเครื่องต้องใช้งาน ซึ่งเป็นคำขอ HTTP GET สำหรับ URL "/privet/info" ดังนี้ GET /privet/info HTTP/1.1

API ข้อมูลจะแสดงข้อมูลพื้นฐานเกี่ยวกับอุปกรณ์และฟังก์ชันที่รองรับ API นี้ ต้องไม่เปลี่ยนสถานะอุปกรณ์หรือดำเนินการใดๆ เนื่องจากมีความเสี่ยงต่อการโจมตีแบบ XSRF นี่เป็น API เดียวที่ได้รับอนุญาตให้มีส่วนหัว "X-Privet-Token" ว่างเปล่า ไคลเอ็นต์ควร เรียก API /privet/info โดยตั้งค่าส่วนหัว "X-Privet-Token" เป็น X-Privet-Token: ""

API ข้อมูลต้องแสดงข้อมูลที่สอดคล้องกับข้อมูลที่มีอยู่ในระเบียน TXT ระหว่างการค้นพบ

4.2.1. อินพุต

API /privet/info ไม่มีพารามิเตอร์อินพุต

4.2.2. รีเทิร์น

API /privet/info จะแสดงข้อมูลพื้นฐานเกี่ยวกับอุปกรณ์และฟังก์ชันที่รองรับ

คอลัมน์ TXT จะระบุฟิลด์ที่เกี่ยวข้องในระเบียน TXT ของ DNS-SD

ชื่อค่า	ประเภทค่า	คำอธิบาย	TXT
เวอร์ชัน	สตริง	เวอร์ชันสูงสุด (เมเจอร์.ไมเนอร์) ของ API ที่รองรับ ปัจจุบันคือ 1.0
ชื่อ	สตริง	ชื่ออุปกรณ์ที่ผู้ใช้อ่านได้	ty
คำอธิบาย	สตริง	(ไม่บังคับ) คำอธิบายอุปกรณ์ ควรแก้ไขได้โดย ผู้ใช้	โน้ต
URL	สตริง	URL ของเซิร์ฟเวอร์ที่อุปกรณ์นี้สื่อสารด้วย URL ต้องมี การระบุโปรโตคอล เช่น https://www.google.com/cloudprint	URL
ประเภท	รายการสตริง	รายการประเภทอุปกรณ์ที่รองรับ	ประเภท
id	สตริง	รหัสอุปกรณ์ ว่างเปล่าหากยังไม่ได้ลงทะเบียนอุปกรณ์	id
device_state	สตริง	สถานะของอุปกรณ์ ไม่ได้ใช้งาน หมายความว่าอุปกรณ์ พร้อม กำลังประมวลผล หมายความว่าอุปกรณ์กำลังทำงานและฟังก์ชันการทำงานอาจถูกจำกัดชั่วคราว หยุด หมายความว่าอุปกรณ์ไม่ทำงานและต้องมีการแทรกแซงจากผู้ใช้
connection_state	สตริง	สถานะของการเชื่อมต่อกับเซิร์ฟเวอร์ (base_url) ออนไลน์ - มีการเชื่อมต่อ ออฟไลน์ - ไม่มีการเชื่อมต่อ กำลังเชื่อมต่อ - กำลังดำเนินการตามขั้นตอนการเริ่มต้น ไม่ได้กำหนดค่า - ยังไม่ได้กำหนดค่าการเชื่อมต่อ อุปกรณ์ที่ลงทะเบียนอาจรายงานสถานะการเชื่อมต่อตามสถานะของช่องทางการแจ้งเตือน (เช่น สถานะการเชื่อมต่อ XMPP)	cs
ผู้ผลิต	สตริง	ชื่อผู้ผลิตอุปกรณ์
รุ่น	สตริง	รุ่นของอุปกรณ์
serial_number	สตริง	ตัวระบุอุปกรณ์ที่ไม่ซ้ำกัน ในข้อกำหนดนี้ ค่านี้ต้องเป็น UUID (ข้อกำหนด GCP 1.1) (ไม่บังคับ) เราขอแนะนำอย่างยิ่งให้ใช้รหัสหมายเลขซีเรียลเดียวกันทุกที่ เพื่อให้ไคลเอ็นต์ ที่แตกต่างกันระบุอุปกรณ์เดียวกันได้ ตัวอย่างเช่น เครื่องพิมพ์ที่ใช้ IPP อาจใช้รหัสหมายเลขซีเรียลนี้ในฟิลด์ "printer-device-id"
เฟิร์มแวร์	สตริง	เวอร์ชันเฟิร์มแวร์ของอุปกรณ์
ระยะเวลาทำงาน	int	จำนวนวินาทีตั้งแต่เปิดเครื่องอุปกรณ์
setup_url	สตริง	(ไม่บังคับ) URL (รวมถึงโปรโตคอล) ของหน้าที่มี วิธีการตั้งค่า
support_url	สตริง	(ไม่บังคับ) URL (รวมถึงโปรโตคอล) ของหน้าเว็บที่มี ข้อมูลการสนับสนุนและคำถามที่พบบ่อย
update_url	สตริง	(ไม่บังคับ) URL (รวมถึงโปรโตคอล) ของหน้าเว็บที่มี วิธีการอัปเดตเฟิร์มแวร์
x-privet-token	สตริง	ค่าของส่วนหัว X-Privet-Token ที่ต้องส่งไปยัง API ทั้งหมดเพื่อป้องกันการโจมตีแบบ XSSI และ XSRF ดูรายละเอียดได้ที่ 6.1
api	คำอธิบายของ API	รายการ API ที่รองรับ (อธิบายไว้ด้านล่าง)
semantic_state	JSON	(ไม่บังคับ) สถานะเชิงความหมายของอุปกรณ์ในรูปแบบ CloudDeviceState

api - เป็นรายการ JSON ที่มีรายการ API ที่พร้อมใช้งานผ่านเครือข่ายท้องถิ่น โปรดทราบ ว่า API บางรายการอาจไม่พร้อมใช้งานพร้อมกันในเครือข่ายท้องถิ่น เช่น อุปกรณ์ที่เพิ่งเชื่อมต่อ ควรจะรองรับเฉพาะ API /register เท่านั้น

"api": [
        "/privet/register",
]

เมื่อการลงทะเบียนอุปกรณ์เสร็จสมบูรณ์แล้ว อุปกรณ์ควรหยุดรองรับ /register API อุปกรณ์ควรตรวจสอบกับบริการเพื่อระบุว่า API ใดที่สามารถเปิดเผยผ่านเครือข่าย ท้องถิ่นได้ เช่น

"api": [
        "/privet/accesstoken",
        "/privet/capabilities",
        "/privet/printer/submitdoc",
]

ขณะนี้ API ต่อไปนี้พร้อมใช้งาน

/privet/register - API สำหรับการลงทะเบียนอุปกรณ์ผ่านเครือข่ายท้องถิ่น (ดูรายละเอียดได้ที่ /privet/register API) ต้องซ่อน API นี้เมื่อลงทะเบียนอุปกรณ์ในระบบคลาวด์เรียบร้อยแล้ว
/privet/accesstoken - API สำหรับขอโทเค็นเพื่อการเข้าถึงจากอุปกรณ์ (ดูรายละเอียดใน /privet/accesstoken API)
/privet/capabilities - API สำหรับดึงความสามารถของอุปกรณ์ (ดูรายละเอียดใน /privet/capabilities API)
/privet/printer/* - API สำหรับอุปกรณ์ประเภท "เครื่องพิมพ์" โดยเฉพาะ โปรดดูรายละเอียดใน API สำหรับเครื่องพิมพ์ โดยเฉพาะ

ตัวอย่างการตอบกลับ /privet/info มีดังนี้ (โปรดสังเกตว่าไม่มี API /privet/register เนื่องจาก นี่คืออุปกรณ์ที่ลงทะเบียนแล้ว)

{
        "version": "1.0",
        "name": "Gene’s printer",
        "description": "Printer connected through Chrome connector",
        "url": "https://www.google.com/cloudprint",
        "type": [
                "printer"
        ],
        "id": "11111111-2222-3333-4444-555555555555",
        "device_state": "idle",
        "connection_state": "online",
        "manufacturer": "Google",
        "model": "Google Chrome",
        "serial_number": "1111-22222-33333-4444",
        "firmware": "24.0.1312.52",
        "uptime": 600,
        "setup_url": "http://support.google.com/cloudprint/answer/1686197/?hl=en",
        "support_url": "http://support.google.com/cloudprint/?hl=en",
        "update_url": "http://support.google.com/cloudprint/?hl=en",
        "x-privet-token": "AIp06DjQd80yMoGYuGmT_VDAApuBZbInsQ:1358377509659",
        "api": [
                "/privet/accesstoken",
                "/privet/capabilities",
                "/privet/printer/submitdoc",
        ]
}

ต่อไปนี้คือตัวอย่างการตอบกลับ /privet/info สำหรับเครื่องพิมพ์ที่หมึกหมด (สังเกตฟิลด์ semantic_state)

{
        "version": "1.0",
        "name": "Gene’s printer",
        "description": "Printer connected through Chrome connector",
        "url": "https://www.google.com/cloudprint",
        "type": [
                "printer"
        ],
        "id": "11111111-2222-3333-4444-555555555555",
        "device_state": "stopped",
        "connection_state": "online",
        "manufacturer": "Google",
        "model": "Google Chrome",
        "serial_number": "1111-22222-33333-4444",
        "firmware": "24.0.1312.52",
        "uptime": 600,
        "setup_url": "http://support.google.com/cloudprint/answer/1686197/?hl=en",
        "support_url": "http://support.google.com/cloudprint/?hl=en",
        "update_url": "http://support.google.com/cloudprint/?hl=en",
        "x-privet-token": "AIp06DjQd80yMoGYuGmT_VDAApuBZbInsQ:1358377509659",
        "api": [
                "/privet/accesstoken",
                "/privet/capabilities",
                "/privet/printer/submitdoc",
        ],
        "semantic_state": {
                "version": "1.0",
                "printer": {
                        "state": "STOPPED",
                        "marker_state": {
                                "item": [
                                        {
                                                "vendor_id": "ink",
                                                "state": "EXHAUSTED",
                                                "level_percent": 0
                                        }
                                ]
                        }
                }
        }
}

4.2.3. ข้อผิดพลาด

API /privet/info ควรแสดงข้อผิดพลาดก็ต่อเมื่อไม่มีส่วนหัว X-Privet-Token เท่านั้น ต้องเป็นข้อผิดพลาด HTTP 400

HTTP/1.1 400 Missing X-Privet-Token header.

4.3 /privet/register API

/privet/register API เป็นทางเลือก ซึ่งเป็นคำขอ HTTP POST API /privet/register ต้องตรวจสอบ ส่วนหัว X-Privet-Token ที่ถูกต้อง อุปกรณ์ต้องใช้ API นี้ใน URL "/privet/register"

POST /privet/register?action=start&user=user@domain.com HTTP/1.1
POST /privet/register?action=complete&user=user@domain.com HTTP/1.1

อุปกรณ์ควรแสดง API /privet/register เมื่ออนุญาตให้ลงทะเบียนโดยไม่ระบุตัวตนในขณะนั้นเท่านั้น เช่น

เมื่อเปิดอุปกรณ์ (หรือหลังจากคลิกปุ่มพิเศษในอุปกรณ์) และยังไม่ได้ลงทะเบียน อุปกรณ์ควรแสดง API /privet/register เพื่ออนุญาตให้ผู้ใช้จากเครือข่าย LAN อ้างสิทธิ์เครื่องพิมพ์
หลังจากลงทะเบียนเสร็จแล้ว อุปกรณ์ควรหยุดแสดง /privet/register API เพื่อ ป้องกันไม่ให้ผู้ใช้รายอื่นในเครือข่ายท้องถิ่นอ้างสิทธิ์ในอุปกรณ์
อุปกรณ์บางเครื่องอาจมีวิธีลงทะเบียนอุปกรณ์ที่แตกต่างกัน และไม่ควรแสดง API /privet/register เลย (เช่น ตัวเชื่อมต่อ Chrome Cloud Print)

กระบวนการจดทะเบียนประกอบด้วย 3 ขั้นตอน (ดูการจดทะเบียนแบบไม่ระบุตัวตนสำหรับ Cloud Print)

เริ่มกระบวนการลงทะเบียนแบบไม่ระบุตัวบุคคล
ไคลเอ็นต์จะเริ่มกระบวนการนี้โดยการเรียกใช้ API /privet/register อุปกรณ์อาจรอ การยืนยันจากผู้ใช้ในเวลานั้น
รับโทเค็นการอ้างสิทธิ์

ไคลเอ็นต์จะสำรวจเพื่อดูว่าเมื่อใดที่อุปกรณ์พร้อมดำเนินการต่อ เมื่ออุปกรณ์พร้อมแล้ว อุปกรณ์จะส่งคำขอไปยังเซิร์ฟเวอร์เพื่อดึงโทเค็นการลงทะเบียนและ URL การลงทะเบียน ควรส่งคืนโทเค็น และ URL ที่ได้รับไปยังไคลเอ็นต์ ในขั้นตอนนี้ หากอุปกรณ์รับสายเรียกเข้าอีกสายเพื่อ เริ่มต้นการลงทะเบียน อุปกรณ์ควรทำดังนี้

หากเป็นผู้ใช้รายเดียวกันกับที่เริ่มการลงทะเบียน ให้ทิ้งข้อมูลก่อนหน้าทั้งหมด (หากมี) และเริ่มกระบวนการลงทะเบียนใหม่
หากเป็นผู้ใช้รายอื่น ให้แสดงข้อผิดพลาด device_busy และหมดเวลา 30 วินาที

ทำตามขั้นตอนการลงทะเบียนให้เสร็จสมบูรณ์

หลังจากที่ไคลเอ็นต์อ้างสิทธิ์อุปกรณ์แล้ว ไคลเอ็นต์ควรแจ้งให้อุปกรณ์ลงทะเบียนให้เสร็จสมบูรณ์ เมื่อกระบวนการลงทะเบียนเสร็จสมบูรณ์ อุปกรณ์ควรส่งประกาศการอัปเดต รวมถึงรหัสอุปกรณ์ที่เพิ่งได้รับ

หมายเหตุ: เมื่ออุปกรณ์กำลังประมวลผลการเรียก API /privet/register ระบบจะประมวลผลการเรียก API /privet/register อื่นๆ พร้อมกันไม่ได้ อุปกรณ์ต้องแสดงข้อผิดพลาด device_busy และหมดเวลา 30 วินาที

ขอแนะนำอย่างยิ่งให้ผู้ใช้ยืนยันการลงทะเบียนในอุปกรณ์ หากมีการติดตั้งใช้งาน อุปกรณ์ต้องรอการยืนยันจากผู้ใช้หลังจากได้รับคำขอ API /privet/register?action=start ไคลเอ็นต์จะเรียกใช้ API /privet/register?action=getClaimToken เพื่อดูว่าเมื่อใดที่ การยืนยันผู้ใช้เสร็จสมบูรณ์และโทเค็นการอ้างสิทธิ์พร้อมใช้งาน หากผู้ใช้ยกเลิกการลงทะเบียนในอุปกรณ์ (เช่น กดปุ่มยกเลิก) ระบบจะต้องแสดงข้อผิดพลาด user_cancel หากผู้ใช้ ยังไม่ได้ยืนยันการลงทะเบียนภายในกรอบเวลาที่กำหนด ระบบจะต้องแสดงข้อผิดพลาด confirmation_timeout ดูรายละเอียดเพิ่มเติมได้ที่ส่วนค่าเริ่มต้น

4.3.1. อินพุต

/privet/register API มีพารามิเตอร์อินพุตต่อไปนี้

ชื่อ	ค่า
การดำเนินการ	อาจเป็นค่าใดค่าหนึ่งต่อไปนี้ start - เพื่อเริ่มกระบวนการลงทะเบียน getClaimToken - ดึงโทเค็นการอ้างสิทธิ์สำหรับอุปกรณ์ cancel - เพื่อยกเลิกกระบวนการลงทะเบียน complete - เพื่อสิ้นสุดกระบวนการลงทะเบียน
ผู้ใช้	อีเมลของผู้ใช้ที่จะอ้างสิทธิ์อุปกรณ์นี้

ชื่อ

ค่า

การดำเนินการ

อาจเป็นค่าใดค่าหนึ่งต่อไปนี้
start - เพื่อเริ่มกระบวนการลงทะเบียน
getClaimToken - ดึงโทเค็นการอ้างสิทธิ์สำหรับอุปกรณ์
cancel - เพื่อยกเลิกกระบวนการลงทะเบียน
complete - เพื่อสิ้นสุดกระบวนการลงทะเบียน

ผู้ใช้

อีเมลของผู้ใช้ที่จะอ้างสิทธิ์อุปกรณ์นี้

อุปกรณ์ต้องตรวจสอบว่าอีเมลจากทุกการดำเนินการ (start, getClaimToken, cancel, complete) ตรงกัน

4.3.2. รีเทิร์น

/privet/register API จะแสดงข้อมูลต่อไปนี้

ชื่อค่า	ประเภทค่า	คำอธิบาย
การดำเนินการ	สตริง	การดำเนินการเดียวกันกับในพารามิเตอร์อินพุต
ผู้ใช้	สตริง (ไม่บังคับ)	ผู้ใช้คนเดียวกับในพารามิเตอร์อินพุต (อาจไม่มี หากละเว้นในอินพุต)
โทเค็น	สตริง (ไม่บังคับ)	โทเค็นการลงทะเบียน (ต้องระบุสำหรับ การตอบกลับ "getClaimToken" ไม่ต้องระบุสำหรับ "start", "complete", "cancel")
claim_url	สตริง (ไม่บังคับ)	URL การลงทะเบียน (ต้องระบุสำหรับ การตอบกลับ "getClaimToken" ละเว้นสำหรับ "start", "complete", "cancel") สำหรับเครื่องพิมพ์ระบบคลาวด์ URL ต้องเป็น "complete_invite_url" ที่ได้รับจากเซิร์ฟเวอร์
automated_claim_url	สตริง (ไม่บังคับ)	URL การลงทะเบียน (ต้องระบุสำหรับ การตอบกลับ "getClaimToken" ละเว้นสำหรับ "start", "complete", "cancel") สำหรับเครื่องพิมพ์ระบบคลาวด์ จะต้อง เป็น "automated_invite_url" ที่ได้รับจากเซิร์ฟเวอร์
device_id	สตริง (ไม่บังคับ)	รหัสอุปกรณ์ใหม่ (ละเว้นสำหรับคำตอบ "start" ต้องระบุสำหรับคำตอบ "complete")

อุปกรณ์ต้องแสดงรหัสอุปกรณ์ในการตอบกลับของ /privet/info API หลังจากลงทะเบียนเสร็จสมบูรณ์แล้วเท่านั้น

ตัวอย่างที่ 1:

{
        "action": "start",
        "user": "user@domain.com",
}

ตัวอย่างที่ 2:

{
        "action": "getClaimToken",
        "user": "user@domain.com",
        "token": "AAA111222333444555666777",
        "claim_url": "https://domain.com/SoMeUrL",
}

ตัวอย่างที่ 3:

{
        "action": "complete",
        "user": "user@domain.com",
        "device_id": "11111111-2222-3333-4444-555555555555",
}

4.3.3. ข้อผิดพลาด

API /privet/register อาจแสดงข้อผิดพลาดต่อไปนี้ (ดูรายละเอียดในส่วนข้อผิดพลาด)

ข้อผิดพลาด	คำอธิบาย
device_busy	อุปกรณ์กำลังทำงานอยู่และดำเนินการตามที่ขอไม่ได้ ลองอีกครั้ง หลังจากหมดเวลา
pending_user_action	ในการตอบกลับ "getClaimToken" ข้อผิดพลาดนี้บ่งชี้ว่า อุปกรณ์ยังคงรอการยืนยันจากผู้ใช้ และควรลองส่งคำขอ "getClaimToken" อีกครั้งหลังจาก หมดเวลา
user_cancel	ผู้ใช้ยกเลิกกระบวนการลงทะเบียนจากอุปกรณ์โดยตรง
confirmation_timeout	การยืนยันผู้ใช้หมดเวลา
invalid_action	มีการเรียกใช้การดำเนินการที่ไม่ถูกต้อง ตัวอย่างเช่น หากไคลเอ็นต์เรียกใช้ action=complete ก่อนเรียกใช้ action=start และ action=getClaimToken
invalid_params	ระบุพารามิเตอร์ที่ไม่ถูกต้องในคำขอ (ควรละเว้นพารามิเตอร์ที่ไม่รู้จัก เพื่อความเข้ากันได้ในอนาคต) เช่น ส่งคืนค่านี้หากไคลเอ็นต์ เรียกใช้ action=unknown หรือ user=
device_config_error	วันที่/เวลา (หรือการตั้งค่าอื่นๆ) ในฝั่งอุปกรณ์ไม่ถูกต้อง ผู้ใช้ต้องไปที่ (เว็บไซต์ภายในของอุปกรณ์) และกำหนดการตั้งค่าอุปกรณ์
ออฟไลน์	ขณะนี้อุปกรณ์ออฟไลน์อยู่และไม่สามารถสื่อสารกับเซิร์ฟเวอร์ได้
server_error	เกิดข้อผิดพลาดของเซิร์ฟเวอร์ระหว่างกระบวนการลงทะเบียน
invalid_x_privet_token	X-Privet-Token ไม่ถูกต้องหรือว่างเปล่าในคำขอ

อุปกรณ์ต้องหยุดแสดง API /privet/register หลังจากลงทะเบียนเสร็จสมบูรณ์แล้ว หากอุปกรณ์ไม่ได้เปิดเผย API /privet/register อุปกรณ์จะต้องแสดงข้อผิดพลาด HTTP 404 ดังนั้น หากมีการลงทะเบียนอุปกรณ์แล้ว การเรียก API นี้จะต้องแสดงผล 404 หากไม่มีส่วนหัว X-Privet-Token อุปกรณ์ต้องแสดงข้อผิดพลาด HTTP 400

4.4 /privet/accesstoken API

API /privet/accesstoken เป็น API ที่ไม่บังคับ เป็นคำขอ HTTP GET API /privet/accesstoken ต้องตรวจสอบ ส่วนหัว "X-Privet-Token" ที่ถูกต้อง อุปกรณ์ต้องใช้ API นี้ใน URL "/privet/accesstoken"

GET /privet/accesstoken HTTP/1.1

เมื่ออุปกรณ์ได้รับการเรียกใช้ API /accesstoken อุปกรณ์ควรเรียกใช้เซิร์ฟเวอร์เพื่อเรียกโทเค็นเพื่อเข้าถึง สำหรับผู้ใช้ที่ระบุและส่งคืนโทเค็นไปยังไคลเอ็นต์ จากนั้นไคลเอ็นต์จะใช้โทเค็นการเข้าถึงเพื่อเข้าถึงอุปกรณ์นี้ผ่านระบบคลาวด์

อุปกรณ์ Cloud Print ต้องเรียก API ต่อไปนี้

/cloudprint/proximitytoken

และส่งพารามิเตอร์ "printerid=<printer_id>" และ "user" จาก API ในเครื่อง หากทำสำเร็จ การตอบกลับของเซิร์ฟเวอร์จะมีออบเจ็กต์ต่อไปนี้

"proximity_token": {
        "user": "user@domain.com",
        "token": "AAA111222333444555666777",
        "expires_in": 600
}

อุปกรณ์ Cloud Print ต้องส่งค่าของออบเจ็กต์ "proximity_token" ในการตอบกลับ ไปยังการเรียก API /privet/accesstoken ในเครื่อง การที่อุปกรณ์ส่งพารามิเตอร์ทั้งหมด (รวมถึงพารามิเตอร์ที่ไม่ได้อธิบายไว้ในข้อกำหนดนี้) จะเป็นประโยชน์มากกว่า (รองรับการใช้งานในอนาคต)

4.4.1. อินพุต

API /privet/accesstoken มีพารามิเตอร์อินพุตต่อไปนี้

ชื่อ	ค่า
ผู้ใช้	อีเมลของผู้ใช้ที่ต้องการใช้โทเค็นเพื่อการเข้าถึงนี้ อาจว่างเปล่าในคำขอ

4.4.2. รีเทิร์น

API /privet/accesstoken จะแสดงข้อมูลต่อไปนี้

ชื่อค่า	ประเภทค่า	คำอธิบาย
โทเค็น	สตริง	โทเค็นเพื่อการเข้าถึงที่เซิร์ฟเวอร์ส่งคืน
ผู้ใช้	สตริง	ผู้ใช้คนเดียวกับในพารามิเตอร์อินพุต
expires_in	int	จำนวนวินาทีจนกว่าโทเค็นนี้จะหมดอายุ ได้รับจาก เซิร์ฟเวอร์และส่งผ่านในการตอบกลับนี้

ตัวอย่าง

{
        "token": "AAA111222333444555666777",
        "user": "user@domain.com",
        "expires_in": 600
}

4.4.3. ข้อผิดพลาด

API /privet/accesstoken อาจแสดงข้อผิดพลาดต่อไปนี้ (ดูรายละเอียดในส่วนข้อผิดพลาด)

ข้อผิดพลาด	คำอธิบาย
ออฟไลน์	ขณะนี้อุปกรณ์ออฟไลน์อยู่และไม่สามารถสื่อสารกับเซิร์ฟเวอร์ได้
access_denied	สิทธิ์ไม่เพียงพอ การเข้าถึงถูกปฏิเสธ อุปกรณ์ควรแสดงข้อผิดพลาดนี้ เมื่อเซิร์ฟเวอร์ปฏิเสธคำขออย่างชัดแจ้ง
invalid_params	ระบุพารามิเตอร์ที่ไม่ถูกต้องในคำขอ (ควรละเว้นพารามิเตอร์ที่ไม่รู้จัก เพื่อความเข้ากันได้ในอนาคต) เช่น หากไคลเอ็นต์เรียก /accesstoken?user= หรือ /accesstoken
server_error	เกิดข้อผิดพลาดกับเซิร์ฟเวอร์
invalid_x_privet_token	X-Privet-Token ไม่ถูกต้องหรือว่างเปล่าในคำขอ

หากอุปกรณ์ไม่ได้เปิดเผย API /privet/accesstoken อุปกรณ์จะต้องแสดงข้อผิดพลาด HTTP 404 หากไม่มีส่วนหัว X-Privet-Token อุปกรณ์ต้องแสดงข้อผิดพลาด HTTP 400

4.5 /privet/capabilities API

/privet/capabilities API เป็นทางเลือก เป็นคำขอ HTTP GET API /privet/capabilities ต้องตรวจสอบ ส่วนหัว "X-Privet-Token" ที่ถูกต้อง อุปกรณ์ต้องใช้ API นี้ใน URL "/privet/capabilities"

GET /privet/capabilities HTTP/1.1

เมื่ออุปกรณ์ได้รับการเรียก API /capabilities หากอุปกรณ์ทำได้ อุปกรณ์ควรติดต่อ เซิร์ฟเวอร์เพื่อรับความสามารถที่อัปเดตแล้ว เช่น หากเครื่องพิมพ์รองรับการโพสต์งานพิมพ์ (ที่ได้รับในเครื่อง) ไปยังตัวเครื่องเองผ่านบริการ Cloud Print เครื่องพิมพ์ควรแสดงความสามารถที่บริการ Cloud Print จะแสดง ในกรณีนี้ Cloud Print อาจเปลี่ยนแปลงความสามารถของเครื่องพิมพ์เดิม โดยการเพิ่มฟีเจอร์ใหม่ๆ ที่อาจทำงานก่อนส่งงานไปยังเครื่องพิมพ์ กรณีที่พบบ่อยที่สุดคือรายการประเภทเอกสารที่รองรับ หากเครื่องพิมพ์ออฟไลน์ ควรแสดงประเภทเอกสารที่รองรับ อย่างไรก็ตาม หากเครื่องพิมพ์ออนไลน์และลงทะเบียนกับ Cloud Print เครื่องพิมพ์จะต้องแสดง "*/*" เป็นประเภทที่รองรับประเภทหนึ่ง บริการ Cloud Print จะทำการแปลงที่จำเป็นในกรณีนี้ สำหรับการพิมพ์แบบออฟไลน์ เครื่องพิมพ์ต้องรองรับรูปแบบ "image/pwg-raster" อย่างน้อย

4.5.1. อินพุต

/privet/capabilities API มีพารามิเตอร์อินพุตต่อไปนี้

ชื่อ	ค่า
ออฟไลน์	(ไม่บังคับ) ต้องเป็น "offline=1" เท่านั้น ในกรณีนี้ อุปกรณ์ควรแสดงความสามารถสำหรับการใช้งานแบบออฟไลน์ (หากแตกต่างจากความสามารถ "ออนไลน์")

4.5.2. รีเทิร์น

API /privet/capabilities จะแสดงความสามารถของอุปกรณ์ในรูปแบบ JSON ของคำอธิบายอุปกรณ์ในระบบคลาวด์ (CDD) (ดูรายละเอียดในเอกสาร CDD) เครื่องพิมพ์อย่างน้อยที่สุดต้องแสดงรายการประเภทที่รองรับ ที่นี่ ตัวอย่างเช่น เครื่องพิมพ์ที่ใช้งานได้ในระบบคลาวด์ซึ่งออนไลน์อยู่ในขณะนี้อาจแสดงผลคล้ายกับตัวอย่างต่อไปนี้ (อย่างน้อย)

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        {
                                "content_type": "application/pdf",
                                "min_version": "1.4"
                        },
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "image/jpeg" },
                        { "content_type": "*/*" }
                ]
        }
}

และเมื่อยกเลิกการเชื่อมต่อจากเซิร์ฟเวอร์ ระบบอาจแสดงผลดังนี้

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        {
                                "content_type": "application/pdf",
                                "min_version": "1.4"
                        },
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "image/jpeg" }
                ]
        }
}

หมายเหตุ: เครื่องพิมพ์จะแสดงลำดับความสำคัญของประเภทเนื้อหาที่รองรับโดยใช้ลำดับ ตัวอย่างเช่น ในตัวอย่างด้านบน เครื่องพิมพ์ระบุว่าต้องการข้อมูล "application/pdf" มากกว่า "image/pwg-raster" และ "image/jpeg" ไคลเอ็นต์ควรพิจารณาลำดับความสำคัญของเครื่องพิมพ์หากเป็นไปได้ (ดูรายละเอียดในเอกสาร CDD)

4.5.3. ข้อผิดพลาด

API /privet/capabilities อาจแสดงข้อผิดพลาดต่อไปนี้ (ดูรายละเอียดในส่วนข้อผิดพลาด)

ข้อผิดพลาด	คำอธิบาย
invalid_x_privet_token	X-Privet-Token ไม่ถูกต้องหรือว่างเปล่าในคำขอ

หากอุปกรณ์ไม่ได้เปิดเผย API /privet/capabilities จะต้องแสดงข้อผิดพลาด HTTP 404 หากไม่มีส่วนหัว X-Privet-Token อุปกรณ์ต้องแสดงข้อผิดพลาด HTTP 400

4.6 ข้อผิดพลาด

API ข้างต้นจะแสดงข้อผิดพลาดในรูปแบบต่อไปนี้

ชื่อค่า	ประเภทค่า	คำอธิบาย
ข้อผิดพลาด	สตริง	ประเภทข้อผิดพลาด (กำหนดต่อ API)
คำอธิบาย	สตริง (ไม่บังคับ)	คำอธิบายข้อผิดพลาดที่มนุษย์อ่านได้
server_api	สตริง (ไม่บังคับ)	ในกรณีที่เกิดข้อผิดพลาดของเซิร์ฟเวอร์ ฟิลด์นี้จะมี API ของเซิร์ฟเวอร์ที่ไม่สำเร็จ
server_code	int (ไม่บังคับ)	ในกรณีที่เกิดข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ ฟิลด์นี้จะมี รหัสข้อผิดพลาดที่เซิร์ฟเวอร์ส่งคืน
server_http_code	int (ไม่บังคับ)	ในกรณีที่เกิดข้อผิดพลาด HTTP ของเซิร์ฟเวอร์ ฟิลด์นี้ จะมีรหัสข้อผิดพลาด HTTP ที่เซิร์ฟเวอร์ส่งคืน
เวลานอก	int (ไม่บังคับ)	จำนวนวินาทีที่ไคลเอ็นต์ต้องรอก่อน ลองอีกครั้ง (สำหรับข้อผิดพลาดที่กู้คืนได้เท่านั้น) ไคลเอ็นต์ต้องสุ่มค่าหมดเวลาจริงจากค่านี้เป็น ค่าที่เพิ่มขึ้น 20%

API ทั้งหมดต้องแสดงข้อผิดพลาด HTTP 400 หากไม่มีส่วนหัว X-Privet-Token

HTTP/1.1 400 Missing X-Privet-Token header.

ตัวอย่างที่ 1:

{
        "error": "server_error",
        "description": "Service unavailable",
        "server_api": "/submit",
        "server_http_code": 503
}

ตัวอย่างที่ 2:

{
        "error": "printer_busy",
        "description": "Printer is currently printing other job",
        "timeout": 15
}

5. Printer API

อุปกรณ์ประเภทหนึ่งที่โปรโตคอลนี้รองรับคือเครื่องพิมพ์ประเภท อุปกรณ์ที่รองรับประเภทนี้อาจ ใช้ฟังก์ชันการทำงานบางอย่างที่เฉพาะเจาะจงสำหรับเครื่องพิมพ์ โดยปกติแล้ว การพิมพ์ไปยังเครื่องพิมพ์ที่ใช้งานได้ในระบบคลาวด์จะ ผ่านเซิร์ฟเวอร์ Cloud Print ดังนี้

ในบางกรณี ลูกค้าอาจต้องส่งเอกสารในพื้นที่ อาจจำเป็นในกรณีที่ไคลเอ็นต์ไม่มี รหัส Google หรือไม่สามารถสื่อสารกับเซิร์ฟเวอร์ Cloud Print ได้ ในกรณีดังกล่าว ระบบจะส่งงานพิมพ์ไปยังเครื่องพิมพ์ในเครื่อง จากนั้นเครื่องพิมพ์จะใช้บริการ Cloud Print สำหรับ การจัดคิวงานและการแปลง เครื่องพิมพ์จะโพสต์งานที่ส่งในเครื่องไปยังบริการ Cloud Print อีกครั้ง แล้วขอรับงานดังกล่าวเนื่องจากมีการส่งผ่านระบบคลาวด์ กระบวนการนี้จะมอบ ประสบการณ์การใช้งานที่ยืดหยุ่นในแง่ของบริการ (Conversion) และการจัดการ/ติดตามงานพิมพ์

เนื่องจากบริการ Cloud Print ใช้การแปลง เครื่องพิมพ์จึงควรประกาศว่ารองรับรูปแบบอินพุตทั้งหมด ("*/*") ในรายการประเภทเนื้อหาที่รองรับ

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "*/*" }
                ]
        }
}

ในบางกรณี คุณอาจต้องการโซลูชันที่ทำงานแบบออฟไลน์โดยสมบูรณ์ เนื่องจากเครื่องพิมพ์รองรับรูปแบบอินพุตจำนวนจำกัด ไคลเอ็นต์จึงต้องแปลงเอกสารเป็นรูปแบบเครื่องพิมพ์ที่รองรับโดยเนทีฟ ไม่กี่รูปแบบ

ข้อกำหนดนี้กำหนดให้เครื่องพิมพ์ทั้งหมดต้องรองรับรูปแบบ PWG Raster ("image/pwg-raster") อย่างน้อย สำหรับกรณีการพิมพ์แบบออฟไลน์ เครื่องพิมพ์อาจรองรับรูปแบบอื่นๆ (เช่น JPEG) และหากไคลเอ็นต์รองรับ เครื่องพิมพ์อาจส่งเอกสารในรูปแบบนั้น เครื่องพิมพ์ต้องแสดงประเภทที่รองรับ ผ่าน /capabilities API เช่น

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "image/jpeg" }
                ]
        }
}

ไคลเอ็นต์เริ่มพิมพ์ผ่านเครือข่ายท้องถิ่นได้ 2 วิธี

การพิมพ์อย่างง่าย - ไคลเอ็นต์ส่งเอกสารผ่านเครือข่ายท้องถิ่นไปยัง API /submitdoc (โดยไม่ต้องระบุพารามิเตอร์ job_id) ระบบจะพิมพ์เอกสารที่ส่งโดยใช้การตั้งค่าตั๋วพิมพ์เริ่มต้น และไม่จำเป็นต้องมีสถานะของงานพิมพ์ หากเครื่องพิมพ์รองรับการพิมพ์ประเภทนี้เท่านั้น จะต้องโฆษณาเฉพาะ API /submitdoc ในการตอบกลับ API /privet/info

"api": [
        "/privet/accesstoken",
        "/privet/capabilities",
        "/privet/printer/submitdoc",
]

การพิมพ์ขั้นสูง - ไคลเอ็นต์ควรสร้างงานพิมพ์ในเครื่องพิมพ์ก่อนโดยเรียกใช้ API /privet/printer/createjob พร้อมตั๋วงาน CJT ที่ถูกต้องในคำขอ เครื่องพิมพ์ ต้องจัดเก็บตั๋วการพิมพ์ไว้ในหน่วยความจำและส่ง job_id กลับไปยังไคลเอ็นต์ จากนั้นไคลเอ็นต์จะ เรียกใช้ API /printer/submitdoc และระบุ job_id ที่ได้รับก่อนหน้านี้ เมื่อถึงเวลานั้น เครื่องพิมพ์จะเริ่มพิมพ์ ไคลเอ็นต์จะสำรวจสถานะของงานพิมพ์ในเครื่องพิมพ์โดยการเรียก API /privet/printer/jobstate

ในสภาพแวดล้อมแบบหลายลูกค้า เราไม่รับประกันว่าจะมีการเรียก API นี้อย่างไร ไคลเอ็นต์หนึ่งสามารถเรียกใช้ /createjob ระหว่างการเรียกใช้ /createjob->/submitdoc ของไคลเอ็นต์อื่นได้ เราขอแนะนำให้มีคิวงานพิมพ์ที่รอดำเนินการบนเครื่องพิมพ์จำนวนเล็กน้อย (อย่างน้อย 3-5 รายการ) เพื่อป้องกันการหยุดชะงักที่อาจเกิดขึ้นและปรับปรุงความสามารถในการใช้งาน

/createjob จะใช้ตำแหน่งแรกที่ว่างในคิว
อายุของงาน (ในคิว) อย่างน้อย 5 นาที
หากคิวเต็ม ระบบจะนำงานที่เก่าที่สุดซึ่งไม่ได้พิมพ์ออกและแทนที่ด้วยงานใหม่
หากมีงานพิมพ์ที่กำลังพิมพ์ในอุปกรณ์ (การพิมพ์แบบธรรมดาหรือขั้นสูง) /submitdoc ควรแสดงสถานะว่าไม่ว่างและเสนอการหมดเวลาเพื่อลองส่งงานพิมพ์นี้อีกครั้ง
หาก /submitdoc อ้างอิงถึงงานที่ถูกนำออกจากคิว (เนื่องจาก การแทนที่หรือหมดเวลา) เครื่องพิมพ์ควรแสดงข้อผิดพลาด invalid_print_job และ ไคลเอ็นต์จะลองกระบวนการอีกครั้งจากขั้นตอน /createjob ไคลเอ็นต์ต้องรอ ระยะหมดเวลาแบบสุ่มสูงสุด 5 วินาทีก่อนลองอีกครั้ง

หากข้อจำกัดด้านหน่วยความจำทำให้จัดเก็บงานที่รอดำเนินการหลายรายการในอุปกรณ์ไม่ได้ คุณอาจมีคิวงานพิมพ์ยาว 1 งาน โดยยังคงต้องเป็นไปตามโปรโตคอลเดียวกันกับด้านบน หลังจากงานเสร็จสมบูรณ์หรือล้มเหลวโดยมีข้อผิดพลาด เครื่องพิมพ์ควรจัดเก็บข้อมูลเกี่ยวกับสถานะของงานเป็นเวลาอย่างน้อย 5 นาที ขนาดคิวสำหรับจัดเก็บสถานะของงานที่เสร็จสมบูรณ์ควรมีอย่างน้อย 10 หากมีสถานะงานที่ต้องจัดเก็บเพิ่มเติม ระบบอาจนำสถานะงานที่เก่าที่สุดออกจากคิว ก่อนที่จะหมดเวลา 5 นาที

หมายเหตุ: ตอนนี้ไคลเอ็นต์จะสำรวจสถานะงาน ในอนาคต เราอาจกำหนดให้เครื่องพิมพ์ส่งการแจ้งเตือน DNS TXT เมื่อสถานะของงานพิมพ์มีการเปลี่ยนแปลง

5.1 /privet/printer/createjob API

/privet/printer/createjob API เป็น API ที่ไม่บังคับ (ดูการพิมพ์อย่างง่ายด้านบน) ซึ่งเป็นคำขอ HTTP POST API /privet/printer/createjob ต้องตรวจสอบส่วนหัว "X-Privet-Token" ที่ถูกต้อง อุปกรณ์ต้องติดตั้งใช้งาน API นี้ใน URL "/privet/printer/createjob"

POST /privet/printer/createjob HTTP/1.1

เมื่อได้รับ /privet/printer/createjob API call เครื่องพิมพ์ต้องสร้างรหัสงานพิมพ์ใหม่ จัดเก็บ ตั๋วงานพิมพ์ที่ได้รับในรูปแบบ CJT และส่งรหัสงานพิมพ์กลับไปยังไคลเอ็นต์

5.1.1. อินพุต

/privet/printer/createjob API ไม่มีพารามิเตอร์อินพุตใน URL เนื้อความของคำขอควรมีข้อมูลตั๋วงานพิมพ์ในรูปแบบ CJT

5.1.2. รีเทิร์น

API /privet/printer/createjob จะแสดงข้อมูลต่อไปนี้

ชื่อค่า	ประเภทค่า	คำอธิบาย
job_id	สตริง	รหัสของงานพิมพ์ที่สร้างขึ้นใหม่
expires_in	int	จำนวนวินาทีที่งานพิมพ์นี้ใช้ได้

ตัวอย่าง

{
        "job_id": "123",
        "expires_in": 600
}

5.1.3. ข้อผิดพลาด

API /privet/printer/createjob อาจแสดงข้อผิดพลาดต่อไปนี้ (ดูรายละเอียดในส่วนข้อผิดพลาด)

ข้อผิดพลาด	คำอธิบาย
invalid_ticket	ตั๋วการพิมพ์ที่ส่งไม่ถูกต้อง
printer_busy	เครื่องพิมพ์กำลังทำงานและไม่สามารถประมวลผล /createjob ได้ในขณะนี้ ลองอีกครั้ง หลังจากหมดเวลา
printer_error	เครื่องพิมพ์อยู่ในสถานะข้อผิดพลาดและต้องมีการโต้ตอบจากผู้ใช้เพื่อแก้ไข คำอธิบายควรมีคำอธิบายโดยละเอียดเพิ่มเติม (เช่น "กระดาษติดในถาด 1")
invalid_x_privet_token	X-Privet-Token ไม่ถูกต้องหรือว่างเปล่าในคำขอ

หากอุปกรณ์ไม่แสดง /privet/printer/createjob อุปกรณ์ต้องแสดงข้อผิดพลาด HTTP 404 หากไม่มีส่วนหัว X-Privet-Token อุปกรณ์ต้องแสดงข้อผิดพลาด HTTP 400

5.2 /privet/printer/submitdoc API

ต้องใช้ API /privet/printer/submitdoc เพื่อใช้การพิมพ์ผ่านเครือข่ายท้องถิ่น (ออฟไลน์หรือ โพสต์ไปยัง Cloud Print อีกครั้ง) ซึ่งเป็นคำขอ HTTP POST API /privet/printer/submitdoc ต้องตรวจสอบส่วนหัว "X-Privet-Token" ที่ถูกต้อง อุปกรณ์ต้องใช้ API นี้ใน URL "/privet/printer/submitdoc"

POST /privet/printer/submitdoc HTTP/1.1

เมื่อได้รับคำขอ API /privet/printer/submitdoc เครื่องพิมพ์ควรเริ่มพิมพ์ หากเริ่มพิมพ์ไม่ได้ จะต้องแสดงข้อผิดพลาด printer_busy และระยะหมดเวลาที่แนะนำเพื่อให้ไคลเอ็นต์รอ ก่อนที่จะลองอีกครั้ง

หากเครื่องพิมพ์ไม่สามารถเก็บข้อมูลทั้งหมดไว้ในบัฟเฟอร์ภายในได้ เครื่องพิมพ์ควรใช้กลไก TCP เพื่อชะลอการโอนข้อมูลจนกว่าจะพิมพ์เอกสารบางส่วน ซึ่งจะทำให้บัฟเฟอร์ บางส่วนพร้อมใช้งานอีกครั้ง (เช่น เครื่องพิมพ์อาจตั้งค่า windowsize=0 ในเลเยอร์ TCP ซึ่งจะทำให้ไคลเอ็นต์ต้องรอ)

การส่งเอกสารไปยังเครื่องพิมพ์อาจใช้เวลานาน ไคลเอ็นต์ควร ตรวจสอบสถานะของเครื่องพิมพ์และงาน (การพิมพ์ขั้นสูง) ได้ในขณะที่การพิมพ์กำลังดำเนินการอยู่ หากต้องการดำเนินการดังกล่าว เครื่องพิมพ์ต้องอนุญาตให้ไคลเอ็นต์เรียกใช้ API /privet/info และ /privet/printer/jobstate ขณะประมวลผลการเรียกใช้ API /privet/printer/submitdoc เราขอแนะนำให้ไคลเอ็นต์ทุกรายเริ่มเธรดใหม่เพื่อเรียกใช้ API /privet/printer/submitdoc เพื่อให้เธรดหลักใช้ API /privet/info และ /privet/printer/jobstate เพื่อตรวจสอบสถานะเครื่องพิมพ์และสถานะงานได้

หมายเหตุ: เมื่อพิมพ์งานในเครื่องเสร็จสมบูรณ์หรือยกเลิก เราขอแนะนำเป็นอย่างยิ่ง (และจะต้องรายงานในข้อกำหนดนี้เวอร์ชันในอนาคต) ให้รายงานสถานะสุดท้ายของงานไปยังอินเทอร์เฟซ /cloudprint/submit เพื่อวัตถุประสงค์ด้านการบัญชีและประสบการณ์ของผู้ใช้ ต้องระบุพารามิเตอร์ "printerid", "title", "contentType" และ "final_semantic_state" (ในรูปแบบ PrintJobState) รวมถึงพารามิเตอร์ "tag" (พารามิเตอร์ที่ทำซ้ำ) และ "ticket" (ตั๋วของงานในรูปแบบ CloudJobTicket) โปรดทราบว่า PrintJobState ที่ระบุต้องเป็นสถานะสุดท้ายจริง กล่าวคือ ประเภทต้องเป็น DONE หรือ ABORTED และต้องระบุสาเหตุในกรณีที่เป็น ABORTED (ดูรายละเอียดได้ที่ JobState ) นอกจากนี้ โปรดทราบว่าการใช้ อินเทอร์เฟซ /cloudprint/submit เพื่อรายงานงานพิมพ์ในเครื่องไม่ได้ระบุไว้ใน ข้อกำหนดเนื่องจากส่วนดังกล่าวมีไว้เพื่ออธิบาย การใช้งานหลักของอินเทอร์เฟซ ซึ่งก็คือการส่งงานพิมพ์พร้อมเอกสารที่จะพิมพ์ที่ระบุไว้ใน พารามิเตอร์ "content"

5.2.1. อินพุต

API /privet/printer/submitdoc มีพารามิเตอร์อินพุตต่อไปนี้

ชื่อ	ค่า
job_id	(ไม่บังคับ) รหัสงานพิมพ์ อาจละเว้นได้ในกรณีการพิมพ์อย่างง่าย (ดูด้านบน) ต้องตรงกับหมายเลขที่เครื่องพิมพ์ส่งคืน
user_name	(ไม่บังคับ) ชื่อผู้ใช้ที่ผู้ใช้อ่านได้ ค่านี้ไม่แน่นอนและควรใช้ เฉพาะสำหรับการอธิบายประกอบงานพิมพ์เท่านั้น หากมีการโพสต์งานไปยังบริการ Cloud Print อีกครั้ง ควรแนบสตริงนี้ไปกับงาน Cloud Print
client_name	(ไม่บังคับ) ชื่อของแอปพลิเคชันไคลเอ็นต์ที่ส่งคำขอนี้ สำหรับการแสดงผลเท่านั้น หากมีการโพสต์งานไปยังบริการ Cloud Print อีกครั้ง ควรแนบสตริงนี้ ไปกับงาน Cloud Print
job_name	(ไม่บังคับ) ชื่อของงานพิมพ์ที่จะบันทึก หากมีการโพสต์งานอีกครั้งไปยัง บริการ Cloud Print ควรแนบสตริงนี้ไปกับงาน Cloud Print
ออฟไลน์	(ไม่บังคับ) ต้องเป็น "offline=1" เท่านั้น ในกรณีนี้ เครื่องพิมพ์ควร ลองพิมพ์แบบออฟไลน์เท่านั้น (ไม่ต้องโพสต์ไปยังเซิร์ฟเวอร์ Cloud Print อีก)

เนื้อหาของคำขอควรมีเอกสารที่ถูกต้องสำหรับการพิมพ์ "Content-Length" ควร มีความยาวที่ถูกต้องของคำขอ ควรตั้งค่าส่วนหัว "Content-Type" เป็น ประเภท MIME ของเอกสารและตรงกับประเภทใดประเภทหนึ่งใน CDD (เว้นแต่ CDD จะระบุ "*/*")

เราขอแนะนำให้ลูกค้าอย่างยิ่งระบุชื่อผู้ใช้ (หรืออีเมล) ชื่อลูกค้า และชื่องานที่ถูกต้องพร้อมกับคำขอนี้ ฟิลด์เหล่านั้นจะใช้ใน UI เพื่อปรับปรุงประสบการณ์ของผู้ใช้เท่านั้น

5.2.2. รีเทิร์น

API /privet/printer/submitdoc จะแสดงข้อมูลต่อไปนี้

ชื่อค่า	ประเภทค่า	คำอธิบาย
job_id	สตริง	รหัสของงานพิมพ์ที่สร้างขึ้นใหม่ (การพิมพ์อย่างง่าย) หรือ job_id ที่ระบุในคำขอ (การพิมพ์ขั้นสูง)
expires_in	int	จำนวนวินาทีที่งานพิมพ์นี้ใช้ได้
job_type	สตริง	ประเภทเนื้อหาของเอกสารที่ส่ง
job_size	int 64 บิต	ขนาดของข้อมูลการพิมพ์ในหน่วยไบต์
job_name	สตริง	(ไม่บังคับ) ชื่องานเดียวกันกับในอินพุต (หากมี)

ตัวอย่าง

{
        "job_id": "123",
        "expires_in": 500,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document"
}

5.2.3. ข้อผิดพลาด

API /privet/printer/submitdoc อาจแสดงข้อผิดพลาดต่อไปนี้ (ดูรายละเอียดในส่วนข้อผิดพลาด)

ข้อผิดพลาด	คำอธิบาย
invalid_print_job	มีการระบุรหัสงานที่ไม่ถูกต้อง/หมดอายุในคำขอ ลองอีกครั้งหลังจาก หมดเวลา
invalid_document_type	เครื่องพิมพ์ไม่รองรับประเภท MIME ของเอกสาร
invalid_document	เอกสารที่ส่งไม่ถูกต้อง
document_too_large	เอกสารมีขนาดเกินขนาดสูงสุดที่อนุญาต
printer_busy	เครื่องพิมพ์ไม่ว่างและประมวลผลเอกสารไม่ได้ในขณะนี้ ลองอีกครั้ง หลังจากหมดเวลา
printer_error	เครื่องพิมพ์อยู่ในสถานะข้อผิดพลาดและต้องมีการโต้ตอบจากผู้ใช้เพื่อแก้ไข คำอธิบายควรมีคำอธิบายโดยละเอียดเพิ่มเติม (เช่น "กระดาษติดในถาด 1")
invalid_params	ระบุพารามิเตอร์ที่ไม่ถูกต้องในคำขอ (ระบบควรไม่สนใจพารามิเตอร์ที่ไม่รู้จัก เพื่อความเข้ากันได้ในอนาคต)
user_cancel	ผู้ใช้ยกเลิกกระบวนการพิมพ์จากอุปกรณ์โดยตรง
server_error	โพสต์เอกสารไปยัง Cloud Print ไม่สำเร็จ
invalid_x_privet_token	X-Privet-Token ไม่ถูกต้องหรือว่างเปล่าในคำขอ

หากอุปกรณ์ไม่ได้แสดง /privet/printer/submitdoc อุปกรณ์จะต้องแสดงข้อผิดพลาด HTTP 404 หากไม่มีส่วนหัว X-Privet-Token อุปกรณ์ต้องแสดงข้อผิดพลาด HTTP 400

หมายเหตุ: API /privet/printer/submitdoc อาจต้องมีการจัดการพิเศษในฝั่งเครื่องพิมพ์ (เนื่องจากมีเพย์โหลดขนาดใหญ่แนบมา) ในบางกรณี (ขึ้นอยู่กับการติดตั้งใช้งานเซิร์ฟเวอร์ HTTP ของเครื่องพิมพ์ และแพลตฟอร์ม) เครื่องพิมพ์อาจปิดซ็อกเก็ตก่อนที่จะแสดงข้อผิดพลาด HTTP ในกรณีอื่นๆ เครื่องพิมพ์อาจแสดงข้อผิดพลาด 503 (แทนที่จะเป็นข้อผิดพลาด Privet) เครื่องพิมพ์ควรพยายามส่งคืน Privet ให้ได้มากที่สุด อย่างไรก็ตาม ไคลเอ็นต์ทุกรายที่ใช้ข้อกำหนด Privet ควรจัดการ การปิดซ็อกเก็ต (ไม่มีข้อผิดพลาด HTTP) และกรณีข้อผิดพลาด HTTP 503 สำหรับ API /privet/printer/submitdoc ได้ ในกรณีนี้ ไคลเอ็นต์ควรจัดการเป็นข้อผิดพลาด "printer_busy" แบบส่วนตัวโดยตั้งค่า "timeout" เป็น 15 วินาที ไคลเอ็นต์อาจหยุดลองอีกครั้งหลังจากพยายามแล้วหลายครั้ง (เช่น 3 ครั้ง) เพื่อหลีกเลี่ยงการลองอีกครั้งอย่างไม่สิ้นสุด

5.3 /privet/printer/jobstate API

/privet/printer/jobstate API เป็น API ที่ไม่บังคับ (ดูการพิมพ์อย่างง่ายด้านบน) เป็นคำขอ HTTP GET API /privet/printer/jobstate ต้องตรวจสอบส่วนหัว "X-Privet-Token" ที่ถูกต้อง อุปกรณ์ ต้องใช้ API นี้ใน URL "/privet/printer/jobstate"

GET /privet/printer/jobstate HTTP/1.1

เมื่อได้รับการเรียก API /privet/printer/jobstate เครื่องพิมพ์ควรแสดงสถานะของ งานพิมพ์ที่ขอหรือข้อผิดพลาด invalid_print_job

5.3.1. อินพุต

API /privet/printer/jobstate มีพารามิเตอร์อินพุตต่อไปนี้

ชื่อ	ค่า
job_id	รหัสงานพิมพ์เพื่อแสดงสถานะ

5.3.2. รีเทิร์น

API /privet/printer/jobstate จะแสดงข้อมูลต่อไปนี้

ชื่อค่า	ประเภทค่า	คำอธิบาย
job_id	สตริง	รหัสงานพิมพ์ที่มีข้อมูลสถานะ
รัฐ	สตริง	ฉบับร่าง - สร้างงานพิมพ์ในอุปกรณ์แล้ว (ยังไม่ได้รับ การเรียกใช้ /privet/printer/submitdoc) อยู่ในคิว - ระบบได้รับงานพิมพ์และจัดคิวแล้ว แต่ยังไม่ได้เริ่มพิมพ์ in_progress - งานพิมพ์อยู่ระหว่างการพิมพ์ หยุด - งานพิมพ์หยุดชั่วคราว แต่สามารถเริ่มต้นใหม่ได้ด้วยตนเองหรือโดยอัตโนมัติ done - งานพิมพ์เสร็จแล้ว ยกเลิก - งานพิมพ์ไม่สำเร็จ
คำอธิบาย	สตริง	(ไม่บังคับ) คำอธิบายที่มนุษย์อ่านได้ของสถานะ งานพิมพ์ ควรระบุข้อมูลเพิ่มเติมหากสถานะเป็นหยุดหรือยกเลิก โดยปกติแล้วฟิลด์ semantic_state จะให้คำอธิบายที่ดีและมีความหมายมากกว่าแก่ไคลเอ็นต์
expires_in	int	จำนวนวินาทีที่งานพิมพ์นี้ใช้ได้
job_type	สตริง	(ไม่บังคับ) ประเภทเนื้อหาของเอกสารที่ส่ง
job_size	int 64 บิต	(ไม่บังคับ) ขนาดของข้อมูลการพิมพ์ในหน่วยไบต์
job_name	สตริง	(ไม่บังคับ) ชื่องานเดียวกันกับในอินพุต (หากมี)
server_job_id	สตริง	(ไม่บังคับ) รหัสของงานที่เซิร์ฟเวอร์ส่งคืน (หากมีการโพสต์งานไปยังบริการ Cloud Print) ละเว้นสำหรับการพิมพ์ออฟไลน์
semantic_state	JSON	(ไม่บังคับ) สถานะเชิงความหมายของงานในรูปแบบ PrintJobState

ตัวอย่าง (การพิมพ์โดยการรายงานผ่าน Cloud Print)

{
        "job_id": "123",
        "state": "in_progress",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document",
        "server_job_id": "1111-2222-3333-4444"
}

ตัวอย่าง (ข้อผิดพลาดในการพิมพ์ออฟไลน์)

{
        "job_id": "123",
        "state": "stopped",
        "description": "Out of paper",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document"
}

ตัวอย่าง (ผู้ใช้ยกเลิกงานพิมพ์)

{
        "job_id": "123",
        "state": "aborted",
        "description": "User action",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document",
        "semantic_state": {
                "version": "1.0",
                "state": {
                        "type": "ABORTED",
                        "user_action_cause": {"action_code": "CANCELLED"}
                },
                "pages_printed": 7
        }
}

ตัวอย่าง (หยุดงานพิมพ์เนื่องจากกระดาษหมด) สังเกตการอ้างอิงถึงสถานะของอุปกรณ์ ไคลเอ็นต์จะต้องเรียกใช้ API /privet/info เพื่อดูรายละเอียดเพิ่มเติมเกี่ยวกับสถานะอุปกรณ์

{
        "job_id": "123",
        "state": "stopped",
        "description": "Out of paper",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": "123456",
        "job_name": "My PDF document",
        "semantic_state": {
                "version": "1.0",
                "state": {
                        "type": "STOPPED",
                        "device_state_cause": {"error_code": "INPUT_TRAY"}
                },
                "pages_printed": 7
        }
}

5.3.3. ข้อผิดพลาด

API /privet/printer/jobstate อาจแสดงข้อผิดพลาดต่อไปนี้ (ดูรายละเอียดในส่วนข้อผิดพลาด)

ข้อผิดพลาด	คำอธิบาย
invalid_print_job	ระบุรหัสงานที่ไม่ถูกต้อง/หมดอายุในคำขอ
server_error	รับสถานะงานพิมพ์ (สำหรับงานพิมพ์ที่โพสต์ไปยัง Cloud Print) ไม่สำเร็จ
invalid_x_privet_token	X-Privet-Token ไม่ถูกต้องหรือว่างเปล่าในคำขอ

หากอุปกรณ์ไม่แสดง /privet/printer/jobstate อุปกรณ์จะต้องแสดงข้อผิดพลาด HTTP 404 หากไม่มีส่วนหัว X-Privet-Token อุปกรณ์ต้องแสดงข้อผิดพลาด HTTP 400

6. ภาคผนวก

6.1 ลักษณะการทำงานและการตั้งค่าเริ่มต้น

ส่วนนี้จะอธิบายลักษณะการทำงานเริ่มต้นที่เราคาดหวังจากอุปกรณ์ที่รองรับ Privet ทั้งหมด

อุปกรณ์ที่พร้อมใช้งานควรรองรับเฉพาะ API /privet/info และ /privet/register ควรปิดใช้ API อื่นๆ ทั้งหมด (เช่น /privet/accesstoken, การพิมพ์ในเครื่อง)
การลงทะเบียนต้องมีการโต้ตอบทางกายภาพกับอุปกรณ์

ผู้ใช้ต้องดำเนินการทางกายภาพบนอุปกรณ์ (เช่น กดปุ่ม) เพื่อยืนยันสิทธิ์เข้าถึงอุปกรณ์ ของตน
หลังจากที่ผู้ใช้ดำเนินการตามที่ระบุไว้ข้างต้น เครื่องพิมพ์ควรส่งคำขอ /cloudprint/register โดยไม่ควรส่งคำขอนี้จนกว่าจะมีการดำเนินการ (ดูแผนภาพลำดับที่ 1)
หากอุปกรณ์กำลังประมวลผลคำขอ /privet/register (เช่น รอการดำเนินการ ข้างต้น) อุปกรณ์ต้องปฏิเสธคำขอ /privet/register อื่นๆ ทั้งหมด ในกรณีนี้ อุปกรณ์ต้องแสดงข้อผิดพลาด device_busy
อุปกรณ์ควรกำหนดระยะหมดเวลาสำหรับคำขอ /register ที่ไม่ได้รับการดำเนินการทางกายภาพ ที่กล่าวถึงข้างต้นภายใน 60 วินาที อุปกรณ์ต้องแสดงข้อผิดพลาด confirmation_timeout ในกรณีนี้
ไม่บังคับ: รายการต่อไปนี้อาจช่วยปรับปรุงประสบการณ์ของผู้ใช้ได้ แต่ไม่จำเป็นต้องระบุ

เครื่องพิมพ์อาจกะพริบไฟหรือหน้าจอเพื่อระบุว่าผู้ใช้ต้องดำเนินการเพื่อยืนยันการลงทะเบียน
เครื่องพิมพ์อาจแสดงข้อความบนหน้าจอว่า "ระบบกำลังลงทะเบียนกับ Google Cloud Print สำหรับผู้ใช้ "abc@def.com" - กด OK เพื่อ ดำเนินการต่อ" โดย abc@def.com คือพารามิเตอร์ผู้ใช้จาก การเรียก API /register ซึ่งจะช่วยให้ผู้ใช้ทราบอย่างชัดเจนว่า

เป็นการยืนยันคำขอลงทะเบียน
จะเกิดอะไรขึ้นหากผู้ใช้ไม่ได้เป็นผู้ทริกเกอร์คำขอ

นอกจากการดำเนินการทางกายภาพเพื่อยืนยันจากเครื่องพิมพ์ (เช่น ปุ่ม"ตกลง" ) เครื่องพิมพ์อาจมีปุ่มให้ผู้ใช้ยกเลิกคำขอด้วย (เช่น "กด "ยกเลิก" เพื่อปฏิเสธ") ซึ่งจะช่วยให้ผู้ใช้ที่ไม่ได้ทริกเกอร์คำขอลงทะเบียนสามารถยกเลิกคำขอดังกล่าวก่อนที่ระบบจะหมดเวลา 60 วินาที อุปกรณ์ต้องแสดงข้อผิดพลาด user_cancel ในกรณีนี้

การโอนการเป็นเจ้าของ

อุปกรณ์อาจถูกลบออกจากบริการระบบคลาวด์อย่างชัดเจน

หากอุปกรณ์ได้รับผลสำเร็จ แต่ไม่มีคำอธิบายอุปกรณ์อันเป็นผลมาจากการเรียกใช้ /cloudprint/printer (สำหรับ GCP) อุปกรณ์จะต้องกลับไปใช้โหมดเริ่มต้น (พร้อมใช้งานทันที)
หากข้อมูลเข้าสู่ระบบของอุปกรณ์ใช้ไม่ได้อีกต่อไป (เนื่องจากการตอบกลับจากเซิร์ฟเวอร์ระบุว่า "ข้อมูลเข้าสู่ระบบไม่ถูกต้อง") อุปกรณ์จะต้องกลับไปใช้โหมดเริ่มต้น (พร้อมใช้งานทันที)

การรีเซ็ตเป็นค่าเริ่มต้นในเครื่องต้องล้างข้อมูลเข้าสู่ระบบของอุปกรณ์และตั้งค่าเป็นสถานะเริ่มต้น
ไม่บังคับ: อุปกรณ์อาจมีรายการเมนูเพื่อล้างข้อมูลเข้าสู่ระบบและตั้งค่าเป็นโหมดเริ่มต้น

อุปกรณ์ที่รองรับการแจ้งเตือน XMPP ต้องมีความสามารถในการ Ping เซิร์ฟเวอร์ เซิร์ฟเวอร์ต้องควบคุมการหมดเวลาของ Ping ได้ผ่าน "local_settings"
อุปกรณ์อาจปิงเซิร์ฟเวอร์อย่างชัดเจน (/cloudprint/printer API สำหรับ GCP นอกเหนือจาก ปิง XMPP) ไม่เกินวันละครั้ง (24 ชั่วโมง) เพื่อให้แน่ใจว่าอุปกรณ์ซิงค์กัน เราขอแนะนำให้สุ่มกรอบเวลาการตรวจสอบภายในกรอบเวลา 24-32 ชั่วโมง
ไม่บังคับ: สำหรับอุปกรณ์ Cloud Print เราขอแนะนำให้มีวิธีด้วยตนเอง (ปุ่ม) เพื่อให้ผู้ใช้เริ่มตรวจสอบงานพิมพ์ใหม่จากอุปกรณ์ได้ เครื่องพิมพ์บางรุ่น มีฟีเจอร์นี้อยู่แล้ว
ไม่บังคับ เครื่องพิมพ์ระดับองค์กรอาจมีตัวเลือกในการปิดใช้การค้นหาในพื้นที่โดยสมบูรณ์ ใน กรณีดังกล่าว อุปกรณ์ต้องอัปเดตการตั้งค่าในเครื่องเหล่านี้บนเซิร์ฟเวอร์ การตั้งค่าใหม่ในเครื่องต้อง ว่างเปล่า (การตั้งค่า "local_discovery" เป็น "false" หมายความว่า เปิดใช้ซ้ำจากบริการ GCP ได้)

6.1.2 แผนภาพการลงทะเบียนเริ่มต้น

6.2 การโจมตีและการป้องกัน XSSI และ XSRF

ส่วนนี้จะอธิบายความเป็นไปได้ของการโจมตีแบบ XSSI และ XSRF ในอุปกรณ์ รวมถึงวิธีป้องกัน การโจมตีดังกล่าว (รวมถึงเทคนิคการสร้างโทเค็น)
ดูรายละเอียดเพิ่มเติมได้ที่ http://googleonlinesecurity.blogspot.com/2011/05/website-security-for-webmasters.html
โดยปกติแล้ว การโจมตี XSSI และ XSRF จะเกิดขึ้นได้เมื่อเว็บไซต์ใช้กลไกการตรวจสอบสิทธิ์ด้วยคุกกี้ แม้ว่า Google จะไม่ได้ใช้คุกกี้กับบริการ Cloud Print แต่การโจมตีดังกล่าวก็ยังคงเป็นไปได้ การเข้าถึงเครือข่ายภายในเชื่อถือคำขอโดยปริยายตามการออกแบบ

6.2.1. XSSI

เว็บไซต์ที่เป็นอันตรายอาจคาดเดาที่อยู่ IP และหมายเลขพอร์ตของอุปกรณ์ที่เข้ากันได้กับ Privet และพยายามเรียกใช้ Privet API โดยใช้ "src=<ชื่อ API>" ภายในแท็ก <script>

<script type="text/javascript" src="http://192.168.1.42:8080/privet/info"></script>

หากไม่มีการป้องกัน เว็บไซต์ที่เป็นอันตรายจะเรียกใช้ API และเข้าถึงผลลัพธ์ได้
เพื่อป้องกันการโจมตีประเภทนี้ การเรียกใช้ Privet API ทั้งหมดต้องมีส่วนหัว "X-Privet-Token" ในคำขอ แท็กสคริปต์ "src=<api>" จะ เพิ่มส่วนหัวไม่ได้ ซึ่งเป็นการป้องกันการโจมตีประเภทนี้อย่างมีประสิทธิภาพ

6.2.2. XSRF

http://en.wikipedia.org/wiki/Cross-site_request_forgery
เว็บไซต์ที่เป็นอันตรายอาจคาดเดาที่อยู่ IP และหมายเลขพอร์ตของอุปกรณ์ที่เข้ากันได้กับ Privet และพยายามเรียกใช้ Privet API โดยใช้ <iframe>, แบบฟอร์ม หรือกลไกการโหลดข้ามเว็บไซต์อื่นๆ ผู้โจมตีจะเข้าถึงผลลัพธ์ของคำขอไม่ได้ แต่หากคำขอจะดำเนินการ (เช่น การพิมพ์) ผู้โจมตีก็สามารถทริกเกอร์ได้

เราจึงกำหนดให้มีการป้องกันต่อไปนี้เพื่อป้องกันการโจมตีนี้

ปล่อยให้ /privet/info API เปิดต่อ XSRF
API /privet/info ต้องไม่ดำเนินการใดๆ ในอุปกรณ์
ใช้ /privet/info API เพื่อรับ x-privet-token
API อื่นๆ ทั้งหมดต้องตรวจสอบโทเค็น x-privet ที่ถูกต้องในส่วนหัว "X-Privet-Token"
x-privet-token ควรใช้งานได้เพียง 24 ชั่วโมงเท่านั้น

แม้ว่าผู้โจมตีจะสามารถเรียกใช้ API /privet/info ได้ แต่ก็จะไม่สามารถ อ่าน x-privet-token จากการตอบกลับได้ จึงไม่สามารถเรียกใช้ API อื่นๆ ได้

ขอแนะนำอย่างยิ่งให้สร้างโทเค็น XSRF โดยใช้อัลกอริทึมต่อไปนี้

XSRF_token = base64( SHA1(device_secret + DELIMITER + issue_timecounter) + DELIMITER + issue_timecounter )

องค์ประกอบการสร้างโทเค็น XSRF

DELIMITER เป็นอักขระพิเศษ โดยปกติคือ ":"
issue_timecounter คือจำนวนวินาทีนับตั้งแต่เหตุการณ์หนึ่งๆ (Epoch สำหรับการประทับเวลา) หรือ เวลาเปิดเครื่องของอุปกรณ์ (สำหรับตัวนับ CPU) issue_timecounter จะเพิ่มขึ้นเรื่อยๆ เมื่อ อุปกรณ์ทำงานอยู่ (ดูการยืนยันโทเค็นด้านล่าง)
SHA1 - ฟังก์ชันแฮชที่ใช้อัลกอริทึม SHA1
base64 - การเข้ารหัส base64
device_secret - ข้อมูลลับเฉพาะของอุปกรณ์ ต้องอัปเดตข้อมูลลับของอุปกรณ์ทุกครั้งที่ รีสตาร์ท

วิธีที่แนะนำในการสร้างข้อมูลลับของอุปกรณ์

สร้าง UUID ใหม่ทุกครั้งที่รีสตาร์ท
สร้างหมายเลขสุ่ม 64 บิตทุกครั้งที่รีสตาร์ท

อุปกรณ์ไม่จำเป็นต้องจัดเก็บโทเค็น XSRF ทั้งหมดที่ออก เมื่ออุปกรณ์ต้อง ยืนยันโทเค็น XSRF เพื่อตรวจสอบความถูกต้อง อุปกรณ์ควรถอดรหัสโทเค็นแบบ Base64 รับ issue_timecounter จากครึ่งหลัง (ข้อความธรรมดา) แล้วลองสร้างแฮช SHA1 ของ device_secret + DELIMITER + issue_timecounter โดยที่ issue_timecounter มาจากโทเค็น หาก SHA1 ที่สร้างขึ้นใหม่ตรงกับ SHA1 ในโทเค็น อุปกรณ์จะต้องตรวจสอบว่า issue_timecounter อยู่ภายในระยะเวลาที่ถูกต้องจาก (24 ชั่วโมง) ของตัวนับเวลาปัจจุบันหรือไม่ โดยอุปกรณ์จะใช้ตัวนับเวลาปัจจุบัน (เช่น ตัวนับ CPU) และลบ issue_timecounter ออกจากตัวนับนั้น ผลลัพธ์ต้องเป็นจำนวนวินาทีตั้งแต่มีการออกโทเค็น

สำคัญ: วิธีนี้เป็นวิธีที่แนะนำในการใช้การป้องกัน XSRF ไคลเอ็นต์ของข้อกำหนด Privet จะไม่พยายามทำความเข้าใจโทเค็น XSRF แต่จะถือว่าเป็นกล่องดำแทน รูปที่ 6.2.3 แสดงวิธีที่แนะนำในการใช้ X-Privet-Token และการยืนยันคำขอทั่วไป

6.2.3 แผนภาพลำดับการสร้างและการยืนยันโทเค็น X-Privet

6.3 ไดอะแกรมเวิร์กโฟลว์

ส่วนนี้จะแสดงเวิร์กโฟลว์ในกรณีต่างๆ

6.3.1. เวิร์กโฟลว์ของเครื่องพิมพ์ที่พร้อมใช้งานทันที

6.3.2. การเริ่มต้นใช้งานเครื่องพิมพ์ที่ลงทะเบียน

6.3.3 เวิร์กโฟลว์การจัดการการแจ้งเตือน XMPP

6.3.4. ขั้นตอนการตรวจสอบการตั้งค่าเครื่องพิมพ์

พริเวต จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ

1. บทนำ

2. Discovery

2.1 ประเภทบริการ

2.2 ระเบียน TXT

2.2.1. txtvers

2.2.2. ty

2.2.3. note (ไม่บังคับ)

2.2.4. url

2.2.5. ประเภท

2.2.6. id

2.2.7. cs

3. ประกาศ

3.1 สตาร์ทอัพ

3.2 ปิดการทำงาน

3.3. อัปเดต

4. API

4.1 ความพร้อมใช้งานของ API

4.1.1. การลงทะเบียน

4.1.2. สตาร์ทอัพ

4.1.3. อัปเดต

4.1.3.1. การตั้งค่าในเครื่องที่รอดำเนินการ

4.1.3.2. การตั้งค่าในพื้นที่ปัจจุบัน

4.1.4. ออฟไลน์

4.1.5. การลบอุปกรณ์ออกจากบริการ

4.2 /privet/info API

4.2.1. อินพุต

4.2.2. รีเทิร์น

4.2.3. ข้อผิดพลาด

4.3 /privet/register API

4.3.1. อินพุต

4.3.2. รีเทิร์น

4.3.3. ข้อผิดพลาด

4.4 /privet/accesstoken API

4.4.1. อินพุต

4.4.2. รีเทิร์น

4.4.3. ข้อผิดพลาด

4.5 /privet/capabilities API

4.5.1. อินพุต

4.5.2. รีเทิร์น

4.5.3. ข้อผิดพลาด

4.6 ข้อผิดพลาด

5. Printer API

5.1 /privet/printer/createjob API

5.1.1. อินพุต

5.1.2. รีเทิร์น

5.1.3. ข้อผิดพลาด

5.2 /privet/printer/submitdoc API

5.2.1. อินพุต

5.2.2. รีเทิร์น

5.2.3. ข้อผิดพลาด

5.3 /privet/printer/jobstate API

5.3.1. อินพุต

5.3.2. รีเทิร์น

5.3.3. ข้อผิดพลาด

6. ภาคผนวก

6.1 ลักษณะการทำงานและการตั้งค่าเริ่มต้น

6.1.2 แผนภาพการลงทะเบียนเริ่มต้น

6.2 การโจมตีและการป้องกัน XSSI และ XSRF

6.2.1. XSSI

6.2.2. XSRF

6.2.3 แผนภาพลำดับการสร้างและการยืนยันโทเค็น X-Privet

6.3 ไดอะแกรมเวิร์กโฟลว์

6.3.1. เวิร์กโฟลว์ของเครื่องพิมพ์ที่พร้อมใช้งานทันที

6.3.2. การเริ่มต้นใช้งานเครื่องพิมพ์ที่ลงทะเบียน

6.3.3 เวิร์กโฟลว์การจัดการการแจ้งเตือน XMPP

6.3.4. ขั้นตอนการตรวจสอบการตั้งค่าเครื่องพิมพ์

พริเวต