Privet คือ API การค้นหาภายในอุปกรณ์ระบบคลาวด์ที่ใช้โดยบริการระบบคลาวด์ เอกสารนี้จะจัดระเบียบเป็นส่วนดังต่อไปนี้
- บทนํา: ข้อมูลเบื้องต้นเกี่ยวกับ Privet
- การค้นพบ: กลไกการค้นหาในท้องถิ่น
- ประกาศ: ประกาศการค้นหาในท้องถิ่น
- API: API ของ Privet สําหรับอุปกรณ์ระบบคลาวด์ทั่วไป
- Printer API: Privet API ที่เครื่องพิมพ์ใช้
- ภาคผนวก: แผนภาพเสริม
1. บทนำ
อุปกรณ์ที่เชื่อมต่อกับระบบคลาวด์มีข้อดีมากมาย ผู้ดูแลระบบสามารถใช้บริการ Conversion ออนไลน์ จัดคิวงานในขณะที่อุปกรณ์ออฟไลน์ และสามารถเข้าถึงได้จากทุกหนแห่งในโลก อย่างไรก็ตาม เนื่องจากอุปกรณ์ระบบคลาวด์ชนิดต่างๆ หลายชนิดที่ผู้ใช้คนหนึ่งเข้าถึงได้ เราต้องแสดงวิธีการค้นหาอุปกรณ์ที่ใกล้ที่สุดโดยอิงตามตําแหน่ง วัตถุประสงค์ของโปรโตคอล Privet คือการเชื่อมโยงความยืดหยุ่นของอุปกรณ์ระบบคลาวด์กับกลไกการสํารวจในเครื่องที่เหมาะสม เพื่อให้ผู้ใช้ค้นพบอุปกรณ์ได้ง่ายในสภาพแวดล้อมใหม่
เป้าหมายของโปรโตคอลนี้คือ- ทําให้ค้นพบอุปกรณ์ในระบบคลาวด์ได้
- ลงทะเบียนอุปกรณ์ระบบคลาวด์ด้วยบริการระบบคลาวด์
- เชื่อมโยงอุปกรณ์ที่ลงทะเบียนไว้กับตัวแทนในระบบคลาวด์
- เปิดใช้ฟังก์ชันการทํางานแบบออฟไลน์
- ติดตั้งใช้งานได้ง่ายขึ้นเพื่อให้อุปกรณ์ขนาดเล็กใช้ได้
โปรโตคอล Privet ประกอบด้วย 2 ส่วนหลักๆ ได้แก่ Discovery และ API ระบบจะใช้การค้นพบเพื่อค้นหาอุปกรณ์ในเครือข่ายภายใน และจะใช้ API เพื่อรับข้อมูลเกี่ยวกับอุปกรณ์และดําเนินการบางอย่าง ในเอกสารนี้ อุปกรณ์หมายถึงอุปกรณ์ที่เชื่อมต่อกับระบบคลาวด์ซึ่งใช้โปรโตคอล Privet
2. การค้นพบ
Discovery เป็นโปรโตคอลที่อิงตาม 0conf (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 Service Discovery ใช้รูปแบบต่อไปนี้สําหรับประเภทบริการ: _applicationprotocol._transportprotocol ในกรณีของโปรโตคอล Privet ประเภทบริการสําหรับ DNS-SD ควรเป็น _privet._tcp
อุปกรณ์ยังใช้บริการอื่นๆ ได้เช่นกัน ขอแนะนําให้ใช้ชื่ออินสแตนซ์บริการเดียวกันสําหรับบริการทุกประเภทที่ใช้งานโดยอุปกรณ์ เช่น เครื่องพิมพ์อาจใช้งาน "เครื่องพิมพ์ XYZ._privet._tcp" และ "เครื่องพิมพ์ XYZ._printer._tcp" ซึ่งจะทําให้ผู้ใช้ตั้งค่าได้ง่ายขึ้น แต่ไคลเอ็นต์ Privet จะมองหาเฉพาะ "_privet._tcp"
นอกเหนือจากประเภทบริการหลักแล้ว อุปกรณ์ต้องโฆษณาระเบียน PTR สําหรับประเภทย่อยที่เกี่ยวข้อง (ดูข้อมูลจําเพาะของ DNS-SD: "7.1 การแจกแจงอินสแตนซ์ที่เลือก (ประเภทย่อย)") รูปแบบควรมีลักษณะดังนี้ _<subtype>._sub._privet._tcp
ปัจจุบันประเภทย่อยของอุปกรณ์ที่รองรับมีเพียงเครื่องพิมพ์เท่านั้น เครื่องพิมพ์ทั้งหมดจึงต้องโฆษณาระเบียน PTR จํานวน 2 รายการต่อไปนี้
- _privet._tcp.local
- _printer._sub._privet._tcp.local
2.2. ระเบียน TXT
DNS Service Discovery กําหนดช่องสําหรับใส่ข้อมูลเสริมเกี่ยวกับบริการในระเบียน TXT ระเบียน TXT ประกอบด้วยคู่คีย์-ค่า คู่คีย์/ค่าแต่ละคู่เริ่มต้นจากไบต์ความยาวแล้วตามด้วยข้อความสูงสุด 255 ไบต์ คีย์คือข้อความก่อนอักขระ "=" แรก และค่าคือข้อความหลังจากอักขระ "=" แรกจนถึงจุดสิ้นสุด ข้อกําหนดช่วยให้ไม่มีค่าในระเบียน ซึ่งในกรณีนี้จะไม่มีการใช้อักขระ "=" หรือไม่ใส่ข้อความหลังอักขระ "=" (ดูข้อมูลจําเพาะของ DNS-SD: "6.1 กฎรูปแบบทั่วไปสําหรับระเบียน TXT ของ DNS" สําหรับรูปแบบระเบียน DNS รูปแบบ TXT และ "6.2 ขนาดระเบียน TXT ของ DNS-SD และเครื่องหมายคําพูดสําหรับความยาวที่แนะนํา)
Privet กําหนดให้อุปกรณ์ส่งคู่คีย์/ค่าต่อไปนี้ในระเบียน TXT สตริงคีย์/ค่าจะไม่คํานึงถึงตัวพิมพ์เล็กหรือใหญ่ ตัวอย่างเช่น "CS=online" และ "cs=online" เหมือนกัน ข้อมูลในระเบียน TXT ต้องเหมือนกับที่เข้าถึงได้ผ่านทาง /info API (ดู 4.1 API)
ขอแนะนําให้รักษาขนาดของระเบียน TXT ไว้ต่ํากว่า 512 ไบต์
2.2.1. txt
เวอร์ชันของโครงสร้าง TXT txt ต้องเป็นระเบียนแรกของโครงสร้าง TXT ปัจจุบันมีเวอร์ชันที่รองรับเพียง 1 รายการเท่านั้น
txtvers=1
2.2.2.
ระบุชื่ออุปกรณ์ที่ผู้ใช้อ่านได้ เช่น
ty=Google Cloud Ready Printer Model XYZ
2.2.3 หมายเหตุ (ไม่บังคับ)
ระบุชื่ออุปกรณ์ที่ผู้ใช้อ่านได้ เช่น
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=11111111-2222-3333-4444-555555555555 id=
2.2.7. cs
ระบุสถานะการเชื่อมต่อปัจจุบันของอุปกรณ์ ค่าที่เป็นไปได้มี 4 ค่าที่กําหนดไว้ในข้อกําหนดนี้
- "online" บ่งชี้ว่าขณะนี้อุปกรณ์กําลังเชื่อมต่อกับระบบคลาวด์
- "ออฟไลน์" บ่งชี้ว่าอุปกรณ์ดังกล่าวพร้อมใช้งานบนเครือข่าย LAN แต่สื่อสารกับเซิร์ฟเวอร์ไม่ได้
- "การเชื่อมต่อ&การเสนอราคา; บ่งชี้ว่าอุปกรณ์กําลังทํางานตามลําดับการเริ่มต้นและยังไม่ออนไลน์อย่างสมบูรณ์
- "not-config" ระบุว่ายังไม่มีการกําหนดค่าการเข้าถึงอินเทอร์เน็ตของอุปกรณ์ ปัจจุบันระบบไม่ได้ใช้ค่านี้ แต่อาจมีประโยชน์ในข้อกําหนดเวอร์ชันในอนาคต
- cs=online
- cs=Offline
- cs=การเชื่อมต่อ
หากลงทะเบียนอุปกรณ์กับระบบคลาวด์แล้ว เมื่อเริ่มต้น ควรตรวจสอบการเชื่อมต่อกับเซิร์ฟเวอร์เพื่อตรวจหาสถานะการเชื่อมต่อ (เช่น เรียกใช้ Cloud API เพื่อรับการตั้งค่าอุปกรณ์) อุปกรณ์อาจใช้สถานะการเชื่อมต่อช่องทางการแจ้งเตือน (เช่น XMPP) เพื่อรายงานค่านี้ อุปกรณ์ที่ไม่ได้ลงทะเบียนเมื่อเริ่มต้นใช้งานอาจใช้คําสั่ง ping กับโดเมนเพื่อตรวจสอบสถานะการเชื่อมต่อ (เช่น ใช้คําสั่ง ping www.google.com สําหรับอุปกรณ์ใน Cloud Print)
3. ประกาศ
เมื่อเริ่มต้นอุปกรณ์ ปิดเครื่อง หรือเปลี่ยนสถานะ อุปกรณ์ต้องทําขั้นตอนการประกาศตามที่อธิบายไว้ในข้อกําหนดของ mDNS ซึ่งควรส่งประกาศที่เกี่ยวข้องอย่างน้อย 2 ครั้งด้วยช่วงเวลา 1 วินาทีเป็นอย่างน้อย
3.1. สตาร์ทอัพ
เมื่อเริ่มต้นอุปกรณ์ ต้องทําการตรวจสอบและประกาศขั้นตอนตามที่อธิบายไว้ในข้อกําหนดของ mDNS ในกรณีนี้ คุณควรส่งระเบียน SRV, PTR และ TXT ขอแนะนําให้จัดกลุ่มระเบียนทั้งหมดไว้ในการตอบสนอง DNS 1 รายการ หากเป็นไปได้ หากไม่มี ขอแนะนําให้เรียงลําดับต่อไปนี้เป็น SRV, PTR, ระเบียน TXT
3.2. ปิดการทำงาน
เมื่อปิดอุปกรณ์ ควรพยายามแจ้งผู้ที่สนใจทั้งหมดเกี่ยวกับเรื่องนี้โดยการส่ง "goodbye package" พร้อมด้วย 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 ดูข้อมูลเพิ่มเติมเกี่ยวกับสาเหตุที่การดําเนินการนี้เกิดขึ้นและวิธีสร้างโทเค็นได้ที่ภาคผนวก A: การโจมตี 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 } }คุณสามารถตั้งค่าต่อไปนี้ได้
ชื่อค่า | ประเภทค่า | คำอธิบาย |
---|---|---|
การค้นพบในพื้นที่ | บูลีน | ระบุว่าอนุญาตฟังก์ชันการค้นพบท้องถิ่นหรือไม่ หาก "false" จะต้องปิดใช้ API ในเครื่องทั้งหมด (รวมทั้ง /info) และการค้นพบ DNS-SD โดยค่าเริ่มต้น อุปกรณ์ที่ลงทะเบียนใหม่ควรส่ง "true" |
เปิดใช้งานการเข้าถึงโทเค็น | บูลีน (ไม่บังคับ) | ระบุว่าควรแสดง /accesstoken API ในเครือข่ายภายในหรือไม่ โดยค่าเริ่มต้นควรเป็น "true" |
เครื่องพิมพ์/local_printing_enabled | บูลีน (ไม่บังคับ) | ระบุว่าควรแสดงฟังก์ชันการพิมพ์ในเครื่อง (/printer/createjob, /printer/submitdoc, /printer/jobstate) ในเครือข่ายภายในหรือไม่ โดยค่าเริ่มต้นควรเป็น "true" |
เครื่องพิมพ์/conversion_printing_enabled | บูลีน (ไม่บังคับ) | ระบุว่าการพิมพ์ในเครื่องจะส่งงานไปยังเซิร์ฟเวอร์สําหรับ Conversion หรือไม่ คุณควรเลือกใช้ได้เมื่อเปิดใช้การพิมพ์ในเครื่องเท่านั้น |
ค่า xmpp_timeout_value | int (ไม่บังคับ) | ระบุจํานวนวินาทีระหว่างคําสั่ง ping ของช่อง XMPP โดยค่าเริ่มต้นต้องเป็น 300 (5 นาที) ขึ้นไป |
สําคัญ: ไม่มีค่าที่ไม่บังคับซึ่งแสดงให้เห็นว่าอุปกรณ์ไม่รองรับฟังก์ชันการทํางานที่เกี่ยวข้องโดยสิ้นเชิง
4.1.2 สตาร์ทอัพ
เมื่อเริ่มต้นอุปกรณ์ เซิร์ฟเวอร์ควรติดต่อเซิร์ฟเวอร์เพื่อตรวจสอบว่า API ใดที่ควรเปิดเผยในเครือข่ายภายใน สําหรับเครื่องพิมพ์ที่เชื่อมต่อกับ Cloud Print พวกเขาควรโทรหา:
/cloudprint/printer?printerid=<printer_id>หรือ
/cloudprint/list
ควรใช้ /":{"/printer มากกว่า /duration/list แต่ทั้งคู่จะทํางานได้
API นี้จะแสดงพารามิเตอร์อุปกรณ์ปัจจุบัน รวมถึงการตั้งค่าสําหรับ 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>
เมื่ออุปกรณ์เห็นส่วน "pending" อันเป็นผลจาก /duration/printer API (เมื่อเริ่มต้นใช้งานหรือเนื่องจากการแจ้งเตือน) อุปกรณ์ต้องอัปเดตสถานะภายในเพื่อจดจําการตั้งค่าใหม่ โดยระบบต้องเรียกใช้ API ของเซิร์ฟเวอร์เพื่อยืนยันการตั้งค่าใหม่ สําหรับ Cloud Printer อุปกรณ์จะต้องเรียก /duration/update API และใช้พารามิเตอร์ "local_settings" ในระหว่างการลงทะเบียน
เมื่อเชื่อมต่อกับช่อง XMPP อีกครั้ง อุปกรณ์ต้องเรียกใช้ /duration/printer API เพื่อตรวจสอบว่าการตั้งค่าในเครื่องมีการเปลี่ยนแปลงนับตั้งแต่ครั้งล่าสุดหรือไม่
4.1.3.1 การตั้งค่าในเครื่องกําลังรอดําเนินการ
"local_settings" ที่อุปกรณ์ใช้ในการเรียก API ของเซิร์ฟเวอร์จะต้องมีส่วน "pending"
4.1.3.2 การตั้งค่าปัจจุบันในเครื่อง
เฉพาะอุปกรณ์เท่านั้นที่สามารถเปลี่ยนส่วน "current" ของ "local_settings" คนอื่นๆ จะเปลี่ยนส่วน "pending" และรอจนกว่าการเปลี่ยนแปลงจะเผยแพร่ไปยังส่วน "current" ตามอุปกรณ์
4.1.4 ออฟไลน์
เมื่อไม่สามารถติดต่อเซิร์ฟเวอร์ได้ในช่วงเริ่มต้นใช้งาน อุปกรณ์จะต้องใช้การตั้งค่าในเครื่องที่ทราบครั้งล่าสุดหลังจากการแจ้งเตือน
4.1.5 กําลังลบอุปกรณ์ออกจากบริการ
หากอุปกรณ์ถูกลบออกจากบริการ (เช่น GCP) การแจ้งเตือน XMPP จะส่งไปยังอุปกรณ์ การแจ้งเตือนจะมีรูปแบบดังนี้
<device_id>/delete
เมื่อได้รับการแจ้งเตือนดังกล่าว อุปกรณ์จะต้องไปที่เซิร์ฟเวอร์เพื่อตรวจสอบสถานะ อุปกรณ์ Cloud Print ต้องใช้สิ่งต่อไปนี้
/cloudprint/printer?printerid=<printer_id>
อุปกรณ์ต้องได้รับการตอบกลับ HTTP ที่สําเร็จด้วยsuccess=false และไม่มีคําอธิบายอุปกรณ์/เครื่องพิมพ์ หมายความว่าระบบได้นําอุปกรณ์ออกจากเซิร์ฟเวอร์แล้ว และอุปกรณ์ต้องลบข้อมูลเข้าสู่ระบบและไปยังโหมดการตั้งค่าเริ่มต้น
เมื่อใดก็ตามที่อุปกรณ์ได้รับการตอบกลับว่าอุปกรณ์ถูกลบเนื่องจาก /duration/printer API (การเริ่มต้น การแจ้งเตือนการตั้งค่าการอัปเดต คําสั่ง ping ประจําวัน) อุปกรณ์จะต้องลบข้อมูลเข้าสู่ระบบและไปยังโหมดเริ่มต้น
4.2. /privet/info API
API ข้อมูลเป็นสิ่งจําเป็นและจะต้องติดตั้งใช้งานในอุปกรณ์ทุกเครื่อง เป็นคําขอ HTTP GET สําหรับ "/privet/info" url: GET /privet/info HTTP/1.1
โดย API ข้อมูลจะแสดงข้อมูลเบื้องต้นเกี่ยวกับอุปกรณ์และฟังก์ชันการทํางานที่รองรับ API นี้ต้องไม่เปลี่ยนสถานะของอุปกรณ์หรือดําเนินการใดๆ เนื่องจากเสี่ยงต่อการถูกโจมตี XSRF นี่คือ API เดียวเท่านั้นที่ได้รับอนุญาตให้ใส่ส่วนหัว "X-Privet-Token" ที่ว่างเปล่า ไคลเอ็นต์ควรเรียก /privet/info API ด้วย "X-Privet-Token" ส่วนหัวตั้งค่าเป็น X-Privet-Token: & ""
API ข้อมูลต้องส่งคืนข้อมูลที่สอดคล้องกับข้อมูลที่มีอยู่ในระเบียน TXT ระหว่างการค้นหา
4.2.1 อินพุต
/privet/info API ไม่มีพารามิเตอร์อินพุต
4.2.2 ไปกลับ
/privet/info API แสดงข้อมูลพื้นฐานเกี่ยวกับอุปกรณ์และฟังก์ชันการทํางานที่รองรับ
คอลัมน์ TXT จะระบุช่องที่เกี่ยวข้องในระเบียน TXT ของ DNS-SD
ชื่อค่า | ประเภทค่า | คำอธิบาย | TXT |
---|---|---|---|
เวอร์ชัน | สตริง | รองรับ API เวอร์ชันสูงสุด (major.minor) ปัจจุบันคือ 1.0 | |
name | สตริง | ชื่ออุปกรณ์ที่มนุษย์อ่านได้ | ไท |
คำอธิบาย | สตริง | (ไม่บังคับ) คําอธิบายอุปกรณ์ ผู้ใช้ควรทําการแก้ไขได้ | โน้ต |
url | สตริง | URL ของเซิร์ฟเวอร์ที่อุปกรณ์นี้กําลังพูดคุยด้วย URL ต้องมีข้อกําหนดโปรโตคอล เช่น https://www.google.com/duration | url |
ประเภท | รายการสตริง | รายการประเภทอุปกรณ์ที่รองรับ | ประเภท |
id | สตริง | รหัสอุปกรณ์ ว่างเปล่าหากยังไม่ได้ลงทะเบียนอุปกรณ์ | id |
สถานะอุปกรณ์ | สตริง | สถานะอุปกรณ์ ไม่มีหมายความว่าอุปกรณ์พร้อมแล้ว กําลังประมวลผลหมายความว่าอุปกรณ์ไม่ว่างและอาจใช้ได้เป็นระยะเวลาหนึ่ง หยุดทํางานหมายความว่าอุปกรณ์ไม่ทํางานและต้องให้ผู้ใช้จัดการ | |
สถานะการเชื่อมต่อ | สตริง | สถานะการเชื่อมต่อกับเซิร์ฟเวอร์ (base_url)
ออนไลน์ - การเชื่อมต่อพร้อมใช้งาน ออฟไลน์ - ไม่มีการเชื่อมต่อ การเชื่อมต่อ - กําลังเริ่มขั้นตอนการเริ่มต้น ไม่ได้กําหนดค่า - ยังไม่ได้กําหนดค่าการเชื่อมต่อ อุปกรณ์ที่ลงทะเบียนอาจรายงานสถานะการเชื่อมต่อตามสถานะของช่องทางการแจ้งเตือน (เช่น สถานะการเชื่อมต่อ XMPP) | cs |
ผู้ผลิต | สตริง | ชื่อผู้ผลิตอุปกรณ์ | |
รุ่น | สตริง | รุ่นของอุปกรณ์ | |
หมายเลขซีเรียล_หมายเลขซีเรียล | สตริง | ตัวระบุอุปกรณ์ที่ไม่ซ้ํากัน ในข้อมูลจําเพาะนี้ ต้องเป็น UUID (ข้อกําหนดของ GCP 1.1) (ไม่บังคับ) เราขอแนะนําให้ใช้รหัสหมายเลขซีเรียลเดียวกันทุกที่ เพื่อให้ลูกค้าแต่ละรายสามารถระบุอุปกรณ์เครื่องเดียวกันได้ ตัวอย่างเช่น เครื่องพิมพ์ที่ใช้ IPP อาจใช้รหัสหมายเลขซีเรียลนี้ในช่อง "printer-device-id" | |
เฟิร์มแวร์ | สตริง | เวอร์ชันเฟิร์มแวร์ของอุปกรณ์ | |
ระยะเวลาทำงาน | int | จํานวนวินาทีจากการเปิดเครื่องอุปกรณ์ | |
ตั้งค่า URL | สตริง | (ไม่บังคับ) URL (รวมถึงโปรโตคอล) ของหน้าเว็บพร้อมวิธีการตั้งค่า | |
URL การสนับสนุน | สตริง | (ไม่บังคับ) URL (รวมถึงโปรโตคอล) ของหน้าเว็บที่รองรับข้อมูลคําถามที่พบบ่อย | |
อัปเดต URL | สตริง | (ไม่บังคับ) URL (รวมถึงโปรโตคอล) ของหน้าเว็บพร้อมวิธีการอัปเดตเฟิร์มแวร์ | |
X-Pivet-Token | สตริง | ค่าของส่วนหัว X-Privet-Token ที่ต้องส่งผ่านไปยัง API ทั้งหมดเพื่อป้องกันการโจมตี XSSI และ XSRF โปรดดูรายละเอียดที่ 6.1 | |
api | คําอธิบาย API | รายการ API ที่รองรับ (คําอธิบายอยู่ด้านล่าง) | |
รัฐความหมาย | JSON | (ไม่บังคับ) สถานะเชิงความหมายของอุปกรณ์ในรูปแบบ CloudDeviceState |
api - คือรายการ JSON ที่มีรายการ API ที่ใช้ได้ผ่านเครือข่ายภายใน โปรดทราบว่าอาจมี API บางรายการเท่านั้นที่ใช้งานได้พร้อมกันในเครือข่ายภายใน เช่น อุปกรณ์ที่เชื่อมต่อใหม่ควรรองรับเฉพาะ /register api:
"api": [ "/privet/register", ]เมื่อการลงทะเบียนอุปกรณ์เสร็จสมบูรณ์ อุปกรณ์ควรหยุดรองรับ /register API อุปกรณ์ยังควรตรวจสอบร่วมกับบริการเพื่อดูว่า API ใดบ้างที่อาจเปิดเผยผ่านเครือข่ายภายใน ดังตัวอย่างต่อไปนี้
"api": [ "/privet/accesstoken", "/privet/capabilities", "/privet/printer/submitdoc", ]
ขณะนี้ API ต่อไปนี้พร้อมให้ใช้งาน
- /privet/register - API สําหรับการลงทะเบียนอุปกรณ์ผ่านเครือข่ายภายใน (ดูรายละเอียดได้ที่ /privet/register API) คุณต้องซ่อน API นี้เมื่อลงทะเบียนอุปกรณ์ใน Cloud เรียบร้อยแล้ว
- /privet/accesstoken - API สําหรับขอโทเค็นเพื่อการเข้าถึงจากอุปกรณ์ (ดูรายละเอียดที่ /privet/accesstoken API)
- /privet/capability - API สําหรับดึงความสามารถของอุปกรณ์ (ดูรายละเอียดที่ /privet/capability API)
- /privet/printer/* - API เฉพาะสําหรับประเภทอุปกรณ์ "printer" ดูรายละเอียดได้ที่ API เฉพาะสําหรับเครื่องพิมพ์
{ "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 ข้อผิดพลาด
/privet/info API ควรแสดงข้อผิดพลาดเฉพาะในกรณีที่ไม่มีส่วนหัว X-Privet-Token ต้องเป็นข้อผิดพลาด HTTP 400
HTTP/1.1 400 Missing X-Privet-Token header.
4.3. /privet/register API
/privet/register API เป็นแบบไม่บังคับ เป็นคําขอ HTTP POST /privet/register API ต้องตรวจสอบส่วนหัว X-Privet-Token ที่ถูกต้อง อุปกรณ์ต้องใช้ API นี้ที่ "/privet/register" url:
POST /privet/register?action=start&user=user@domain.com HTTP/1.1 POST /privet/register?action=complete&user=user@domain.com HTTP/1.1
อุปกรณ์ควรเปิดเผย /privet/register API เฉพาะเมื่ออนุญาตให้ลงทะเบียนโดยไม่ระบุชื่อได้ในขณะนี้ เช่น
- เมื่อเปิดอุปกรณ์ (หรือหลังจากคลิกปุ่มพิเศษในอุปกรณ์) และยังไม่ได้ลงทะเบียน อุปกรณ์ควรจะแสดง /privet/register API เพื่อให้ผู้ใช้จากเครือข่ายภายในเครื่องอ้างสิทธิ์เครื่องพิมพ์ได้
- หลังจากลงทะเบียนเสร็จแล้ว อุปกรณ์ควรเลิกแสดง /privet/register API เพื่อป้องกันไม่ให้ผู้ใช้ในเครือข่ายท้องถิ่นกลับมาอ้างสิทธิ์อุปกรณ์อีก
- อุปกรณ์บางเครื่องอาจมีวิธีลงทะเบียนอุปกรณ์ที่แตกต่างกัน และไม่ควรแสดง /privet/register API เลย (เช่น เครื่องมือเชื่อมต่อ Chrome Cloud Print)
กระบวนการลงทะเบียนประกอบด้วย 3 ขั้นตอน (ดูการลงทะเบียนแบบไม่ระบุชื่อสําหรับ Cloud Print)
- เริ่มขั้นตอนการลงทะเบียนโดยไม่ระบุชื่อ
- ไคลเอ็นต์เริ่มต้นกระบวนการนี้โดยเรียก /privet/register API อุปกรณ์อาจรอการยืนยันของผู้ใช้ในเวลานั้น
- รับโทเค็นการอ้างสิทธิ์
โปรแกรมจะสํารวจแบบสํารวจเพื่อให้ทราบช่วงเวลาที่อุปกรณ์พร้อมดําเนินการต่อ เมื่ออุปกรณ์พร้อมจะส่งคําขอไปยังเซิร์ฟเวอร์เพื่อเรียกโทเค็นการลงทะเบียนและ URL การลงทะเบียน โทเค็นและ URL ที่ได้รับควรกลับไปยังไคลเอ็นต์ ในขั้นตอนนี้ หากอุปกรณ์ได้รับสายเรียกเข้าอีกสายหนึ่งเพื่อเริ่มการลงทะเบียน ควรทําอย่างไร
- หากเป็นผู้ใช้รายเดียวกันที่เริ่มลงทะเบียนแล้ว ให้วางข้อมูลก่อนหน้านี้ทั้งหมด (หากมี) แล้วเริ่มกระบวนการลงทะเบียนใหม่
- หากเป็นผู้ใช้รายอื่น - ให้ส่งคืนข้อผิดพลาด device_hangouts และหมดเวลา 30 วินาที
ลงทะเบียนให้เสร็จสมบูรณ์
หลังจากที่ลูกค้าอ้างสิทธิ์อุปกรณ์แล้ว ไคลเอ็นต์ควรแจ้งให้อุปกรณ์ลงทะเบียนให้เสร็จสิ้น เมื่อขั้นตอนการลงทะเบียนเสร็จสมบูรณ์ อุปกรณ์ควรส่งประกาศการอัปเดตรวมถึงรหัสอุปกรณ์ที่ได้รับมาใหม่
หมายเหตุ: ขณะที่อุปกรณ์กําลังประมวลผลการเรียก /privet/register API การเรียกใช้ /privet/register API อื่นๆ อาจไม่ประมวลผลพร้อมกัน อุปกรณ์ต้องส่งคืนข้อผิดพลาด device_hangouts และหมดเวลา 30 วินาที
ขอแนะนําให้ยืนยันการลงทะเบียนของผู้ใช้ในอุปกรณ์ หากใช้แล้ว อุปกรณ์ต้องรอการยืนยันจากผู้ใช้หลังจากได้รับการเรียก /privet/register?action=start API ไคลเอ็นต์จะเรียกใช้ /privet/register?action=getClaimToken API เพื่อดูว่าการยืนยันผู้ใช้เสร็จสมบูรณ์และมีโทเค็นการอ้างสิทธิ์พร้อมใช้งานหรือไม่ หากผู้ใช้ยกเลิกการลงทะเบียนในอุปกรณ์ (เช่น กดปุ่มยกเลิก) ต้องแสดงข้อผิดพลาด user_cancel หากผู้ใช้ไม่ยืนยันการลงทะเบียนภายในระยะเวลาที่กําหนด ก็จะต้องแสดงข้อความ error_timeout กลับมา ดูรายละเอียดเพิ่มเติมได้ที่ส่วนค่าเริ่มต้น
4.3.1 อินพุต
/privet/register API มีพารามิเตอร์อินพุตต่อไปนี้ชื่อ | ค่า |
---|---|
การดำเนินการ | อาจเป็นอย่างใดอย่างหนึ่งต่อไปนี้
เริ่มต้น - เพื่อเริ่มขั้นตอนการลงทะเบียน getClaimToken - เรียกโทเค็นการอ้างสิทธิ์สําหรับอุปกรณ์ ยกเลิก - เพื่อยกเลิกขั้นตอนการลงทะเบียน เสร็จสมบูรณ์ - เพื่อเสร็จสิ้นขั้นตอนการลงทะเบียน |
ผู้ใช้ | อีเมลของผู้ใช้ที่จะอ้างสิทธิ์อุปกรณ์นี้ |
อุปกรณ์ต้องตรวจสอบว่าอีเมลจากการดําเนินการทั้งหมด (เริ่มต้น, getClaimToken, ยกเลิก, เสร็จสมบูรณ์) ตรงกัน
4.3.2 ไปกลับ
/privet/register API จะแสดงข้อมูลต่อไปนี้:ชื่อค่า | ประเภทค่า | คำอธิบาย |
---|---|---|
การดำเนินการ | สตริง | การกระทําเดียวกันกับพารามิเตอร์อินพุต |
ผู้ใช้ | สตริง (ไม่บังคับ) | ผู้ใช้เหมือนกับในพารามิเตอร์อินพุต (อาจหายไปหากไม่ระบุไว้ในอินพุต) |
โทเค็น | สตริง (ไม่บังคับ) | โทเค็นการลงทะเบียน (บังคับสําหรับ &"getClaimToken" การตอบกลับ ละเว้นสําหรับ "start", "complete", "cancel") |
URL การอ้างสิทธิ์ | สตริง (ไม่บังคับ) | URL สําหรับลงทะเบียน (บังคับสําหรับ "getClaimToken" การตอบกลับ, ละเว้นสําหรับ "start", "complete", "cancel") สําหรับ Cloud Printer เซิร์ฟเวอร์จะต้องเป็น "complete_invite_url" ที่ได้รับจากเซิร์ฟเวอร์ |
การอ้างสิทธิ์อัตโนมัติ URL | สตริง (ไม่บังคับ) | URL สําหรับลงทะเบียน (บังคับสําหรับ "getClaimToken" การตอบกลับ, ละเว้นสําหรับ "start", "complete", "cancel") สําหรับ Cloud Printer เซิร์ฟเวอร์จะต้องเป็น "automatic_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 ข้อผิดพลาด
/privet/register API อาจแสดงผลข้อผิดพลาดต่อไปนี้ (ดูรายละเอียดในส่วนข้อผิดพลาด)ข้อผิดพลาด | คำอธิบาย |
---|---|
อุปกรณ์ไม่ว่าง | อุปกรณ์ไม่ว่างและดําเนินการที่ขอไม่ได้ ลองอีกครั้งหลังหมดเวลา |
การกระทําที่รอดําเนินการ | เพื่อตอบสนองต่อ "getClaimToken" ข้อผิดพลาดนี้บ่งชี้ว่าอุปกรณ์อยู่ระหว่างรอการยืนยันจากผู้ใช้ และควรลองส่งคําขอ "getClaimToken" อีกครั้งหลังจากหมดเวลา |
ยกเลิกผู้ใช้ | ผู้ใช้ยกเลิกกระบวนการลงทะเบียนจากอุปกรณ์อย่างชัดแจ้ง |
หมดเวลาการยืนยัน | หมดเวลายืนยันผู้ใช้ |
การดําเนินการไม่ถูกต้อง | มีการเรียกการทํางานที่ไม่ถูกต้อง ตัวอย่างเช่น หากลูกค้าชื่อ action=complete ก่อนที่จะเรียกใช้ action=start และ action=getClaimToken |
พารามิเตอร์ไม่ถูกต้อง | พารามิเตอร์ที่ระบุในคําขอไม่ถูกต้อง (ควรละเว้นพารามิเตอร์ที่ไม่รู้จักอย่างปลอดภัยเพื่อให้ใช้งานร่วมกันได้ในอนาคต) ตัวอย่างเช่น แสดงค่าเหล่านี้หากไคลเอ็นต์ชื่อ action=unknown หรือ user= |
ข้อผิดพลาดการกําหนดค่าอุปกรณ์ | วันที่/เวลา (หรือการตั้งค่าอื่นๆ บางรายการ) ไม่ถูกต้อง ผู้ใช้ต้องไปที่ (เว็บไซต์ภายในของอุปกรณ์) แล้วกําหนดการตั้งค่าอุปกรณ์ |
ออฟไลน์ | อุปกรณ์ออฟไลน์อยู่ในขณะนี้และไม่สามารถสื่อสารกับเซิร์ฟเวอร์ได้ |
ข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ | เกิดข้อผิดพลาดของเซิร์ฟเวอร์ระหว่างขั้นตอนการลงทะเบียน |
ที่ไม่ถูกต้อง _x_privet_token | X-Privet-Token ไม่ถูกต้องหรือว่างเปล่าในคําขอ |
อุปกรณ์ต้องหยุดการแสดง /privet/register API หลังจากการลงทะเบียนเสร็จสมบูรณ์ หากอุปกรณ์ไม่ได้เปิดเผย /privet/register API อุปกรณ์จะต้องแสดงข้อผิดพลาด HTTP 404 ดังนั้น หากมีการลงทะเบียนอุปกรณ์ไว้แล้ว การเรียก API นี้จะต้องแสดงข้อผิดพลาด 404 หากไม่มีส่วนหัว X-Privet-Token อุปกรณ์ต้องแสดงข้อผิดพลาด HTTP 400
4.4. /privet/accesstoken API
/privet/accesstoken API เป็นแบบไม่บังคับ เป็นคําขอ HTTP GET /privet/accesstoken API ต้องตรวจสอบส่วนหัวที่ถูกต้อง "X-Privet-Token" อุปกรณ์ต้องนํา API นี้ไปใช้ใน &"/privet/accesstoken" url:GET /privet/accesstoken HTTP/1.1
เมื่ออุปกรณ์ได้รับการเรียก /accesstoken API เซิร์ฟเวอร์ควรเรียกเซิร์ฟเวอร์เพื่อเรียกโทเค็นเพื่อการเข้าถึงสําหรับผู้ใช้ที่ระบุ และส่งโทเค็นกลับไปยังไคลเอ็นต์ จากนั้นไคลเอ็นต์จะใช้โทเค็นเพื่อการเข้าถึงเพื่อเข้าถึงอุปกรณ์นี้ผ่านระบบคลาวด์
อุปกรณ์ Cloud Print ต้องเรียก API ต่อไปนี้:
/cloudprint/proximitytokenและส่งผ่าน "printeridgoogleappslt;printer_id>" และ "user" จาก API ภายใน หากทําสําเร็จ การตอบกลับของเซิร์ฟเวอร์จะมีออบเจ็กต์ต่อไปนี้
"proximity_token": { "user": "user@domain.com", "token": "AAA111222333444555666777", "expires_in": 600 }อุปกรณ์ Cloud Print จะต้องส่งค่าของออบเจ็กต์ "proximity_token" ในการตอบกลับการเรียก /privet/accesstoken API ภายในเครื่อง วิธีนี้มีประโยชน์มากกว่า (รับประกันอนาคต) หากอุปกรณ์ส่งพารามิเตอร์ทั้งหมด (รวมถึงพารามิเตอร์ที่ไม่ได้อธิบายไว้ในข้อมูลจําเพาะนี้)
4.4.1 อินพุต
/privet/accesstoken API มีพารามิเตอร์อินพุตต่อไปนี้ชื่อ | ค่า |
---|---|
ผู้ใช้ | อีเมลของผู้ใช้ที่ตั้งใจจะใช้โทเค็นเพื่อการเข้าถึงนี้ คําขออาจว่างเปล่า |
4.4.2 ไปกลับ
/privet/accesstoken API แสดงข้อมูลต่อไปนี้ชื่อค่า | ประเภทค่า | คำอธิบาย |
---|---|---|
โทเค็น | สตริง | โทเค็นเพื่อการเข้าถึงที่เซิร์ฟเวอร์ส่งคืน |
ผู้ใช้ | สตริง | ผู้ใช้เหมือนกับในพารามิเตอร์อินพุต |
หมดอายุภายใน | int | จํานวนวินาทีก่อนที่โทเค็นนี้จะหมดอายุ ได้รับจากเซิร์ฟเวอร์และส่งต่อในการตอบกลับนี้ |
ตัวอย่าง
{ "token": "AAA111222333444555666777", "user": "user@domain.com", "expires_in": 600 }
4.4.3 ข้อผิดพลาด
/privet/accesstoken API อาจแสดงข้อผิดพลาดต่อไปนี้ (ดูรายละเอียดในส่วนข้อผิดพลาด)ข้อผิดพลาด | คำอธิบาย |
---|---|
ออฟไลน์ | อุปกรณ์ออฟไลน์อยู่ในขณะนี้จึงสื่อสารกับเซิร์ฟเวอร์ไม่ได้ |
การเข้าถึงถูกปฏิเสธ | มีสิทธิ์ไม่เพียงพอ ไม่สามารถเข้าใช้ได้ อุปกรณ์ควรแสดงข้อผิดพลาดนี้เมื่อเซิร์ฟเวอร์ปฏิเสธคําขออย่างชัดเจน |
พารามิเตอร์ไม่ถูกต้อง | พารามิเตอร์ที่ระบุในคําขอไม่ถูกต้อง (ควรละเว้นพารามิเตอร์ที่ไม่รู้จักอย่างปลอดภัยเพื่อให้ใช้งานร่วมกันได้ในอนาคต) เช่น หากลูกค้าชื่อ /accesstoken?user= หรือ /accesstoken |
ข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ | เกิดข้อผิดพลาดกับเซิร์ฟเวอร์ |
ที่ไม่ถูกต้อง _x_privet_token | X-Privet-Token ไม่ถูกต้องหรือว่างเปล่าในคําขอ |
หากอุปกรณ์ไม่ได้เปิดเผย /privet/accesstoken API อุปกรณ์ต้องแสดงข้อผิดพลาด HTTP 404 หากไม่มีส่วนหัว X-Privet-Token อุปกรณ์ต้องแสดงข้อผิดพลาด HTTP 400
4.5 /privet/capability API
/privet/capability API เป็นตัวเลือกแบบไม่บังคับ เป็นคําขอ HTTP GET /privet/capability API ต้องตรวจสอบ ส่วนหัว "X-Privet-Token" ที่ถูกต้อง อุปกรณ์ต้องนํา API นี้ไปใช้ด้วย "/privet/capability" url:GET /privet/capabilities HTTP/1.1เมื่ออุปกรณ์ได้รับการเรียก /capability API หากอุปกรณ์สามารถใช้งานได้ ก็จะควรติดต่อเซิร์ฟเวอร์เพื่อให้ได้ความสามารถในการอัปเดต เช่น หากเครื่องพิมพ์รองรับการโพสต์งานพิมพ์ (ได้รับภายในเครื่อง) เองผ่านทางบริการ Cloud Print เครื่องพิมพ์นั้นก็จะกลับมาใช้งานได้ตามที่บริการ Cloud Print จะส่งคืน ในกรณีนี้ Cloud Print อาจเปลี่ยนความสามารถเดิมของเครื่องพิมพ์โดยการเพิ่มฟีเจอร์ใหม่ๆ ที่เครื่องพิมพ์น่าจะทําก่อนส่งงานไปยังเครื่องพิมพ์ กรณีที่พบบ่อยที่สุดคือรายการประเภทเอกสารที่รองรับ หากเครื่องพิมพ์ออฟไลน์อยู่ ก็ควรจะแสดงประเภทเอกสารที่รองรับ อย่างไรก็ตาม หากเครื่องพิมพ์ออนไลน์อยู่และลงทะเบียนกับ Cloud Print เครื่องพิมพ์จะต้องส่งคืน "*/*" เป็นหนึ่งในประเภทที่รองรับ บริการ Cloud Print จะทํา Conversion ที่จําเป็นในกรณีนี้ สําหรับการพิมพ์แบบออฟไลน์ เครื่องพิมพ์ต้องรองรับรูปแบบ "image/pwg-raster" เป็นอย่างน้อย
4.5.1 อินพุต
/privet/capability API มีพารามิเตอร์อินพุตต่อไปนี้ชื่อ | ค่า |
---|---|
ออฟไลน์ | (ไม่บังคับ) เป็น&"ออฟไลน์=1" ได้เท่านั้น ในกรณีนี้อุปกรณ์ควรส่งคืนความสามารถในการใช้งานแบบออฟไลน์ (หากแตกต่างจากความสามารถ "online") |
4.5.2 ไปกลับ
/privet/capability API แสดงความสามารถของอุปกรณ์ในรูปแบบ 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 ข้อผิดพลาด
/privet/capability API อาจแสดงผลข้อผิดพลาดต่อไปนี้ (ดูรายละเอียดในส่วนข้อผิดพลาด)ข้อผิดพลาด | คำอธิบาย |
---|---|
ที่ไม่ถูกต้อง _x_privet_token | X-Privet-Token ไม่ถูกต้องหรือว่างเปล่าในคําขอ |
หากอุปกรณ์ไม่ได้เปิดเผย /privet/capability API อุปกรณ์จะต้องแสดงข้อผิดพลาด HTTP 404 หากไม่มีส่วนหัว X-Privet-Token อุปกรณ์ต้องแสดงข้อผิดพลาด HTTP 400
4.6 ข้อผิดพลาด
ระบบจะแสดงผลข้อผิดพลาดจาก API ข้างต้นในรูปแบบต่อไปนี้ชื่อค่า | ประเภทค่า | คำอธิบาย |
---|---|---|
error | สตริง | ประเภทข้อผิดพลาด (กําหนดต่อ API) |
คำอธิบาย | สตริง (ไม่บังคับ) | คําอธิบายข้อผิดพลาดที่มนุษย์อ่านได้ |
เซิร์ฟเวอร์ API | สตริง (ไม่บังคับ) | ในกรณีที่เกิดข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ ช่องนี้ประกอบด้วย API ของเซิร์ฟเวอร์ที่ล้มเหลว |
รหัสเซิร์ฟเวอร์ [server_code] | int (ไม่บังคับ) | ในกรณีที่เกิดข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ ช่องนี้ประกอบด้วยรหัสข้อผิดพลาดที่เซิร์ฟเวอร์ส่งกลับมา |
รหัสเซิร์ฟเวอร์ http_ | int (ไม่บังคับ) | ในกรณีที่เกิดข้อผิดพลาด HTTP ของเซิร์ฟเวอร์ ช่องนี้จะแสดงเซิร์ฟเวอร์รหัสข้อผิดพลาดของ HTTP |
ระยะหมดเวลา | int (ไม่บังคับ) | จํานวนวินาทีที่ไคลเอ็นต์จะรอก่อนลองอีกครั้ง (สําหรับข้อผิดพลาดที่กู้คืนได้เท่านั้น) ไคลเอ็นต์ต้องสุ่มหมดเวลาจริงจากค่านี้เป็นค่าที่มากกว่า 20% |
API ทั้งหมดต้องแสดงข้อผิดพลาด HTTP 400 หากไม่มีส่วนหัว X-Privet-Token
ส่วนหัว HTTP/1.1 400 ไม่มี X-Privet-Token
ตัวอย่างที่ 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. API เครื่องพิมพ์
หนึ่งในประเภทโปรโตคอลที่โปรโตคอลนี้รองรับคือ เครื่องพิมพ์ประเภท อุปกรณ์ที่รองรับประเภทนี้อาจใช้งานฟังก์ชันบางอย่างสําหรับเครื่องพิมพ์โดยเฉพาะ ควรพิมพ์เครื่องพิมพ์ที่พร้อมใช้งานในระบบคลาวด์ ผ่านเซิร์ฟเวอร์ Cloud Print
![](https://developers.google.cn/cloud-print/images/privet_image07.jpg?authuser=4&hl=th)
ในบางกรณี ลูกค้าอาจต้องส่งเอกสารภายในองค์กร คุณอาจต้องใช้เมื่อไคลเอ็นต์ไม่มีรหัส Google หรือไม่สามารถสื่อสารกับเซิร์ฟเวอร์ Cloud Print ในกรณีดังกล่าว งานพิมพ์จะส่งไปยังเครื่องพิมพ์ในเครื่อง เครื่องพิมพ์จะใช้บริการ Cloud Print ในการจัดคิวและการแปลงงาน เครื่องพิมพ์จะโพสต์งานที่ส่งซ้ําไปยังบริการ Cloud Print อีกครั้ง จากนั้นขอ เนื่องจากเครื่องพิมพ์ส่งผ่านระบบคลาวด์ ขั้นตอนนี้จะมอบประสบการณ์ของผู้ใช้ที่ยืดหยุ่นในข้อกําหนดในการให้บริการ (Conversion) รวมถึงการจัดการ/การติดตามงานพิมพ์
![](https://developers.google.cn/cloud-print/images/privet_image08.jpg?authuser=4&hl=th)
เนื่องจากบริการ Cloud Print ใช้ Conversion เครื่องพิมพ์ควรแสดงโฆษณาที่รองรับรูปแบบอินพุตทั้งหมด ("*/*") ในรายการประเภทเนื้อหาที่รองรับ ได้แก่
{ "version": "1.0", "printer": { "supported_content_type": [ { "content_type": "image/pwg-raster" }, { "content_type": "*/*" } ] } }
ในบางกรณี อาจต้องการโซลูชันแบบออฟไลน์ที่สมบูรณ์ เนื่องจากเครื่องพิมพ์รองรับการป้อนข้อมูลในจํานวนที่จํากัด ไคลเอ็นต์จึงต้องแปลงเอกสารเป็นรูปแบบเครื่องพิมพ์ที่รองรับเพียงไม่กี่รูปแบบ
![](https://developers.google.cn/cloud-print/images/privet_image04.jpg?authuser=4&hl=th)
ข้อกําหนดนี้กําหนดให้เครื่องพิมพ์ทั้งหมดรองรับรูปแบบ PWG Raster ("image/pwg-raster") เป็นอย่างน้อยสําหรับเคสพิมพ์ออฟไลน์ เครื่องพิมพ์อาจรองรับรูปแบบอื่นๆ (เช่น JPEG) และหากไคลเอ็นต์รองรับ ก็อาจส่งเอกสารในรูปแบบนั้น เครื่องพิมพ์ต้องแสดงประเภทที่รองรับผ่าน /capability API ตัวอย่างเช่น
{ "version": "1.0", "printer": { "supported_content_type": [ { "content_type": "image/pwg-raster" }, { "content_type": "image/jpeg" } ] } }ลูกค้าอาจเริ่มพิมพ์ผ่านเครือข่ายภายในได้ 2 วิธี
การพิมพ์แบบง่าย - ไคลเอ็นต์จะส่งเอกสารผ่านเครือข่าย LAN ไปยัง /submitdoc API (โดยไม่ต้องระบุพารามิเตอร์ Jobs_id) ระบบจะพิมพ์เอกสารที่ส่งโดยใช้การตั้งค่าตั๋ว พิมพ์เริ่มต้นและไม่จําเป็นต้องมีสถานะงานพิมพ์ หากเครื่องพิมพ์สนับสนุนการพิมพ์ประเภทนี้เท่านั้น เครื่องพิมพ์จะต้องโฆษณาเฉพาะ /submitdoc API ในการตอบกลับของ /privet/info API เท่านั้น
"api": [ "/privet/accesstoken", "/privet/capabilities", "/privet/printer/submitdoc", ]
การพิมพ์ขั้นสูง - ไคลเอ็นต์ควรสร้างงานพิมพ์บนเครื่องพิมพ์โดยเรียก /privet/printer/createjob API โดยใช้ตั๋วงาน CJT ที่ถูกต้องในคําขอ เครื่องพิมพ์ต้องจัดเก็บการพิมพ์ตั๋วไว้ในหน่วยความจําและส่งคืน Jobs_id กลับไปยังไคลเอ็นต์ จากนั้นไคลเอ็นต์จะเรียกใช้ /printer/submitdoc API และระบุ job_id ที่ได้รับก่อนหน้านี้ เมื่อถึงเวลานั้น เครื่องพิมพ์จะเริ่มพิมพ์ ไคลเอ็นต์จะสํารวจเครื่องพิมพ์สําหรับสถานะงานพิมพ์โดยเรียกใช้ /privet/printer/jobstate API
ในสภาพแวดล้อมที่มีหลายไคลเอ็นต์ จะไม่มีการรับประกันใดๆ ว่า API นี้จะถูกเรียกใช้อย่างไร ไคลเอ็นต์หนึ่งจะเรียกใช้ /createjob ระหว่างการเรียก /createjob->/submitdoc ของลูกค้ารายอื่นได้ หากต้องการขจัดอุปสรรคที่อาจเกิดขึ้นและเพิ่มความสามารถในการใช้งาน เราขอแนะนําให้มีคิวงานงานพิมพ์ที่รอดําเนินการบนเครื่องพิมพ์จํานวนไม่มาก (อย่างน้อย 3-5 ภาพ) ดังนี้
- /createjob จะใช้สปอตแรกในคิว
- อายุการใช้งานงาน (อยู่ในคิว) อย่างน้อย 5 นาที
- หากจับภาพทุกจุดในคิว ระบบจะนํางานที่พิมพ์ไม่ได้เก่าที่สุดออกและส่งงานใหม่
- หากมีงานพิมพ์ที่กําลังพิมพ์ในอุปกรณ์ (การพิมพ์แบบง่ายหรือขั้นสูง) /submitdoc ควรจะส่งคืนสถานะไม่ว่างและเสนอระยะหมดเวลาที่จะลองงานพิมพ์นี้อีกครั้ง
- หาก /submitdoc หมายถึงงานที่ถูกนําออกจากคิวแล้ว (เนื่องจากมีการเปลี่ยนหรือหมดเวลา) เครื่องพิมพ์จะแสดงข้อผิดพลาด invalid_print_job และไคลเอ็นต์จะลองดําเนินการจากขั้นตอน /createjob อีกครั้ง ไคลเอ็นต์จะต้องรอระยะหมดเวลาแบบสุ่มสูงสุด 5 วินาทีก่อนที่จะลองอีกครั้ง
หากข้อจํากัดของหน่วยความจําทําให้ไม่สามารถเก็บงานที่รอดําเนินการหลายงานในอุปกรณ์ คิวงานงานพิมพ์อาจยาว 1 คิว แต่ยังคงเป็นไปตามโปรโตคอลเดียวกับข้างต้น หลังจากที่งานเสร็จสมบูรณ์หรือล้มเหลวโดยมีข้อผิดพลาด เครื่องพิมพ์ควรจัดเก็บข้อมูลเกี่ยวกับสถานะของงานไว้อย่างน้อย 5 นาที ขนาดคิวสําหรับการจัดเก็บสถานะงานที่เสร็จสมบูรณ์ควรมีขนาดอย่างน้อย 10 หากมีสถานะงานอื่นที่ต้องเก็บไว้ สถานะที่เก่าที่สุดอาจถูกนําออกจากคิวก่อนระยะหมดเวลา 5 นาที
หมายเหตุ: สําหรับตอนนี้ เราจะตรวจสอบแบบสํารวจสถานะงาน ในอนาคต เราอาจกําหนดให้เครื่องพิมพ์ส่งการแจ้งเตือน TXT DNS เมื่อสถานะงานพิมพ์ใดๆ มีการเปลี่ยนแปลง
5.1. /privet/printer/createjob API
/privet/printer/createjob API เป็นแบบไม่บังคับ (ดูการพิมพ์แบบง่ายด้านบน) เป็นคําขอ HTTP POST /privet/printer/createjob API ต้องตรวจสอบส่วนหัว "X-Privet-Token" ที่ถูกต้อง อุปกรณ์ต้องใช้ API นี้ใน "/privet/printer/createjob" url:
POST /privet/printer/createjob HTTP/1.1เมื่อได้รับ /privet/printer/createjob API เครื่องพิมพ์จะต้องสร้างรหัสงานพิมพ์ใหม่ จัดเก็บตั๋วการพิมพ์ที่ได้รับในรูปแบบ CJT และส่งคืนรหัสงานพิมพ์กลับไปยังไคลเอ็นต์
5.1.1. อินพุต
/privet/printer/createjob API ไม่มีพารามิเตอร์อินพุตใน URL ส่วนเนื้อหาของคําขอควรมีข้อมูลตั๋วงานพิมพ์ในรูปแบบ CJT5.1.2. ไปกลับ
/privet/printer/createjob API ส่งคืนข้อมูลต่อไปนี้ชื่อค่า | ประเภทค่า | คำอธิบาย |
---|---|---|
รหัสงาน | สตริง | รหัสของงานพิมพ์ที่สร้างใหม่ |
หมดอายุภายใน | int | จํานวนวินาทีที่ใช้งานได้ของงานพิมพ์นี้ |
ตัวอย่าง
{ "job_id": "123", "expires_in": 600 }
5.1.3 ข้อผิดพลาด
/privet/printer/createjob API อาจแสดงข้อผิดพลาดต่อไปนี้ (ดูรายละเอียดในส่วนข้อผิดพลาด)ข้อผิดพลาด | คำอธิบาย |
---|---|
ตั๋วไม่ถูกต้อง | ตั๋วรูปอัดที่ส่งไม่ถูกต้อง |
เครื่องพิมพ์มีที่ว่าง | เครื่องพิมพ์ไม่ว่างและประมวลผล /createjob ไม่ได้ในขณะนี้ ลองอีกครั้งหลังหมดเวลา |
ข้อผิดพลาดเครื่องพิมพ์ | เครื่องพิมพ์อยู่ในสถานะข้อผิดพลาด และต้องมีการโต้ตอบของผู้ใช้เพื่อแก้ไข คําอธิบายควรมีคําอธิบายโดยละเอียด (เช่น "กระดาษแยมในถาด 1") |
ที่ไม่ถูกต้อง _x_privet_token | X-Privet-Token ไม่ถูกต้องหรือว่างเปล่าในคําขอ |
หากอุปกรณ์ไม่ได้แสดงผล /privet/printer/createjob โปรแกรมดังกล่าวจะต้องแสดงข้อผิดพลาด HTTP 404 หากไม่มีส่วนหัว X-Privet-Token อุปกรณ์ต้องแสดงข้อผิดพลาด HTTP 400
5.2. /privet/printer/submitdoc API
/privet/printer/submitdoc API จําเป็นสําหรับการติดตั้งใช้งานการพิมพ์ผ่านเครือข่ายภายใน (แบบออฟไลน์หรือการโพสต์ลงใน Cloud Print) เป็นคําขอ HTTP POST /privet/printer/submitdoc API ต้องตรวจสอบส่วนหัวที่ถูกต้อง "X-Privet-Token" อุปกรณ์ต้องนํา API นี้ไปใช้ด้วย "/privet/printer/submitdoc" url:POST /privet/printer/submitdoc HTTP/1.1เมื่อได้รับการเรียก /privet/printer/submitdoc API เครื่องพิมพ์ควรเริ่มพิมพ์ หากเริ่มต้นการพิมพ์ไม่ได้ ข้อความแสดงข้อผิดพลาดจะต้องแสดงข้อผิดพลาดเป็นเครื่องพิมพ์
หากเครื่องพิมพ์เก็บข้อมูลทั้งหมดไว้ในบัฟเฟอร์ภายในไม่ได้ ควรใช้กลไก TCP เพื่อชะลอการโอนข้อมูลจนกว่าจะพิมพ์ส่วนหนึ่งของเอกสาร ทําให้ใช้บางส่วนของบัฟเฟอร์ได้อีกครั้ง (เช่น เครื่องพิมพ์อาจตั้งค่า windowsize=0 ในเลเยอร์ TCP ซึ่งจะทําให้ไคลเอ็นต์ต้องรอ)
การส่งเอกสารไปยังเครื่องพิมพ์อาจใช้เวลานานกว่าปกติ ไคลเอ็นต์ควรตรวจสอบสถานะของเครื่องพิมพ์และงาน (การพิมพ์ขั้นสูง) ได้ในระหว่างดําเนินการพิมพ์ ในการดําเนินการดังกล่าว เครื่องพิมพ์ต้องอนุญาตให้ไคลเอ็นต์เรียกใช้ /privet/info และ /privet/printer/jobstate API ขณะประมวลผลการเรียก /privet/printer/submitdoc API เราขอแนะนําให้ไคลเอ็นต์ทั้งหมดเริ่มชุดข้อความใหม่เพื่อเรียกใช้การเรียก /privet/printer/submitdoc API เพื่อให้ชุดข้อความหลักใช้ /privet/info และ /privet/printer/jobstate API เพื่อตรวจสอบสถานะเครื่องพิมพ์และตําแหน่งงานได้
หมายเหตุ: เมื่อทํางานเสร็จแล้วหรือทําการทําแท้งของงานพิมพ์ในเครื่อง ขอแนะนําอย่างยิ่ง (และจะต้องใช้ในข้อกําหนดนี้ในเวอร์ชันใหม่ในอนาคต) เพื่อรายงานสถานะสุดท้ายของงานไปยังอินเทอร์เฟซ /duration/submit เพื่อวัตถุประสงค์ทางบัญชีและประสบการณ์ของผู้ใช้ & พารามิเตอร์ "printerid", "title", "contentType" และ "final_semantic_state" (ในรูปแบบ PrintJobState) และพารามิเตอร์ "tag" (พารามิเตอร์ซ้ํากัน) และ " Ticket&ettick (ตั๋วงาน) โปรดทราบว่า PrintJobState ที่ให้มาถือเป็นเรื่องจริง เช่น ประเภทต้องเป็น "เสร็จสิ้น" หรือ "ล้มเลิก" และต้องระบุสาเหตุในกรณีที่ล้มเลิก (ดูรายละเอียดใน JobState) โปรดทราบด้วยว่าการใช้อินเทอร์เฟซ /duration/submit เพื่อรายงานงานพิมพ์ในร้านไม่ได้กล่าวถึงในข้อกําหนดเนื่องจากส่วนดังกล่าวมีจุดประสงค์เพื่ออธิบายการใช้งานหลักของอินเทอร์เฟซ: การส่งงานพิมพ์พร้อมกับเอกสารพิมพ์ที่ให้ไว้ในพารามิเตอร์ "content"
5.2.1. อินพุต
/privet/printer/submitdoc API มีพารามิเตอร์อินพุตต่อไปนี้ชื่อ | ค่า |
---|---|
รหัสงาน | (ไม่บังคับ) รหัสงานพิมพ์ ไม่คํานึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ (ดูด้านบน) ต้องตรงกับเครื่องพิมพ์ที่ส่งคืน |
user_name | (ไม่บังคับ) ชื่อผู้ใช้ที่มนุษย์อ่านได้ ข้อมูลนี้ไม่ใช่คําจํากัดความที่แน่นอนและควรใช้สําหรับคําอธิบายประกอบงานพิมพ์เท่านั้น หากมีการโพสต์งานไปยังบริการ Cloud Print อีกครั้ง สตริงนี้ควรจะแนบอยู่กับงาน Cloud Print |
ชื่อไคลเอ็นต์ | (ไม่บังคับ) ชื่อแอปพลิเคชันของไคลเอ็นต์ที่ส่งคําขอนี้ เพื่อการแสดงผลเท่านั้น หากมีการโพสต์งานซ้ําในบริการ Cloud Print สตริงนี้ควรจะแนบไปกับงาน Cloud Print |
ชื่องาน | (ไม่บังคับ) ชื่อของงานพิมพ์ที่จะบันทึก หากมีการโพสต์งานไปยังบริการ Cloud Print อีกครั้ง สตริงนี้ควรจะแนบอยู่กับงาน Cloud Print |
ออฟไลน์ | (ไม่บังคับ) ต้องเป็น "Offline=1" เท่านั้น ในกรณีนี้ เครื่องพิมพ์ควรลองพิมพ์แบบออฟไลน์เท่านั้น (ไม่ต้องโพสต์ไปยังเซิร์ฟเวอร์ Cloud Print ซ้ํา) |
เนื้อหาของคําขอควรมีเอกสารที่ถูกต้องสําหรับการพิมพ์ "ความยาวเนื้อหา&เครื่องหมายคําพูดควรมีความยาวที่ถูกต้องของคําขอ "Content-Type" ควรตั้งค่าส่วนหัวเป็นประเภท MIME ของเอกสาร และตรงกับประเภทประเภทใดประเภทหนึ่งใน CDD (เว้นแต่ว่า CDD ระบุ "*/*")
เราขอแนะนําให้ลูกค้าระบุชื่อผู้ใช้ (หรืออีเมล) ชื่อลูกค้า และชื่อตําแหน่งงานที่ถูกต้องพร้อมคําขอนี้ ช่องเหล่านี้จะใช้เฉพาะใน UI เพื่อปรับปรุงประสบการณ์ของผู้ใช้เท่านั้น
5.2.2. ไปกลับ
/privet/printer/submitdoc API แสดงผลข้อมูลต่อไปนี้ชื่อค่า | ประเภทค่า | คำอธิบาย |
---|---|---|
รหัสงาน | สตริง | รหัสของงานพิมพ์ที่สร้างใหม่ (พิมพ์แบบง่าย) หรือ Jobs_id ที่ระบุไว้ในคําขอ (การพิมพ์ขั้นสูง) |
หมดอายุภายใน | int | จํานวนวินาทีที่ใช้งานได้ของงานพิมพ์นี้ |
ประเภทงาน | สตริง | ประเภทเนื้อหาของเอกสารที่ส่ง |
ขนาดของงาน | int 64 บิต | ขนาดของข้อมูลการพิมพ์ในหน่วยไบต์ |
ชื่องาน | สตริง | (ไม่บังคับ) ใช้ชื่องานเหมือนกับที่ป้อน (หากมี) |
ตัวอย่าง
{ "job_id": "123", "expires_in": 500, "job_type": "application/pdf", "job_size": 123456, "job_name": "My PDF document" }
5.2.3. ข้อผิดพลาด
/privet/printer/submitdoc API อาจแสดงข้อผิดพลาดต่อไปนี้ (ดูรายละเอียดในส่วนข้อผิดพลาด)ข้อผิดพลาด | คำอธิบาย |
---|---|
งานสิ่งพิมพ์ไม่ถูกต้อง | รหัสงานที่ไม่ถูกต้อง/หมดอายุแล้วตามที่ระบุไว้ในคําขอ ลองอีกครั้งหลังหมดเวลา |
ประเภทเอกสารไม่ถูกต้อง | เครื่องพิมพ์ไม่สนับสนุนประเภท MIME ของเอกสาร |
เอกสารไม่ถูกต้อง | เอกสารที่ส่งไม่ถูกต้อง |
document_to__large | เอกสารใหญ่เกินขนาดสูงสุดที่อนุญาต |
เครื่องพิมพ์มีที่ว่าง | เครื่องพิมพ์ไม่ว่างและประมวลผลเอกสารไม่ได้ในขณะนี้ ลองอีกครั้งหลังหมดเวลา |
ข้อผิดพลาดเครื่องพิมพ์ | เครื่องพิมพ์อยู่ในสถานะข้อผิดพลาด และต้องมีการโต้ตอบของผู้ใช้เพื่อแก้ไข คําอธิบายควรมีคําอธิบายโดยละเอียด (เช่น "กระดาษแยมในถาด 1") |
พารามิเตอร์ไม่ถูกต้อง | พารามิเตอร์ที่ระบุในคําขอไม่ถูกต้อง (ไม่ต้องสนใจพารามิเตอร์ที่ไม่รู้จักอย่างปลอดภัยสําหรับความเข้ากันได้ในอนาคต) |
ยกเลิกผู้ใช้ | ผู้ใช้ยกเลิกกระบวนการพิมพ์จากอุปกรณ์อย่างชัดแจ้ง |
ข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ | โพสต์เอกสารไปยัง Cloud Print ไม่สําเร็จ |
ที่ไม่ถูกต้อง _x_privet_token | X-Privet-Token ไม่ถูกต้องหรือว่างเปล่าในคําขอ |
หากอุปกรณ์ไม่เปิดเผย /privet/printer/submitdoc อุปกรณ์ต้องแสดงข้อผิดพลาด HTTP 404 หากไม่มีส่วนหัว X-Privet-Token อุปกรณ์ต้องแสดงข้อผิดพลาด HTTP 400
หมายเหตุ: /privet/printer/submitdoc API อาจต้องใช้การจัดการพิเศษในฝั่งของเครื่องพิมพ์ (เนื่องจากเพย์โหลดขนาดใหญ่ที่แนบมาด้วย) ในบางกรณี (ขึ้นอยู่กับการใช้แพลตฟอร์มและแพลตฟอร์ม HTTP ของเครื่องพิมพ์) เครื่องพิมพ์อาจปิด Socket ก่อนแสดงข้อผิดพลาดของ HTTP หรือเครื่องพิมพ์อาจแสดงข้อผิดพลาด 503 (แทนข้อผิดพลาดของ Privet) เครื่องพิมพ์ควรพยายาม มากที่สุดเท่าที่จะทําได้เพื่อส่งคืน Privet อย่างไรก็ตาม ไคลเอ็นต์ทั้งหมดที่ใช้ข้อกําหนด Privet ควรจัดการซ็อกเก็ตได้ (ไม่มีข้อผิดพลาด HTTP) และเคสข้อผิดพลาดของ HTTP 503 สําหรับ /privet/printer/submitdoc API ในกรณีนี้ ให้ไคลเอ็นต์จัดการข้อผิดพลาด Privet "printer_hangouts" ที่มี "timeout" ตั้งค่าเป็น 15 วินาที เพื่อหลีกเลี่ยงการลองซ้ําแบบไม่สิ้นสุด ไคลเอ็นต์อาจหยุดการลองอีกครั้งหลังจากพยายามดําเนินการในระดับที่สมเหตุสมผลแล้ว (เช่น 3 ครั้ง)
5.3. /privet/printer/jobstate API
/privet/printer/jobstate API เป็นแบบไม่บังคับ (ดู Print Printing ด้านบน) เป็นคําขอ HTTP GET /privet/printer/jobstate API ต้องตรวจสอบส่วนหัวที่ถูกต้อง "X-Privet-Token" อุปกรณ์ ต้องใช้ API นี้ใน "/privet/printer/jobstate" url:GET /privet/printer/jobstate HTTP/1.1เมื่อได้รับการเรียก /privet/printer/jobstate API เครื่องพิมพ์ควรส่งคืนสถานะของงานพิมพ์ที่ขอ หรือข้อผิดพลาด error_print_job ที่ขอ
5.3.1. อินพุต
/privet/printer/jobstate API มีพารามิเตอร์อินพุตต่อไปนี้ชื่อ | ค่า |
---|---|
รหัสงาน | พิมพ์รหัสงานเพื่อส่งคืนสถานะ |
5.3.2. ไปกลับ
/privet/printer/jobstate API จะแสดงข้อมูลต่อไปนี้ชื่อค่า | ประเภทค่า | คำอธิบาย |
---|---|---|
รหัสงาน | สตริง | รหัสงานพิมพ์จะมีสถานะ |
รัฐ | สตริง | draft - มีการสร้างงานพิมพ์ในอุปกรณ์ (ยังไม่ได้รับการเรียก /privet/printer/submitdoc เลย)
อยู่ในคิว - ได้รับงานพิมพ์และเข้าคิวแล้ว แต่งานพิมพ์ยังไม่เริ่ม in_progress - งานพิมพ์อยู่ระหว่างดําเนินการพิมพ์ หยุดทํางาน - งานพิมพ์หยุดชั่วคราว แต่สามารถรีสตาร์ทด้วยตนเองหรือโดยอัตโนมัติ เสร็จสิ้น - งานพิมพ์เสร็จแล้ว ล้มเลิก - งานพิมพ์ล้มเหลว |
คำอธิบาย | สตริง | (ไม่บังคับ) คําอธิบายสถานะงานพิมพ์ที่มนุษย์อ่านได้ ควรระบุข้อมูลเพิ่มเติมหากสถานะและหยุดหรือยกเลิก ช่อง semantic_state มักให้คําอธิบายที่ดีกว่าและมีความหมายแก่ลูกค้า |
หมดอายุภายใน | int | จํานวนวินาทีที่ใช้งานได้ของงานพิมพ์นี้ |
ประเภทงาน | สตริง | (ไม่บังคับ) ประเภทเนื้อหาของเอกสารที่ส่ง |
ขนาดของงาน | int 64 บิต | (ไม่บังคับ) ขนาดของข้อมูลการพิมพ์ในหน่วยไบต์ |
ชื่องาน | สตริง | (ไม่บังคับ) ใช้ชื่องานเหมือนกับที่ป้อน (หากมี) |
รหัสงานของเซิร์ฟเวอร์ | สตริง | (ไม่บังคับ) รหัสของงานที่ส่งคืนจากเซิร์ฟเวอร์ (หากโพสต์งานไปยังบริการ Cloud Print) ละเว้นสําหรับการพิมพ์แบบออฟไลน์ |
รัฐความหมาย | 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 } }
ตัวอย่าง (หยุดงานพิมพ์เนื่องจากกระดาษหมด) สังเกตการอ้างอิงถึงสถานะอุปกรณ์ โดยไคลเอ็นต์จะต้องเรียกใช้ /privet/info API เพื่อดูรายละเอียดเพิ่มเติมเกี่ยวกับสถานะอุปกรณ์ ดังนี้
{ "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. ข้อผิดพลาด
/privet/printer/jobstate API อาจแสดงผลข้อผิดพลาดต่อไปนี้ (ดูรายละเอียดในส่วนข้อผิดพลาด)ข้อผิดพลาด | คำอธิบาย |
---|---|
งานสิ่งพิมพ์ไม่ถูกต้อง | รหัสงานที่ไม่ถูกต้อง/หมดอายุแล้วตามที่ระบุไว้ในคําขอ |
ข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ | เรียกดูสถานะงานพิมพ์ (สําหรับงานพิมพ์ที่โพสต์ไปยัง Cloud Print) ไม่สําเร็จ |
ที่ไม่ถูกต้อง _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, การพิมพ์ในเครื่อง)
- การลงทะเบียนจําเป็นต้องมีการโต้ตอบทางกายภาพกับอุปกรณ์
- ผู้ใช้จะต้องดําเนินการจริงในอุปกรณ์ (เช่น การกดปุ่ม) เพื่อยืนยันสิทธิ์เข้าถึงอุปกรณ์
- หลังจากผู้ใช้ดําเนินการที่ระบุไว้ข้างต้น เครื่องพิมพ์ควรส่งคําขอ /duration/register และไม่ควรส่งคําขอนี้จนกว่าจะดําเนินการเสร็จแล้ว (ดูแผนภาพลําดับ 1)
- หากอุปกรณ์ประมวลผลคําขอ /privet/register (เช่น กําลังรอการดําเนินการข้างต้น) อุปกรณ์จะต้องปฏิเสธคําขออื่นๆ /privet/register ทั้งหมด อุปกรณ์ต้องส่งคืนข้อผิดพลาด device_hangouts ในกรณีนี้
- อุปกรณ์ควรหมดเวลาคําขอ /register ที่ไม่ได้รับการดําเนินการที่กล่าวถึงข้างต้นภายใน 60 วินาที อุปกรณ์ต้องแสดงข้อผิดพลาด error_timeout ในกรณีนี้
- ไม่บังคับ: ขอแนะนําแต่ไม่บังคับ ตัวอย่างต่อไปนี้อาจช่วยปรับปรุงประสบการณ์ของผู้ใช้
- เครื่องพิมพ์อาจกะพริบไฟหรือหน้าจอเพื่อระบุว่าผู้ใช้จําเป็นต้องดําเนินการเพื่อยืนยันการลงทะเบียน
- เครื่องพิมพ์อาจแสดงข้อความบนหน้าจอว่า "กําลังลงทะเบียนกับ Google Cloud Print สําหรับผู้ใช้ "abc@def.com" - กด "ตกลง" เพื่อดําเนินการต่อ โดยที่ abc@def.com เป็นพารามิเตอร์ผู้ใช้จากการเรียก /register API ซึ่งจะทําให้ผู้ใช้เข้าใจได้ชัดเจนขึ้นว่า
- เป็นคําขอลงทะเบียนที่พวกเขายืนยันว่า
- สิ่งที่จะเกิดขึ้นหากไม่เรียกใช้คําขอ
- นอกเหนือจากการดําเนินการจริงเพื่อยืนยันจากเครื่องพิมพ์ (เช่น "กดปุ่ม "ตกลง") เครื่องพิมพ์อาจเสนอปุ่มให้ผู้ใช้ยกเลิกคําขอด้วย (เช่น "กด "ยกเลิก" เพื่อปฏิเสธ) การดําเนินการนี้จะช่วยให้ผู้ใช้ที่ไม่ได้ส่งคําขอให้ลงทะเบียน ยกเลิกคําขอก่อนระยะหมดเวลา 60 วินาที อุปกรณ์ต้องแสดงข้อผิดพลาด user_cancel ในกรณีนี้
- การโอนการเป็นเจ้าของ:
- ระบบอาจลบอุปกรณ์ออกจากบริการ Cloud อย่างชัดเจน
- หากอุปกรณ์ประสบความสําเร็จ แต่ไม่มีคําอธิบายอุปกรณ์เนื่องมาจากการเรียกใช้ /":{"/printer (สําหรับ GCP) อุปกรณ์จะต้องเปลี่ยนกลับไปอยู่ในโหมดเริ่มต้น (พร้อมใช้งานทันที)
- หากข้อมูลเข้าสู่ระบบของอุปกรณ์ใช้ไม่ได้อีกต่อไป (เนื่องจากคําตอบมาจาก "ข้อมูลเข้าสู่ระบบที่ไม่ถูกต้อง" จากเซิร์ฟเวอร์) จะต้องเปลี่ยนไปใช้โหมดเริ่มต้น (แกะกล่อง)
- การรีเซ็ตเป็นค่าเริ่มต้นในเครื่องต้องล้างข้อมูลเข้าสู่ระบบและตั้งค่าเป็นสถานะเริ่มต้น
- ไม่บังคับ: อุปกรณ์อาจให้รายการเมนูเพื่อล้างข้อมูลเข้าสู่ระบบและตั้งค่าเป็นโหมดเริ่มต้น
- อุปกรณ์ที่สนับสนุนการแจ้งเตือน XMPP ต้องมีความสามารถในการใช้คําสั่ง ping กับเซิร์ฟเวอร์ ระยะหมดเวลาคําสั่ง ping ต้องควบคุมได้จากเซิร์ฟเวอร์ผ่าน "local_settings"
- อุปกรณ์อาจใช้คําสั่ง ping กับเซิร์ฟเวอร์อย่างชัดแจ้ง (/duration/printer API สําหรับ GCP นอกเหนือจากคําสั่ง ping ของ XMPP) ไม่เกิน 1 ครั้งต่อวัน (24 ชั่วโมง) เพื่อให้มั่นใจว่าซิงค์กันแล้ว ขอแนะนําให้สุ่มเลือกช่วงเวลาตรวจสอบภายใน 24-32 ชั่วโมง
- ไม่บังคับ: สําหรับอุปกรณ์ Cloud Print เราขอแนะนําให้ใช้ (ปุ่ม) ซึ่งไม่จําเป็นต้องมีวิธีดําเนินการด้วยตนเองเพื่อให้ผู้ใช้เริ่มต้นการตรวจสอบงานพิมพ์ใหม่จากอุปกรณ์ได้ เครื่องพิมพ์บางเครื่อง มีข้อมูลนี้อยู่แล้ว
- ไม่บังคับ เครื่องพิมพ์ระดับองค์กรอาจมีตัวเลือกให้ปิดใช้การค้นพบในเครื่องโดยสิ้นเชิง ในกรณีนี้ อุปกรณ์ต้องอัปเดตการตั้งค่าในเครื่องเหล่านี้ในเซิร์ฟเวอร์ การตั้งค่าใหม่ในเครื่องต้องว่างเปล่า (การตั้งค่า "local_discovery" เป็น "false" ซึ่งหมายความว่าจะเปิดใช้อีกครั้งจากบริการ GCP ได้)
6.1.2 แผนภาพการจดทะเบียนเริ่มต้น
![](https://developers.google.cn/cloud-print/images/privet_image06.png?authuser=4&hl=th)
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]]>lt;api name>" ภายในแท็ก <script><script type="text/javascript" src="http://192.168.1.42:8080/privet/info"></script>หากไม่มีการปกป้อง เว็บไซต์ที่เป็นอันตรายจะเรียกใช้การเรียก API และการเข้าถึงผลการค้นหาได้
เพื่อป้องกันการโจมตีประเภทนี้ การเรียก Privet API ทั้งหมดจะต้องมีส่วนหัว "X-Privet-Token" ในคําขอ "src=lt;api>" แท็กสคริปต์ไม่สามารถเพิ่มส่วนหัว เพื่อป้องกันการโจมตีประเภทนี้ได้อย่างมีประสิทธิภาพ
6.2.2. XSRF
http://en.wikipedia.org/wiki/Cross-site_request_forgeryเว็บไซต์ที่เป็นอันตรายอาจคาดเดาที่อยู่ IP และหมายเลขพอร์ตของอุปกรณ์ที่เข้ากันได้กับ Privet และพยายามเรียกใช้ Privet API โดยใช้ <iframe> แบบฟอร์ม หรือกลไกการโหลดข้ามเว็บไซต์อื่นๆ ผู้โจมตีจะเข้าถึงผลลัพธ์ของคําขอไม่ได้ แต่หากคําขอดําเนินการ (เช่น การพิมพ์) ก็จะเรียกใช้ได้
เราต้องใช้การป้องกันต่อไปนี้เพื่อป้องกันการโจมตีนี้
- เปิด /privet/info API ไว้ที่ XSRF
- /privet/info API ต้องไม่ดําเนินการใดๆ ในอุปกรณ์
- ใช้ /privet/info API เพื่อรับ x-privet-token
- API อื่นๆ ทั้งหมดจะต้องตรวจสอบ x-privet-token ในส่วนหัว "X-Privet-Token" ที่ถูกต้อง
- x-privet-token จะใช้ได้เป็นเวลา 24 ชั่วโมงเท่านั้น
แม้ว่าผู้โจมตีจะเรียกใช้ /privet/info API ได้ แต่อ่าน x-privet-token จากการตอบกลับไม่ได้ ดังนั้นจึงเรียก API อื่นไม่ได้
ขอแนะนําอย่างยิ่งให้สร้างโทเค็น XSRF โดยใช้อัลกอริทึมต่อไปนี้
XSRF_token = base64( SHA1(device_secret + DELIMITER + issue_timecounter) + DELIMITER + issue_timecounter )
องค์ประกอบการสร้างโทเค็น XSRF:
- DELIMITER เป็นอักขระพิเศษ โดยปกติแล้วจะเป็น: ":"
- issue_timemeet เป็นจํานวนวินาทีนับจากเหตุการณ์บางอย่าง (epoch สําหรับการประทับเวลา) หรือเวลาบูตอุปกรณ์ (สําหรับตัวนับ CPU) issue_timemeet เพิ่มขึ้นอย่างต่อเนื่องเมื่ออุปกรณ์เริ่มทํางาน (ดูการยืนยันโทเค็นด้านล่าง)
- SHA1 - ฟังก์ชันแฮชโดยใช้อัลกอริทึม SHA1
- base64 - การเข้ารหัส base64
- device_secret - ข้อมูลลับเฉพาะของอุปกรณ์ ต้องอัปเดตข้อมูลลับของอุปกรณ์ทุกครั้งที่รีสตาร์ท
วิธีที่แนะนําในการสร้างข้อมูลลับของอุปกรณ์
- สร้าง UUID ใหม่ทุกครั้งที่รีสตาร์ท
- สร้างตัวเลขแบบสุ่ม 64 บิตสําหรับทุกการรีสตาร์ท
อุปกรณ์ไม่จําเป็นสําหรับการจัดเก็บโทเค็น XSRF ทั้งหมดที่อุปกรณ์ได้รับมา เมื่ออุปกรณ์จําเป็นต้องยืนยันโทเค็น XSRF เพื่อความถูกต้อง อุปกรณ์ควรถอดรหัสฐาน 64 รับ issue_timemeet จากครึ่งหลัง (ล้างข้อความ) แล้วลองสร้างแฮช SHA1 ของ device_secret +DELIMITER + issue_timemeet โดย issue_timemeet มาจากโทเค็น หาก SHA1 ที่สร้างขึ้นใหม่ตรงกับโทเค็นในโทเค็น อุปกรณ์จะต้องตรวจสอบว่า issue_timemeet อยู่ในระยะเวลาที่ถูกต้องจาก (24 ชั่วโมง) ของตัวนับเวลาปัจจุบันหรือไม่ ซึ่งทําได้โดยใช้ตัวนับเวลาปัจจุบัน (เช่น ตัวนับ CPU) และลบปัญหา_ตัวนับเวลาออกจากนาฬิกา ผลลัพธ์ต้องเป็นจํานวนวินาทีนับตั้งแต่เกิดปัญหาโทเค็น
สําคัญ: วิธีนี้เป็นวิธีที่แนะนําในการป้องกัน XSRF ไคลเอ็นต์ของข้อมูลจําเพาะของ Privet จะไม่พยายามเข้าใจโทเค็น XSRF แต่จะถือเป็นกล่องดํา รูปที่ 6.2.3 แสดงวิธีที่แนะนําในการใช้งานโทเค็น X-Privet และการยืนยันคําขอทั่วไป
6.2.3 การสร้างโทเค็น X-Privet และแผนภาพลําดับการยืนยัน
![](https://developers.google.cn/cloud-print/images/privet_image03.png?authuser=4&hl=th)
6.3 แผนภาพเวิร์กโฟลว์
ส่วนนี้จะแสดงเวิร์กโฟลว์ในกรณีต่างๆ6.3.1 เครื่องพิมพ์นอกกล่องประมวลผล
![](https://developers.google.cn/cloud-print/images/privet_image01.png?authuser=4&hl=th)
6.3.2 เริ่มต้นเครื่องพิมพ์ที่ลงทะเบียน
![](https://developers.google.cn/cloud-print/images/privet_image02.png?authuser=4&hl=th)
6.3.3 เวิร์กโฟลว์การจัดการการแจ้งเตือน XMPP
![](https://developers.google.cn/cloud-print/images/privet_image05.png?authuser=4&hl=th)
6.3.4 ตรวจสอบเวิร์กโฟลว์การตั้งค่าเครื่องพิมพ์
![](https://developers.google.cn/cloud-print/images/privet_image00.png?authuser=4&hl=th)