لن تتوفر الطباعة السحابية من Google اعتبارًا من 31، كانون الأول (ديسمبر) 2020. يُرجى الاطلاع على مقالة الدعم للمساعدة في نقل البيانات.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

Privet

Privet عبارة عن واجهة برمجة تطبيقات اكتشاف الجهاز في السحابة الإلكترونية على الأجهزة التي تستخدمها خدمات السحابة الإلكترونية. ويتم تنظيم هذا المستند في الأقسام التالية:

مقدمة: مقدمة حول Privet
الاكتشاف: آليات الاكتشاف المحلية
الإشعارات: الإشعارات حول الأنشطة التجارية المحلية
واجهة برمجة التطبيقات: واجهات برمجة تطبيقات Privet لأجهزة السحابة الإلكترونية العامة
واجهة برمجة التطبيقات للطابعات: واجهات برمجة التطبيقات الخاصة بالطابعات التي تستخدمها الطابعات
الملحق: المخطَّطات التكميلية

1- مقدمة

تستفيد الأجهزة المتصلة بالسحابة الإلكترونية من العديد من المزايا. ويمكنهم استخدام خدمات الإحالة الناجحة على الإنترنت واستضافة قوائم انتظار الوظائف أثناء عدم اتصال الجهاز بالإنترنت، ويمكن الوصول إليها من أي مكان في العالم. ومع توفّر العديد من أجهزة السحابة الإلكترونية التي يمكن لمستخدم معيّن الوصول إليها، نحتاج إلى توفير طريقة للعثور على أقرب جهاز استنادًا إلى الموقع الجغرافي. والغرض من بروتوكول Privet هو الالتزام بمرونة استخدام أجهزة السحابة الإلكترونية من خلال آلية مناسبة لاكتشافها على المستوى المحلي، بحيث يسهل العثور على الأجهزة في بيئات جديدة.

أهداف هذا البروتوكول هي:

جعل أجهزة السحابة الإلكترونية قابلة للاكتشاف على المستوى المحلي
تسجيل الأجهزة في السحابة الإلكترونية باستخدام خدمة سحابة إلكترونية
ربط الأجهزة المسجَّلة بتمثيل السحابة الإلكترونية
تفعيل الوظائف بلا اتصال بالإنترنت
تبسيط عملية التنفيذ لتتمكّن الأجهزة الصغيرة من استخدامها

يتألف بروتوكول Privet من جزأين رئيسيَّين: الاكتشاف وواجهة برمجة التطبيقات. وتُستخدم "الاكتشاف" للعثور على الجهاز على الشبكة المحلية، كما يتم استخدام واجهة برمجة التطبيقات للحصول على معلومات حول الجهاز وتنفيذ بعض الإجراءات. في هذا المستند، يشير الجهاز إلى جهاز متصل بالسحابة الإلكترونية يستخدم بروتوكول Privet.

2. استكشاف المحتوى

Discovery عبارة عن بروتوكول يستند إلى شبكات متوفّرة بدون ضبط (mDNS + DNS-SD). يجب أن يستخدم الجهاز عناوين IPv4 Link-Local Addressing. يجب أن يتوافق الجهاز مع مواصفات 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. نوع الخدمة

تستخدم أداة "اكتشاف خدمة نظام أسماء النطاقات" التنسيق التالي لأنواع الخدمات: _applicationprotocol._transportprotocol. في حالة بروتوكول Privet، يجب أن يكون نوع الخدمة لـ DNS-SD هو: _privet__tcp

ويمكن للجهاز تنفيذ أنواع أخرى من الخدمات أيضًا. وننصح باستخدام اسم مثيل الخدمة نفسه لجميع أنواع الخدمات التي ينفذها الجهاز. على سبيل المثال، قد تطبِّق الطابعة الخدمات "الطابعة XYZ._privet._tcp" &"الطابعة XYZ._printer._tcp" وسيؤدي ذلك إلى تبسيط عملية الإعداد للمستخدم. ومع ذلك، لن يبحث عملاء Privet إلا عن "_privet__tcp".

بالإضافة إلى نوع الخدمة الرئيسي، يجب أن يُعلن الجهاز عن سجلّات الموجّه(PTR) للأنواع الفرعية المقابلة لها (راجِع مواصفات DNS-SD: "7.1. تعداد المثيلات الانتقائية (الأنواع الفرعية)&quot؛ يجب أن يكون التنسيق على النحو التالي: _<subtype>._sub._privet__tcp

والنوع الفرعي الوحيد المعتمد من الأجهزة هو الطابعة. لذا يجب أن تُعلن جميع الطابعات عن سجلّي الموجّه (PTR):

_privet__tcp.local.
_printer._sub._privet__tcp.local

2.2. سجلّ TXT

تُحدِّد ميزة اكتشاف خدمة نظام أسماء النطاقات الحقول لإضافة معلومات اختيارية عن إحدى الخدمات في سجلات TXT. يتألف سجلّ TXT من أزواج المفتاح/القيمة. يبدأ كل زوج من المفاتيح/القيمة من بايت الطول متبوعًا بما يصل إلى 255 بايت من النص. والمفتاح هو النص الذي يسبق الحرف الأول "=" والقيمة هي النص بعد الحرف الأول "=" حتى النهاية. لا تسمح المواصفات باستخدام أي قيمة في السجلّ، وفي هذه الحالة لن يكون هناك حرف "=" أو أي نص بعد الحرف "=". (اطّلِع على مواصفات DNS-SD: "6.1. قواعد التنسيق العامة لسجلات TXT لنظام أسماء النطاقات &بالنسبة إلى تنسيق سجل TXT لنظام أسماء النطاقات و;6.2. "سجلّ TXT لنظام أسماء النطاقات العادي" حجم السجلّ والمقترَح للطول المقترَح.

يتطلب Privet أن يرسل الجهاز أزواج المفتاح/القيمة التالية في سجلّ TXT. سلاسل المفاتيح/القيمة غير حساسة لحالة الأحرف، على سبيل المثال &"CS=online" و&&;;;;;;== الجهاز&hl=ar;;;;، ولا يمكن أن يتشابه النصان معًا. يجب أن تكون المعلومات في سجلّ TXT متطابقة مع المعلومات التي يمكن الوصول إليها من خلال واجهة برمجة التطبيقات /info API (راجِع 4.1. قسم واجهة برمجة التطبيقات).

وننصحك بإبقاء حجم سجلّ TXT أقل من 512 بايت.

2.2.1. txters

يجب أن يكون إصدار بنية 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

يجب الإعلان عن كل نوع فرعي مدرج باستخدام سجلّ الموجّه المناسب. بالنسبة إلى كل نوع فرعي متوافق للخدمة، يجب أن يكون هناك عنصر واحد مقابل. يجب أن يكون اسم النوع الفرعي للخدمة (<subtype>__sub._privet__tcp) مساويًا لنوع الجهاز هنا.

المعرّف 2.2.6

رقم تعريف الجهاز إذا لم يتم تسجيل الجهاز بعد، يجب أن يكون هذا المفتاح متوفّرًا، ولكن يجب أن تكون القيمة فارغة. مثلاً:

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

2.2.7. cs

تشير إلى حالة الاتصال الحالية للجهاز. ويتم تحديد أربع قيم محتملة في هذه المواصفات.

"online;quot; تشير إلى أنّ الجهاز متصل حاليًا بالسحابة الإلكترونية
"بلا إنترنت" تشير إلى أنّ الجهاز متوفّر على الشبكة المحلية، ولكن لا يمكنه التحدّث إلى الخادم.
"connecting" يشير إلى أنّ الجهاز يجري تسلسل بدء التشغيل وهو غير متصل بالكامل بالإنترنت.
"not-configure" يشير إلى أنّه لم يتمّ ضبط وصول الإنترنت إلى الجهاز بعد. هذه القيمة غير مستخدَمة حاليًا، ولكن قد تكون مفيدة في الإصدارات المستقبلية من المواصفات.

على سبيل المثال:

cs=online
cs=بلا إنترنت
cs=connect

إذا كان الجهاز مُسجّلاً على سحابة إلكترونية، يجب أن يتحقّق عند بدء التشغيل من الاتصال بالخادم لرصد حالة اتصاله (على سبيل المثال، الاتصال بواجهة برمجة تطبيقات السحابة الإلكترونية للحصول على إعدادات الجهاز). وقد يستخدم الجهاز حالة اتصال قناة الإشعارات (مثل XMPP) للإبلاغ عن هذه القيمة. قد تُرسِل الأجهزة غير المسجَّلة عند بدء التشغيل نطاقًا لاكتشاف حالة الاتصال (على سبيل المثال، إشعار www.google.com لأجهزة الطباعة في السحابة الإلكترونية).

3- الإشعارات

عند بدء تشغيل الجهاز أو إيقافه أو تغيير الحالة، يجب أن ينفِّذ الجهاز خطوة الإعلان كما هو موضّح في مواصفات mDNS. ويجب أن تُرسل الإشعار المناسب مرّتين على الأقل متضمّنةً مهلة زمنية لا تقلّ عن ثانية واحدة بينهما.

3.1. التشغيل

عند بدء تشغيل الجهاز، يجب إجراء خطوات الفحص والإعلان عن الخطوات كما هو موضّح في مواصفات mDNS. ويجب إرسال سجلّات SRV وPTR وTXT في هذه الحالة. ننصحك بتجميع جميع السجلّات في استجابة واحدة لنظام أسماء النطاقات، إن أمكن. وإذا لم يكن الأمر كذلك، نقترح استخدام ما يلي: سجلّات SRV وPTR وTXT.

3.2. إيقاف التشغيل

عند إيقاف تشغيل الجهاز، يجب أن يحاول إشعار جميع الأطراف المعنية بشأنه من خلال إرسال "good;e;bybyepackage" مع TTL=0 (كما هو موضّح في مستندات mDNS).

3.3. تعديل

في حال تغيير أي معلومات موضّحة في ملف TXT، يجب أن يرسل الجهاز إشعارًا بالتحديث. يكفي إرسال سجلّ TXT الجديد في هذه الحالة فقط. على سبيل المثال، بعد تسجيل الجهاز، يجب أن يرسل إشعارًا بالتحديث، بما في ذلك معرّف الجهاز الجديد.

4. واجهة برمجة التطبيقات

بعد اكتشاف جهاز سحابة إلكترونية، يتم تفعيل تواصل العميل مع الجهاز مباشرةً على الشبكة المحلية. تستند جميع واجهات برمجة التطبيقات إلى HTTP 1.1. تعتمد تنسيقات البيانات على JSON. ويمكن أن تكون طلبات البيانات من واجهة برمجة التطبيقات هي طلبات 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 error" (invalid_x_privet_token، اطلع على قسم الأخطاء) للحصول على التفاصيل. والاستثناء الوحيد هو واجهة برمجة تطبيقات /info. للاطّلاع على المزيد من المعلومات حول سبب إتمام هذا الإجراء وكيفية إنشاء الرموز المميّزة، يُرجى مراجعة الملحق أ: XSSI وXSRF والهجمات المتعلّقة به.

إذا لم تكن واجهة برمجة التطبيقات المطلوبة متوفرة أو غير متوافقة، يجب أن يعرض الجهاز الخطأ HTTP 404.

4.1. مدى توفّر واجهة برمجة التطبيقات

قبل أن تظهر أي واجهة برمجة تطبيقات (بما في ذلك واجهة برمجة التطبيقات /info API)، على الجهاز التواصل مع الخادم للتحقّق من الإعدادات المحلية. يجب الاحتفاظ بالإعدادات المحلية بين عمليات إعادة التشغيل. وإذا لم يكن الخادم متاحًا، يجب استخدام آخر إعدادات محلية معروفة. إذا لم يتم تسجيل الجهاز بعد، من المفترض أن يتّبع الإعدادات التلقائية.

يجب أن تتبع أجهزة الطباعة السحابية الخطوات أدناه لتسجيل الإعدادات المحلية وتلقيها وتحديثها.

4.1.1. تسجيل

عند تسجيل الجهاز، يجب تحديد المعلمة "local;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"، يجب إيقاف جميع واجهات برمجة التطبيقات المحلية (بما في ذلك /info) واكتشاف نظام أسماء النطاقات (DNS). حسب الإعدادات التلقائية، يجب أن تجتاز الأجهزة التي تم تسجيلها حديثًا &"true".
access_token_enabled	قيمة منطقية (اختيارية)	تشير هذه الخاصية إلى ما إذا كان يجب عرض واجهة برمجة التطبيقات /accesstoken API على الشبكة المحلية. بشكل تلقائي، يجب أن تكون "true;true".
الطابعة/local_printing_enabled	قيمة منطقية (اختيارية)	تشير هذه الخاصية إلى ما إذا كانت وظيفة الطباعة المحلية (/printer/createjob و/printer/submitdoc و/printer/jobstate) ستظهر على الشبكة المحلية. بشكل تلقائي، يجب أن تكون "true;true".
الطابعة/conversion_printing_enabled	قيمة منطقية (اختيارية)	يشير إلى ما إذا كانت الطباعة المحلية قد ترسل مهام إلى الخادم لإجراء الإحالة الناجحة. لا يكون ذلك مفيدًا إلا عند تفعيل الطباعة المحلية.
xmpp_timeout_value	int (اختياري)	تشير هذه العلامة إلى عدد الثواني بين إشعارات القناة XMPP. يجب أن تكون المدة التلقائية 300 (5 دقائق) أو أكثر تلقائيًا.

ملاحظة مُهمّة: يشير عدم توفّر أي قيمة اختيارية إلى أنّ الوظيفة المقابلة غير متوافقة مع الجهاز تمامًا.

4.1.2. التشغيل

وعند بدء تشغيل الجهاز، عليه التواصل مع الخادم للتحقّق من واجهات برمجة التطبيقات المتاحة للعرض في الشبكة المحلية. بالنسبة إلى الطابعات المتصلة بخدمة "الطباعة السحابية"، يجب طلب ما يلي:

/cloudprint/printer?printerid=<printer_id>

أو

/cloudprint/list

ننصحك باستخدام /cloudprint/printer بدلاً من /gc/list، ولكن سيعمل كلاهما.

تعرض واجهة برمجة التطبيقات هذه معلمات الجهاز الحالية، بما في ذلك إعدادات واجهة برمجة التطبيقات المحلية. سيكون الردّ من الخادم بالتنسيق التالي:

"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
         }
}

&&;;;; القوِيم الحالية&يشير إلى كائن ساري المفعول في الوقت الحالي.

"Pending"الكائن يشير إلى الإعدادات التي يجب تطبيقها على الجهاز (قد لا يكون هذا العنصر متوفّرًا).

بعد أن يرى الجهاز إعدادات ""Pending";، يجب تحديث حالته (انظر أدناه).

4.1.3. تعديل

في حال كان هناك حاجة إلى تعديل الإعدادات، سيتم إرسال إشعار XMPP إلى الجهاز. سيكون الإشعار بالتنسيق التالي:

<device_id>/update_settings

عند تلقّي مثل هذا الإشعار، يجب أن يطلب الجهاز الخادم للحصول على أحدث الإعدادات. يجب استخدام أجهزة الطباعة السحابية:

/cloudprint/printer?printerid=<printer_id>

بعد أن يرى الجهاز قسم "Pending"" كنتيجة لواجهة برمجة التطبيقات /gclid/printer (عند بدء التشغيل أو بسبب الإشعار)، يجب أن يعدّل حالته الداخلية لكي يتذكّر الإعدادات الجديدة. يجب أن يطلب ذلك من واجهة برمجة تطبيقات الخادم لتأكيد الإعدادات الجديدة. بالنسبة إلى الطابعات في السحابة الإلكترونية، يجب أن يستدعي الجهاز واجهة برمجة التطبيقات /GCP/update ويستخدم المعلّمة "local_settings"كما هو الحال أثناء التسجيل.

عند إعادة الاتصال بقناة XMPP، يجب أن يستدعي الجهاز واجهة برمجة التطبيقات /cloudprint/printer لمعرفة ما إذا تم تغيير الإعدادات المحلية منذ آخر مرة.

4.1.3.1. الإعدادات المحلية معلَّقة

"local_settings" المعلَمة التي يستخدمها الجهاز لواجهة برمجة تطبيقات الخادم يجب ألا تحتوي أبدًا على القسم "Pending".

4.1.3.2. الإعدادات المحلية الحالية

يمكن للجهاز فقط تغيير قسم "current";"local;settings_local". سيغيّر كل مستخدم آخر القسم "&;;;;;;;;;;7; Play&; في أخبار Google" وينتظر الانتظار حتى يتم نشر التغييرات إلى القسم "&&;;;;current" حسب الجهاز.

4. 1.4 بلا إنترنت

عند تعذُّر الاتصال بالخادم أثناء بدء التشغيل، يجب أن يستخدم الجهاز آخر الإعدادات المحلية المعروفة بعد تلقّي الإشعار.

4. 1.5 حذف الجهاز من الخدمة

في حال تم حذف الجهاز من الخدمة (على سبيل المثال، Google Cloud Platform)، سيتم إرسال إشعار XMPP إلى الجهاز. سيكون الإشعار بالتنسيق التالي:

<device_id>/delete

عند تلقّي مثل هذا الإشعار، يجب أن ينتقل الجهاز إلى الخادم للتحقّق من حالته. يجب أن تستخدم أجهزة الطباعة السحابية:

/cloudprint/printer?printerid=<printer_id>

يجب أن يتلقّى الجهاز إجابة HTTP ناجحة تتضمّن ناجحًا=خطأ ولا يتضمّن وصفًا للجهاز أو الطابعة. ويعني ذلك أنّه قد تمت إزالة الجهاز من الخادم، وعلى الجهاز محو بيانات اعتماده والانتقال إلى وضع الإعدادات التلقائية.

عندما يتلقّى الجهاز ردًّا يشير إلى أنه تم حذفه بسبب واجهة برمجة التطبيقات /GCP/printer (بدء التشغيل، إشعار تعديل الإعدادات، إشعار يومي)، يجب أن يحذف بيانات اعتماده وينتقل إلى الوضع التلقائي.

4.2. واجهة برمجة التطبيقات /privet/info

واجهة برمجة التطبيقات للمعلومات هي MANDATORY ويجب تنفيذها على كل جهاز. إنه طلب HTTP GET لـ &pr;/privet/info" url: GET /privet/info HTTP/1.1

تعرض واجهة برمجة التطبيقات Info المعلومات الأساسية عن الجهاز والوظائف المتوافقة معه. ويجب ألا تغيّر واجهة برمجة التطبيقات هذه حالة الجهاز أو تنفّذ أي إجراء لأنّه معرّض لهجمات XSRF. هذه هي واجهة برمجة التطبيقات الوحيدة المسموح لها بالحصول على رأس فارغ "X-Privet-Token". وعلى العملاء استدعاء واجهة برمجة التطبيقات /privet/info API باستخدام "X-Privet-Token"، وضبط عنوان الرأس على X-Privet-Token: ""

يجب أن تعرض واجهة برمجة التطبيقات للمعلومات بيانات متوافقة مع البيانات المتاحة في سجلّ TXT أثناء الاكتشاف.

4. 2.1 إدخال

لا تتضمن واجهة برمجة تطبيقات /privet/info أي معلمات إدخال.

4.2.2. تذكرة ذهاب وعودة

تعرض واجهة برمجة التطبيقات /privet/info المعلومات الأساسية حول الجهاز والوظائف المتاحة له.

يشير عمود TXT إلى الحقل المقابل في سجل TXT لنظام أسماء النطاقات (DNS).

اسم القيمة	نوع القيمة	الوصف	نص
إصدار	سلسلة	أحدث إصدار (major.minor) من واجهة برمجة التطبيقات متوافق، حاليًا 1.0
اسم	سلسلة	اسم الجهاز القابل للقراءة للجهاز	تاي
الوصف	سلسلة	(اختياري) وصف الجهاز. يجب أن يتمكّن المستخدم من تغيير ذلك.	ملاحظة
عنوان url	سلسلة	عنوان URL للخادم الذي يتواصل معه هذا الجهاز. ويجب أن يتضمّن عنوان URL مواصفات البروتوكول، مثل: https://www.google.com/cloudprint.	عنوان url
كتابة	قائمة السلاسل	قائمة بأنواع الأجهزة المتوافقة	كتابة
id	سلسلة	يكون رقم تعريف الجهاز فارغًا إذا لم يتم تسجيل الجهاز بعد.	id
_حالة_الجهاز	سلسلة	تشير حالة الجهاز إلى أنّ الجهاز غير نشِط لفترة قصيرة يعني أنّ الجهاز جاهز قيد المعالجة، ما يعني أنّ الجهاز مشغول ويمكن أن تكون الوظائف محدودة لبعض الوقت. توقّف يعني أنّ الجهاز لا يعمل وأنّ المستخدم بحاجة إلى التدخل.
اتصال_حالة	سلسلة	حالة الاتصال بالخادم (base_url) على الإنترنت - الاتصال متاح بلا اتصال بالإنترنت - ما مِن اتصال جارٍ الاتصال - إجراء خطوات بدء التشغيل لم يتم الضبط - لم يتم ضبط الاتصال بعد قد يُبلِغ جهاز مسجَّل عن حالة الاتصال وفقًا لحالة قناة الإشعار (مثل حالة اتصال XMPP).	cs
الشركة المصنّعة	سلسلة	اسم الشركة المصنّعة للجهاز
نموذج	سلسلة	طراز الجهاز
الرقم_الرقمي	سلسلة	المعرّف الفريد للجهاز. من هذه المواصفات يجب أن يكون UUID. (مواصفات Google Cloud Platform 1.1) (اختيارية) ننصحك بشدة باستخدام رقم تعريف الرقم التسلسلي نفسه في كل مكان، حتى يتمكّن العملاء المختلفون من التعرّف على الجهاز نفسه. على سبيل المثال، يمكن أن تستخدم الطابعات التي تستخدِم بروتوكول الطباعة على الإنترنت (IPP) رقم تعريف الرقم التسلسلي هذا في الحقل "print;printer-device-id".
البرامج الثابتة	سلسلة	إصدار البرامج الثابتة للجهاز
مدة التشغيل	int	عدد الثواني من تشغيل الجهاز.
إعداد_عنوان URL	سلسلة	(اختياري) عنوان URL للصفحة (بما في ذلك البروتوكول) الذي يتضمّن تعليمات الإعداد
support_url	سلسلة	(اختياري) عنوان URL (بما في ذلك البروتوكول) للصفحة التي تتضمّن معلومات ومعلومات شائعة
update_url	سلسلة	(اختياري) عنوان URL (بما في ذلك البروتوكول) للصفحة التي تحتوي على تعليمات تحديث البرامج الثابتة
الرمز المميز في x-privet	سلسلة	قيمة العنوان X-Privet-Token الذي يجب تمريره إلى جميع واجهات برمجة التطبيقات لمنع هجمات XSSI وXSRF. يُرجى الاطّلاع على 6.1 لمزيد من التفاصيل.
واجهة برمجة التطبيقات	وصف واجهات برمجة التطبيقات	قائمة بواجهات برمجة التطبيقات المتوافقة (الموضّحة أدناه)
حالة_دلالية	JSON	(اختياري) الحالة الدلالية للجهاز بتنسيق CloudDeviceState.

api - هي قائمة JSON تحتوي على قائمة بواجهات برمجة التطبيقات المتاحة على الشبكة المحلية. ملاحظة: قد لا تتوفّر بعض واجهات برمجة التطبيقات في الوقت نفسه على الشبكة المحلية. على سبيل المثال، يجب أن يتوافق الجهاز المتصل حديثًا مع /register api فقط:

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

عند اكتمال تسجيل الجهاز، يجب أن يتوقف الجهاز عن دعم /register API. يجب أن يراجع الجهاز أيضًا الخدمة لتوفير واجهات برمجة التطبيقات التي يمكن عرضها على الشبكة المحلية. على سبيل المثال:

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

وتتوفّر واجهات برمجة التطبيقات التالية في الوقت الحالي:

/privet/register - واجهة برمجة التطبيقات لتسجيل الجهاز عبر الشبكة المحلية. (راجِع واجهة برمجة التطبيقات /privet/register لمعرفة التفاصيل). يجب أن تكون واجهة برمجة التطبيقات هذه مخفية بعد تسجيل الجهاز بنجاح في السحابة الإلكترونية.
/privet/accesstoken - واجهة برمجة التطبيقات لطلب رمز الدخول من الجهاز (راجِع /privet/accesstoken API لمعرفة التفاصيل).
/privet/capability - واجهة برمجة التطبيقات لاسترداد إمكانات الجهاز (راجِع /privet/capability واجهة برمجة التطبيقات للحصول على التفاصيل).
/privet/printer/* - واجهة برمجة التطبيقات الخاصة بنوع الجهاز "الطابعة&quot؛ ويمكنك الاطّلاع على واجهات برمجة التطبيقات المتعلقة بالطابعات لمعرفة التفاصيل.

إليك مثال على استجابة /privet/info. (يُرجى ملاحظة عدم توفّر واجهة برمجة التطبيقات /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 الأخطاء

يجب أن تعرض /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 صالح. على الجهاز تنفيذ واجهة برمجة التطبيقات هذه على "/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 للسماح لمستخدم من الشبكة المحلية بالمطالبة بالطابعة.
بعد اكتمال التسجيل، يجب أن يتوقف الجهاز عن عرض واجهة برمجة التطبيقات /privet/register لمنع مستخدم آخر على الشبكة المحلية من استرداد الجهاز.
قد تختلف طريقة تسجيل الأجهزة لبعض الأجهزة، ويجب ألا تكشف عن واجهة برمجة التطبيقات /privet/register (على سبيل المثال، موصل الطباعة في السحابة الإلكترونية من Chrome).

تتألف عملية التسجيل من 3 خطوات (راجع التسجيل المجهول لخدمة "الطباعة السحابية من Google").

بدء عملية تسجيل مجهولة الهوية.
يبدأ العميل هذه العملية باستدعاء /privet/register API. قد ينتظر الجهاز تأكيد المستخدم في ذلك الوقت.
الحصول على الرمز المميّز للمطالبة

يجري العميل استطلاعًا لمعرفة الوقت الذي يكون فيه الجهاز جاهزًا للمتابعة. عندما يصبح الجهاز جاهزًا، يتم إرسال طلب إلى الخادم لاسترداد الرمز المميز للتسجيل وعنوان URL للتسجيل. يجب إعادة الرمز المميّز وعنوان URL الذي تم استلامه إلى العميل. وخلال هذه الخطوة، إذا كان الجهاز يتلقّى مكالمة أخرى لبدء التسجيل، عليه تنفيذ ما يلي:

إذا كان هذا المستخدم هو نفسه الذي بدأ التسجيل، يُرجى حذف جميع البيانات السابقة (إذا توفّرت) وبدء عملية تسجيل جديدة.
إذا كان هذا مستخدمًا مختلفًا، يمكنك عرض خطأ device_مشغول ومهلة 30 ثانية.

إكمال عملية التسجيل.

بعد أن يطلب العميل الجهاز، يجب أن يرسل إشعارًا إلى الجهاز لإكمال التسجيل. بعد اكتمال عملية التسجيل، يجب أن يرسل الجهاز إشعارًا بالتحديث، بما في ذلك رقم تعريف الجهاز الذي تم الحصول عليه حديثًا.

ملاحظة: عندما يعالج الجهاز استدعاء /privet/register API، قد لا تتم معالجة استدعاءات /privet/register API الأخرى في الوقت نفسه. يجب أن يعرض الجهاز رسالة الخطأ "device_مشغول" ومهلة 30 ثانية.

ننصح بشدة بتأكيد المستخدم للتسجيل على الجهاز. إذا تم تنفيذ هذه السياسة، يجب أن ينتظر الجهاز تأكيد المستخدم بعد أن يتلقّى استدعاء /privet/register?action=start API. سيطلب العميل واجهة برمجة التطبيقات /privet/register?action=getClaimToken API لمعرفة موعد اكتمال تأكيد المستخدم وتوفّر الرمز المميّز للمطالبة. إذا ألغى المستخدم التسجيل على الجهاز (مثل الضغط على الزر "إلغاء")، يجب أن يظهر الخطأ user_cancel. إذا لم يؤكّد المستخدم التسجيل خلال إطار زمني معيّن، يجب عرض الخطأ "end_timeout". يمكنك الاطّلاع على القسم التلقائي لمعرفة مزيد من التفاصيل.

4.3.1. إدخال

تتضمن واجهة برمجة التطبيقات /privet/register معلمات الإدخال التالية:

الاسم	القيمة
إجراء	يمكن أن تكون إحدى الخطوات التالية: start - لبدء عملية التسجيل getClaimToken - استرداد الرمز المميّز للمطالبة بالجهاز إلغاء - لإلغاء عملية التسجيل complete - لإكمال عملية التسجيل
المستخدم	البريد الإلكتروني للمستخدم الذي قدّم مطالبة بهذا الجهاز.

يجب أن يتحقق الجهاز من تطابق عنوان البريد الإلكتروني من جميع الإجراءات (البدء، getClaimToken، الإلغاء، اكتمل).

4.3.2. تذكرة ذهاب وعودة

تعرض واجهة برمجة التطبيقات /privet/register البيانات التالية:

اسم القيمة	نوع القيمة	الوصف
إجراء	سلسلة	الإجراء نفسه كما في معلمة الإدخال.
المستخدم	السلسلة (اختياري)	المستخدم نفسه كما في معلمة الإدخال (قد يكون مفقودًا، إذا تم حذفه في الإدخال).
رمز مميّز	السلسلة (اختياري)	الرمز المميّز للتسجيل (إلزامي لـ "getClaimToken"الرد وقد تم حذفه لـ&&;;;;;start"&&;;complete","cancel";).
Claim_url	السلسلة (اختياري)	عنوان URL للتسجيل (إلزامي لـ "getClaimToken"الرد وقد تم حذفه لـ&&;;;;;start","complete";"cancel";). بالنسبة إلى الطابعات في السحابة الإلكترونية، يجب أن تكون هذه الرسالة هي "quot;complete_invite_url"مستلمة من الخادم.
تأكيد_مطالبة_تلقائي	السلسلة (اختياري)	عنوان URL للتسجيل (إلزامي لـ "getClaimToken"الرد وقد تم حذفه لـ&&;;;;;start","complete";"cancel";). بالنسبة إلى الطابعات في السحابة الإلكترونية، يجب أن تكون هذه الرسالة هي "##;auto_invite_url" ويُستلم من الخادم.
معرّف_الجهاز	السلسلة (اختياري)	رقم تعريف الجهاز الجديد (مع حذف الاستجابة "البدء"الإلزامي والإلزامي بالنسبة إلى "complete";).

يجب أن يعرض الجهاز معرّف الجهاز في استجابة واجهة برمجة التطبيقات /privet/info فقط بعد اكتمال التسجيل.

المثال 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 الأخطاء التالية (يُرجى الاطّلاع على قسم الأخطاء للحصول على التفاصيل):

خطأ	الوصف
جهاز_مشغول	الجهاز مشغول ولا يمكنه تنفيذ الإجراء المطلوب. أعِد المحاولة بعد انتهاء المهلة.
في انتظار المراجعة	استجابةً لـ "getClaimToken" يشير هذا الخطأ إلى أنّ الجهاز لا يزال في انتظار تأكيد المستخدم وأنّه يجب إعادة محاولة إرسال الطلب "getClaimToken" بعد انتهاء المهلة.
user_cancel	ألغى المستخدم عملية التسجيل صراحةً من الجهاز.
مهلة_التأكيد	انتهت مهلة تأكيد المستخدم.
action_action غير صالح	تم استدعاء إجراء غير صالح. على سبيل المثال، إذا استدعى العميل action=complete قبل استدعاء action=start وaction=getClaimToken.
معلمات_صالحة غير صالحة	تم تحديد معلمات غير صالحة في الطلب. (يجب تجاهل المعلَمات غير المعروفة بأمان من أجل التوافق في المستقبل). على سبيل المثال، يمكنك عرض هذه القيمة إذا كان البرنامج action=unknown أو user=.
خطأ_ضبط_الجهاز	التاريخ/الوقت (أو بعض الإعدادات الأخرى) غير صحيح على جانب الجهاز. يحتاج المستخدم إلى الانتقال (إلى الموقع الإلكتروني الداخلي للجهاز) وضبط إعدادات الجهاز.
بلا إنترنت	الجهاز غير متّصل بالإنترنت حاليًا ولا يمكنه التحدّث إلى الخادم.
خطأ_الخادم	حدث خطأ في الخادم أثناء عملية التسجيل.
الرمز_x_privet_token غير صالح	الرمز المميز X-Privet غير صالح أو فارغ في الطلب.

يجب أن يتوقف الجهاز عن عرض /privet/register API بعد اكتمال التسجيل بنجاح. إذا لم يعرض الجهاز واجهة برمجة التطبيقات /privet/register، يجب أن يعرض خطأ HTTP 404. ولذلك، إذا كان الجهاز مسجّلاً من قبل، يجب أن يعرض طلب البيانات هذا واجهة برمجة التطبيقات خطأ 404. إذا كان رأس X-Privet-Token غير متوفّر، يجب أن يعرض الجهاز خطأ HTTP 400.

4.4. /privet/accesstoken API

/privet/accesstoken API اختيارية. إنه طلب HTTP GET. يجب أن يتحقّق من واجهة برمجة التطبيقات /privet/accesstoken API بحثًا عن عنوان صالح لـ "X-Privet-Token". يجب على الجهاز تنفيذ واجهة برمجة التطبيقات هذه في "/privet/accesstoken" url:

GET /privet/accesstoken HTTP/1.1

عندما يتلقّى الجهاز استدعاء /accesstoken API، يجب أن يستدعي الخادم لاسترداد رمز الدخول الخاص بالمستخدم المحدّد وإرجاع الرمز المميز إلى العميل. بعد ذلك، يستخدم العميل رمز الدخول للوصول إلى هذا الجهاز من خلال السحابة الإلكترونية.

يجب أن تطلب أجهزة الطباعة السحابية واجهة برمجة التطبيقات التالية:

/cloudprint/proximitytoken

ومرِّر المعلّمة "printerprintltlt;printer_id>" &&;;user"معلمة من واجهة برمجة التطبيقات المحلية. إذا كانت الاستجابة ناجحة، ستحتوي استجابة الخادم على الكائن التالي:

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

يجب أن ترسل أجهزة الطباعة السحابية قيمة الكائن "proximity_token"quot في الاستجابة لاستدعاءات واجهة برمجة التطبيقات /privet/accesstoken المحلية. يمكن الاستفادة أكثر من ذلك (للمستقبل) إذا كان بإمكان الجهاز اجتياز جميع المعلمات (بما في ذلك المعلمات التي لم يتم توضيحها في هذه المواصفات).

4. 4.1 إدخال

تتضمن واجهة برمجة التطبيقات /privet/accesstoken واجهة برمجة التطبيقات للإدخال التالية:

الاسم	القيمة
المستخدم	البريد الإلكتروني للمستخدم الذي كان تنوي استخدام رمز الدخول هذا. قد يكون هذا الطلب فارغًا في الطلب.

4.4.2. تذكرة ذهاب وعودة

تعرض واجهة برمجة التطبيقات /privet/accesstoken واجهة برمجة التطبيقات للبيانات التالية:

اسم القيمة	نوع القيمة	الوصف
رمز مميّز	سلسلة	رمز الدخول الذي يعرضه الخادم
المستخدم	سلسلة	المستخدم نفسه كما في معلمة الإدخال.
تنتهي_فيها	int	عدد الثواني المتبقية حتى تنتهي صلاحية الرمز المميز. تم الاستلام من الخادم وتمريرها في هذه الاستجابة.

مثال:

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

4. 4.3 الأخطاء

قد تؤدي واجهة برمجة التطبيقات /privet/accesstoken إلى عرض الأخطاء التالية (يُرجى الاطّلاع على قسم الأخطاء للحصول على التفاصيل):

خطأ	الوصف
بلا إنترنت	الجهاز غير متّصل بالإنترنت حاليًا ولا يمكنه التحدّث إلى الخادم.
الدخول_مرفوض	الحقوق غير كافية. تم رفض الوصول. من المفترض أن يعرض الجهاز هذا الخطأ عندما رفض الخادم الطلب بشكل صريح.
معلمات_صالحة غير صالحة	تم تحديد معلمات غير صالحة في الطلب. (يجب تجاهل المعلَمات غير المعروفة بأمان من أجل التوافق في المستقبل). على سبيل المثال، إذا كان العميل يُسمى /accesstoken?user= أو /accesstoken.
خطأ_الخادم	خطأ في الخادم.
الرمز_x_privet_token غير صالح	الرمز المميز X-Privet غير صالح أو فارغ في الطلب.

إذا لم يعرض الجهاز واجهة برمجة التطبيقات /privet/accesstoken API، يجب أن يعرض خطأ HTTP 404. إذا كان رأس X-Privet-Token غير متوفّر، يجب أن يعرض الجهاز خطأ HTTP 400.

4.5. واجهة برمجة التطبيقات /privet/capability

/privet/capability API اختياري. إنه طلب HTTP GET. يجب أن يتحقّق من واجهة برمجة التطبيقات /privet/capability من العنوان "X-Privet-Token" صالح. يجب على الجهاز تنفيذ واجهة برمجة التطبيقات هذه في "/privet/capability" url:

GET /privet/capabilities HTTP/1.1

عندما يتلقّى الجهاز استدعاء /capability API، إذا كان الجهاز قادرًا على ذلك، يجب أن يتصل بالخادم للحصول على الإمكانيات المحدّثة. على سبيل المثال، إذا كانت الطابعة تتيح نشر مهمة طباعة (مُستلَمة محليًا) من خلال خدمة "الطباعة السحابية"، يجب أن تعرِض الطابعة إمكانات تُعيدها خدمة "الطباعة السحابية". في هذه الحالة، قد تغيّر الطباعة في السحابة الإلكترونية إمكانات الطابعة الأصلية عن طريق إضافة ميزات جديدة قد تنفّذها قبل إرسال المهمة إلى الطابعة. والحالة الأكثر شيوعًا هي قائمة بأنواع المستندات المتوافقة. وإذا كانت الطابعة غير متصلة بالإنترنت، من المفترض أن تعرض أنواع المستندات التي تتوافق معها. ومع ذلك، إذا كانت الطابعة متصلة بالإنترنت ومسجّلة باستخدام الطباعة في السحابة الإلكترونية، يجب عرضها "*/*"اعتبارًا من الأنواع المتوافقة. ستُجري خدمة "الطباعة السحابية" الإحالة الناجحة اللازمة في هذه الحالة. للطباعة بلا اتصال بالإنترنت، يجب أن تتوافق الطابعة على الأقل مع التنسيق "p;g/image/pwg-raster" .

4.5.1. إدخال

تتضمّن واجهة برمجة التطبيقات /privet/capability إجراءات الإدخال التالية:

الاسم	القيمة
بلا إنترنت	(اختياري) لا يمكن أن تكون إلا "التشغيل;بلا إنترنت=1". في هذه الحالة، يجب أن يعرض الجهاز إمكانيات الاستخدام بلا اتصال بالإنترنت (إذا كانت مختلفة عن الإمكانيات "Online").

4.5.2. تذكرة ذهاب وعودة

تعرض واجهة برمجة التطبيقات /privet/capability إمكانيات الجهاز بتنسيق 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 الأخطاء التالية (يُرجى الاطّلاع على قسم الأخطاء للحصول على التفاصيل):

خطأ	الوصف
الرمز_x_privet_token غير صالح	الرمز المميز X-Privet غير صالح أو فارغ في الطلب.

إذا لم يعرض الجهاز واجهة برمجة التطبيقات /privet/capability، يجب أن يعرض رسالة الخطأ HTTP 404. إذا كان عنوان X-Privet-Token مفقودًا، يجب أن يعرض الجهاز خطأ HTTP 400.

4.6. الأخطاء

يتم عرض الأخطاء من واجهات برمجة التطبيقات أعلاه بالتنسيق التالي:

اسم القيمة	نوع القيمة	الوصف
خطأ	سلسلة	نوع الخطأ (محدّد لكل واجهة برمجة تطبيقات)
الوصف	السلسلة (اختياري)	وصف خطأ يمكن للمستخدمين قراءته.
واجهة برمجة تطبيقات الخادم	السلسلة (اختياري)	في حال حدوث خطأ في الخادم، يحتوي هذا الحقل على واجهة برمجة تطبيقات الخادم التي تعذّر تنفيذها.
رمز_الخادم	int (اختياري)	في حال حدوث خطأ في الخادم، يحتوي هذا الحقل على رمز الخطأ الذي عرضه الخادم.
رمز_الخادم_http_code	int (اختياري)	في حال حدوث خطأ في خادم HTTP، يحتوي هذا الحقل على خادم رموز خطأ HTTP الذي تم عرضه.
انتهت المهلة	int (اختياري)	عدد الثواني التي يجب أن ينتظرها العميل قبل إعادة المحاولة (للأخطاء التي يمكن استردادها فقط) يجب أن يحدد البرنامج المهلة الفعلية بشكل عشوائي من هذه القيمة إلى قيمة تزيد عن 20%.

يجب أن تعرض جميع واجهات برمجة التطبيقات خطأ 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. واجهة برمجة تطبيقات الطابعة

أحد أنواع الأجهزة المتوافقة مع هذا البروتوكول هو نوع الطابعة. وقد تستخدم الأجهزة المتوافقة مع هذا النوع بعض الوظائف المخصّصة للطابعات. في العادة، تتم الطباعة إلى الطابعات المجهّزة للاستخدام عبر السحابة الإلكترونية من خلال خادم طباعة في السحابة الإلكترونية:

في بعض الحالات، قد يحتاج العميل إلى إرسال مستند محليًا. وقد يكون هذا مطلوبًا عندما لا يكون لدى العميل معرّف Google أو عندما يتعذّر عليه التحدّث إلى خادم "الطباعة السحابية من Google". وفي هذه الحالة، سيتم إرسال مهمة الطباعة محليًا إلى الطابعة. وبالتالي، ستستخدم الطابعة خدمة الطباعة في السحابة الإلكترونية لوضع المهام في قائمة الانتظار وتحويلها. ستعيد الطابعة نشر المهمة التي تم إرسالها محليًا إلى خدمة "الطباعة السحابية" ثم تطلبها، لأنها قد تم إرسالها من خلال السحابة الإلكترونية. وستوفّر هذه العملية تجربة مستخدم مرنة من حيث الخدمة (الإحالة الناجحة) وإدارة مهام الطباعة/التتبُّع.

بما أن خدمة "الطباعة في السحابة الإلكترونية" تنفذ الإحالات الناجحة، يجب أن تُعلن الطابعة عن دعمها بجميع تنسيقات الإدخال ("*/*") ضمن قائمة أنواع المحتوى المتوافقة:

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

وفي بعض الحالات، يكون الحل الذي نقدّمه بلا إنترنت مطلوبًا. ونظرًا لأن الطابعات تتوافق مع عدد محدود من تنسيقات الإدخال، سيحتاج البرنامج إلى تحويل المستندات إلى بعض تنسيقات الطابعات المتوافقة محليًا.

تتطلب هذه المواصفات كل الطابعات المتوافقة مع تنسيق PWG Raster ("image;pwg-raster") على الأقل لحافظة الطباعة بلا اتصال بالإنترنت. قد تكون الطابعة متوافقة مع تنسيقات أخرى (على سبيل المثال، JPEG) وإذا كان البرنامج يتيح ذلك، يمكنها أن ترسل المستندات بتنسيق معيّن. يجب أن تكشف الطابعة عن الأنواع المتوافقة من خلال /capability API، على سبيل المثال:

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

هناك طريقتان يمكن للعميل بدء الطباعة من خلال الشبكة المحلية.

الطباعة البسيطة - يرسل العميل المستند عبر الشبكة المحلية إلى /submitdoc API (بدون تحديد المعلمة task_id). ستتم طباعة المستند الذي تم إرساله باستخدام إعدادات طلب الطباعة التلقائية ولا يلزم استخدام حالات مهام الطباعة. وإذا كانت الطابعة متوافقة مع هذا النوع من الطباعة فقط، يجب أن تُعلِن فقط عن واجهة برمجة التطبيقات /submitdoc API في استجابة واجهة برمجة التطبيقات /privet/info.

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

الطباعة المتقدمة: على العميل أولاً إنشاء مهمة طباعة على الطابعة من خلال استدعاء واجهة برمجة التطبيقات /privet/printer/createjob مع طلب مهمة CJT صالحة في الطلب. يجب أن تخزّن الطابعة تذكرة الطباعة في الذاكرة وتعرض معرّف_للمهمة على العميل. بعد ذلك، سيتّصل العميل بـ /printer/submitdoc API ويحدّد job_id الذي تم استلامه سابقًا. وستبدأ الطابعة في ذلك الوقت. سيجري العميل استطلاعًا للطابعة لمعرفة حالة مهمة الطباعة من خلال استدعاء واجهة برمجة التطبيقات /privet/printer/jobstate.

في بيئة متعدّدة العملاء، ليس هناك ما يضمن طريقة استدعاء واجهة برمجة التطبيقات هذه. من الممكن أن يستدعي عميل واحد /createjob بين استدعاءات /createjob->/submitdoc عميل آخر. للتخلّص من حالات الإغلاق التام وتحسين سهولة الاستخدام، ننصحك بوضع قائمة انتظار صغيرة لمهام الطباعة المعلّقة على الطابعة (3 إلى 5 على الأقل):

/createjob هو أول مكان متاح في قائمة الانتظار.
تكون مدة الوظيفة (في قائمة الانتظار) 5 دقائق على الأقل.
وفي حال الاستعانة بجميع النقاط المتوفّرة في قائمة الانتظار، ستتم إزالة أقدم وظيفة غير مطبوعة وستتم إضافة مهمة جديدة إليها.
إذا كانت هناك مهمة طباعة حاليًا على الجهاز (الطباعة البسيطة أو المتقدّمة)، من المفترض أن تعرض /submitdoc حالة "مشغول" وتقترح مهلة لإعادة محاولة مهمة الطباعة هذه.
إذا كان /submitdoc يشير إلى مهمة تمت إزالتها من قائمة الانتظار (بسبب الاستبدال أو المهلة)، يجب أن تعرض الطابعة الخطأ invalid_print_job وسيعيد البرنامج محاولة تنفيذ العملية من الخطوة /createjob. يجب أن ينتظر البرنامج مدة مهلة عشوائية تصل إلى 5 ثوانٍ قبل إعادة المحاولة.

إذا كانت قيود الذاكرة تمنع تخزين عدة مهام معلّقة على الجهاز، من الممكن أن تكون هناك قائمة انتظار تضمّ مهمة طباعة واحدة. ويجب أن يتبع البروتوكول نفسه كما هو موضح أعلاه. بعد اكتمال مهمة أو تعذُّر تنفيذها، يجب أن تخزّن الطابعة معلومات عن حالة المهمة لمدة 5 دقائق على الأقل. يجب ألا يقل حجم قائمة الانتظار لتخزين حالات الوظائف المكتملة عن 10. وإذا كان هناك المزيد من حالات الوظائف التي تحتاج إلى تخزينها، قد تتم إزالة الحالة الأقدم من قائمة الانتظار قبل انقضاء المهلة التي تبلغ 5 دقائق.

ملاحظة: في الوقت الحالي، سيُجري العملاء استطلاعًا لمعرفة حالة الوظيفة. في المستقبل، قد نطلب من الطابعة إرسال إشعار نظام أسماء النطاقات TXT عند تغيير أي حالة لمهمة طباعة.

5.1. /privet/printer/createjob API

/privet/printer/createjob API هو اختياري (راجِع الطباعة البسيطة أعلاه). إنه طلب HTTP POST. يجب أن يتحقق /privet/printer/createjob API من رأس صفحة "X-Privet-Token" صالح. يجب على الجهاز تنفيذ واجهة برمجة التطبيقات هذه في "/privet/printer/createjob" url:

POST /privet/printer/createjob HTTP/1.1

عند تلقّي استدعاء /privet/printer/createjob API، يجب إنشاء رقم تعريف جديد لمهمة الطباعة على الطابعة وتخزين تذكرة الطباعة التي تم استلامها بتنسيق CJT وإرجاع معرّف مهمة الطباعة إلى العميل مرة أخرى.

5.1.1. إدخال

لا تتضمّن واجهة برمجة التطبيقات /privet/printer/createjob معلَمات إدخال في عنوان URL. يجب أن يحتوي نص الطلب على بيانات تذكرة مهمة الطباعة بتنسيق CJT.

5.1.2. تذكرة ذهاب وعودة

تعرض واجهة برمجة التطبيقات /privet/printer/createjob البيانات التالية:

اسم القيمة	نوع القيمة	الوصف
معرّف_الوظيفة	سلسلة	معرّف مهمة الطباعة التي تم إنشاؤها حديثًا.
تنتهي_فيها	int	عدد الثواني التي تستغرقها مهمة الطباعة هذه.

مثال:

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

5.1.3. الأخطاء

قد تُظهر واجهة برمجة التطبيقات /privet/printer/createjob الأخطاء التالية (يُرجى الاطلاع على قسم الأخطاء للحصول على التفاصيل):

خطأ	الوصف
تذكرة_غير صالحة	التذكرة المطبوعة التي تم إرسالها غير صالحة.
الطابعة_مشغولة	الطابعة مشغولة ولا يمكنها معالجة /createjob حاليًا. أعِد المحاولة بعد انتهاء المهلة.
خطأ_الطابعة	الطابعة في حالة خطأ وتتطلب تفاعل المستخدم لإصلاحها. يجب أن يتضمّن الوصف شرحًا أكثر تفصيلاً (مثل "Paper jam in Tray 1").
الرمز_x_privet_token غير صالح	الرمز المميز X-Privet غير صالح أو فارغ في الطلب.

إذا لم يكن الجهاز يعرض /privet/printer/createjob، يجب أن يعرض خطأ HTTP 404. في حال عدم توفّر عنوان X-Privet-Token، يجب أن يعرض الجهاز خطأ HTTP 400.

5.2. واجهة برمجة التطبيقات /privet/printer/submitdoc

/privet/printer/submitdoc API مطلوب لتنفيذ الطباعة من خلال شبكة محلية (بلا إنترنت أو إعادة النشر إلى "الطباعة السحابية من Google"). إنه طلب HTTP POST. يجب أن يتحقّق من واجهة برمجة التطبيقات /privet/printer/submitdoc واجهة برمجة التطبيقات الخاصة بالعنوان "X-Privet-Token" صالح. يجب على الجهاز تنفيذ واجهة برمجة التطبيقات هذه في "/privet/printer/submitdoc" url:

POST /privet/printer/submitdoc HTTP/1.1

عند تلقّي استدعاء /privet/printer/submitdoc API، يجب أن تبدأ الطابعة في الطباعة. إذا تعذّر بدء الطباعة، يجب أن يعرض الخطأ الطابعة مشغول ومهلة المهلة المقترحة لينتظرها العميل قبل إعادة المحاولة.

إذا تعذّر على الطابعة الاحتفاظ بجميع البيانات في المخزن المؤقت الداخلي، يجب أن تستخدم آليات TCP لإبطاء عملية نقل البيانات حتى تتم طباعة جزء من المستند، ما يجعل جزءًا من المخزن المؤقت متاحًا مرة أخرى. (على سبيل المثال، قد تضبط الطابعة حجم النافذة=0 على طبقات بروتوكول TCP، ما سينتظر وصول العميل.)

قد يستغرق إرسال المستند إلى الطابعة وقتًا طويلاً. ويجب أن يتمكّن العميل من التحقّق من حالة الطابعة والمَهمّة (الطباعة المتقدّمة) أثناء تقدّم الطباعة. لتنفيذ ذلك، يجب أن تسمح الطابعة للعميل باستدعاء واجهات برمجة التطبيقات /privet/info و/privet/printer/jobstate أثناء معالجة طلبات بيانات من واجهة برمجة التطبيقات /privet/printer/submitdoc. ننصح جميع العملاء ببدء سلسلة محادثات جديدة لتنفيذ طلب البيانات من واجهة برمجة التطبيقات /privet/printer/submitdoc، بحيث يمكن لسلسلة المحادثات الرئيسية استخدام واجهات برمجة التطبيقات /privet/info و /privet/printer/jobstate للتحقّق من حالات الطابعات والوظائف.

ملاحظة: عند إكمال مهمة الطباعة المحلية أو إجهاضها، ننصح بشدة (وسيكون مطلوبًا في إصدار مستقبلي من هذه المواصفات) للإبلاغ عن الحالة النهائية للوظيفة إلى واجهة /cloudprint/submit لأغراض المحاسبة وتجربة المستخدم. تكون المعلّمات "&&;;printerid",&&;;title","contentType" &"final_semantic_state" (بالتنسيق PrintJobState) مطلوبة والمَعلمات "tag&tag; (معلّمة مكررة) و";"ticket" (تذكرة الوظيفة بتنسيق CloudJobTicket). تجدر الإشارة إلى أنّ أمر إطلاق JoBState المُقدّم يجب أن يكون نهائيًا، أي أنّ النوع يجب أن يكون"تم"أو"تم الإلغاء"، ويجب أن يتم تقديم سبب في حال أنه تم الإلغاء (يُرجى مراجعة JobState للحصول على التفاصيل). يُرجى العِلم أيضًا أنّ هذا الاستخدام لواجهة /cloudprint/submit للإبلاغ عن مهام الطباعة المحلية غير مذكور في مواصفاته لأن هذا القسم يهدف إلى وصف الاستخدام الأساسي للواجهة: إرسال مهمة طباعة مع المستند المطلوب طباعته في المعلّمة "content&content".

5.2.1. إدخال

تتضمن واجهة برمجة التطبيقات /privet/printer/submitdoc معلمات الإدخال التالية:

الاسم	القيمة
معرّف_الوظيفة	(اختياري) معرِّف مهمة الطباعة. يمكن حذفه لحافظة الطباعة البسيطة (انظر أعلاه). يجب أن يتطابق مع العنوان الذي تعرضه الطابعة.
user_name	(اختياري) اسم مستخدم يمكن قراءته. وهذا الإجراء ليس نهائيًا، ويجب استخدامه فقط للتعليقات التوضيحية لمهام الطباعة. إذا تمت إعادة نشر المهمة في خدمة "الطباعة السحابية"، يجب إرفاق هذه السلسلة بمهمة "الطباعة السحابية".
Client_name	(اختياري) اسم تطبيق العميل الذي يقدّم هذا الطلب. لأغراض العرض فقط. إذا تمت إعادة نشر المهمة في خدمة "الطباعة السحابية"، يجب إرفاق هذه السلسلة بمهمة "الطباعة السحابية".
المهمة_الاسم	(اختياري) اسم مهمة الطباعة التي سيتم تسجيلها. إذا تمت إعادة نشر المهمة في خدمة الطباعة السحابية، يجب إرفاق هذه السلسلة بمهمة الطباعة السحابية.
بلا إنترنت	(اختياري) لا يمكن أن يكون إلا "Offline=1". وفي هذه الحالة، يجب أن تحاول الطابعة الطباعة بلا اتصال بالإنترنت فقط (لا تتم إعادة النشر إلى خادم الطباعة السحابية).

يجب أن يحتوي نص الطلب على مستند صالح للطباعة. يجب أن يتضمّن "Content-Length"الطول الصحيح للطلب. "Content-Type" يجب ضبط العنوان على مستند MIME ومطابقته مع أحد الأنواع في CDD (ما لم يحدد CDD "*/*").

ننصح العملاء بشدة بتقديم اسم مستخدم صالح (أو عنوان بريد إلكتروني) واسم عميل واسم وظيفي في هذا الطلب. لا يتم استخدام هذه الحقول إلا في واجهات المستخدم لتحسين تجربة المستخدم.

5.2.2. تذكرة ذهاب وعودة

تعرض واجهة برمجة التطبيقات /privet/printer/submitdoc البيانات التالية:

اسم القيمة	نوع القيمة	الوصف
معرّف_الوظيفة	سلسلة	رقم تعريف مهمة الطباعة التي تم إنشاؤها حديثًا (الطباعة البسيطة) أو معرّف_الوظيفة_المحدَّد في الطلب (الطباعة المتقدّمة).
تنتهي_فيها	int	عدد الثواني التي تستغرقها مهمة الطباعة هذه.
الوظيفة_type	سلسلة	نوع محتوى المستند الذي تم إرساله
حجم_الوظيفة	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 الأخطاء التالية (يُرجى الاطلاع على قسم الأخطاء للحصول على التفاصيل):

خطأ	الوصف
وظيفة_طباعة_غير صالحة	يتم تحديد معرف وظيفة غير صالح/منتهية الصلاحية في الطلب. أعِد المحاولة بعد انتهاء المهلة.
نوع_مستند غير صالح	نوع MIME المستند غير متوافق مع الطابعة.
مستند_غير صالح	المستند الذي تم إرساله غير صالح.
Document_to_large	يتجاوز حجم المستند الحد الأقصى المسموح به لحجم المستند.
الطابعة_مشغولة	الطابعة مشغولة ولا يمكنها معالجة المستند حاليًا. أعِد المحاولة بعد انتهاء المهلة.
خطأ_الطابعة	الطابعة في حالة خطأ وتتطلب تفاعل المستخدم لإصلاحها. يجب أن يتضمّن الوصف شرحًا أكثر تفصيلاً (مثل "Paper jam in Tray 1").
معلمات_صالحة غير صالحة	تم تحديد معلمات غير صالحة في الطلب. (يجب تجاهل المعلمات غير المعروفة بأمان من أجل التوافق في المستقبل)
user_cancel	ألغى المستخدم عملية الطباعة صراحةً من الجهاز.
خطأ_الخادم	تعذّر نشر المستند في الطباعة السحابية.
الرمز_x_privet_token غير صالح	الرمز المميز X-Privet غير صالح أو فارغ في الطلب.

إذا كان الجهاز لا يعرض /privet/printer/submitdoc، يجب أن يعرض رسالة الخطأ HTTP 404. إذا كان رأس X-Privet-Token غير متوفّر، يجب أن يعرض الجهاز خطأ HTTP 400.

ملاحظة: قد تتطلب واجهة برمجة التطبيقات /privet/printer/submitdoc معالجة خاصة من جهة الطابعة (بسبب الحمولة الكبيرة المرفقة). في بعض الحالات (يعتمد على تنفيذ خادم HTTP للطابعة والنظام الأساسي)، قد تغلق الطابعة المقبس قبل عرض خطأ HTTP. وبخلاف ذلك، قد تعرض الطابعة خطأ 503 (بدلاً من خطأ Privet). يجب أن تحاول الطابعات قدر الإمكان إرجاع Privet. ومع ذلك، يجب أن يتمكّن كل عميل ينفِّذ مواصفات Privet من معالجة مقبس الإغلاق (بدون خطأ HTTP) وحالات خطأ 503 HTTP في واجهة برمجة التطبيقات /privet/printer/submitdoc. وفي هذه الحالة، على العميل التعامل مع هذا الخطأ على أنه Privet"printer_مشغول" وخلال 15 ثانية على آخر؟ لتجنّب عمليات إعادة المحاولة اللانهائية، يمكن أن يتوقف العميل عن إعادة المحاولة بعد عدد معقول من المحاولات (على سبيل المثال، 3 محاولات).

5.3. /privet/printer/jobstate API

/privet/printer/jobstate API اختياري (اطّلِع على الطباعة البسيطة أعلاه). إنه طلب HTTP GET. يجب أن يتحقق /privet/printer/jobstate API من رأس صفحة "X-Privet-Token" صالح. يجب على الجهاز تنفيذ واجهة برمجة التطبيقات هذه في "/privet/printer/jobstate" url:

GET /privet/printer/jobstate HTTP/1.1

عند تلقّي استدعاء /privet/printer/jobstate API، يجب أن تعرض الطابعة حالة مهمة الطباعة المطلوبة أو الخطأ "invalid_print_job".

5.3.1. إدخال

تتضمن واجهة برمجة التطبيقات /privet/printer/jobstate واجهة برمجة تطبيقات الإدخال التالية:

الاسم	القيمة
معرّف_الوظيفة	مُعرّف مهمة الطباعة لعرض حالة.

5.3.2. تذكرة ذهاب وعودة

تعرض واجهة برمجة التطبيقات /privet/printer/jobstate البيانات التالية:

اسم القيمة	نوع القيمة	الوصف
معرّف_الوظيفة	سلسلة	رقم تعريف مهمة الطباعة الذي تم تخصيص معلومات الحالة له.
ولاية	سلسلة	مسودة - تم إنشاء مهمة الطباعة على الجهاز (لم يتم استلام /privet/printer/submitdoc طلبات حتى الآن). في قائمة الانتظار - تم استلام مهمة الطباعة ووضعها في قائمة الانتظار، ولكن لم تبدأ الطباعة بعد. in_progress - مهمة الطباعة قيد التقدم. تم إيقافها - تم إيقاف مهمة الطباعة مؤقتًا، ولكن يمكن إعادة تشغيلها يدويًا أو تلقائيًا. تم - تم إنجاز مهام الطباعة. تم الإلغاء - تعذَّرت مهمة الطباعة.
الوصف	سلسلة	(اختياري) يمكن للوصف البشري قراءة حالة مهمة الطباعة. يجب أن تتضمّن معلومات إضافية إذا كانت state< موقوفًا أو مُلغى. يقدّم الحقل semantic_state عادةً وصفًا أفضل وفائدة للعميل.
تنتهي_فيها	int	عدد الثواني التي تستغرقها مهمة الطباعة هذه.
الوظيفة_type	سلسلة	(اختياري) نوع محتوى المستند الذي تم إرساله.
حجم_الوظيفة	int 64 بت	(اختياري) حجم بيانات الطباعة بالبايت.
المهمة_الاسم	سلسلة	(اختياري) اسم الوظيفة نفسه كما في الإدخال (إن وجد).
معرّف_الخادم	سلسلة	(اختياري) معرّف المهمة التي تم عرضها من الخادم (إذا تم نشر المهمة في خدمة "الطباعة السحابية من Google"). ويتم حذفها للطباعة بلا اتصال بالإنترنت.
حالة_دلالية	JSON	(اختياري) الحالة الدلالية للوظيفة بتنسيق PrintJobState.

مثال (الطباعة من خلال إعداد التقارير من خلال الطباعة السحابية):

{
        "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 الأخطاء التالية (يُرجى الاطّلاع على قسم الأخطاء للحصول على التفاصيل):

خطأ	الوصف
وظيفة_طباعة_غير صالحة	يتم تحديد معرّف مهمة غير صالح/منتهي الصلاحية في الطلب.
خطأ_الخادم	تعذّر الحصول على حالة مهمة الطباعة (لمهام الطباعة المنشورة في الطباعة السحابية).
الرمز_x_privet_token غير صالح	الرمز المميز X-Privet غير صالح أو فارغ في الطلب.

إذا لم يكن الجهاز يعرض /privet/printer/jobstate، يجب أن يعرض رسالة الخطأ HTTP 404. إذا كان رأس X-Privet-Token غير متوفّر، يجب أن يعرض الجهاز خطأ HTTP 400.

6- Appendix

6.1. السلوك والإعدادات التلقائية

يوضح هذا القسم السلوك التلقائي الذي نتوقعه من جميع الأجهزة المتوافقة مع Privet.

يجب أن تتوافق الأجهزة غير الجاهزة مع واجهات برمجة التطبيقات /privet/info فقط و /privet/register. ويجب إيقاف جميع واجهات برمجة التطبيقات الأخرى (مثل /privet/accesstoken، الطباعة المحلية).
يتطلب التسجيل تفاعلاً فعليًا مع الجهاز.

يجب أن يتخذ المستخدم إجراءً ماديًا على الجهاز (مثل الضغط على زر) لتأكيد إمكانية وصوله إلى الجهاز.
بعد أن يتّخذ المستخدم الإجراء المذكور أعلاه، يجب أن ترسل الطابعة طلب /cloudprint/register. يجب ألا يرسل هذا الطلب إلا بعد اتّخاذ الإجراء (راجِع مخطط التسلسل 1).
إذا كان الجهاز يعالج طلب /privet/register (على سبيل المثال، في انتظار الإجراء أعلاه)، يجب أن يرفض جميع طلبات /privet/register الأخرى. يجب أن يعرض الجهاز الخطأ device_مشغول في هذه الحالة.
يجب أن تنتهي مهلة الجهاز أو أي طلب تسجيل لا يتلقّى الإجراء الفعلي الوارد أعلاه خلال 60 ثانية. يجب أن يعرض الجهاز رسالة التأكيد_timeout في هذه الحالة.
اختياري: يُنصَح به ولكن غير مطلوب، وقد يؤدي ما يلي إلى تحسين تجربة المستخدم:

قد تومض الطابعة ضوءًا أو شاشة الشاشة للإشارة إلى أن المستخدم بحاجة إلى اتخاذ إجراء لتأكيد التسجيل.
قد تشير الطابعة على الشاشة إلى أنّها"تُسجَّل في خدمة"الطباعة السحابية من Google"للمستخدم"abc@def.com": اضغط على"حسنًا"للمتابعة"، حيث تكون abc@def.com هي مَعلمة المستخدم من طلب البيانات من واجهة برمجة التطبيقات /register API. وسيؤدي ذلك إلى توضيح ما يلي للمستخدم:

يجب أن يسجّلوا طلب التسجيل.
ماذا يحدث إذا لم يشغّل الطلب؟

بالإضافة إلى إجراء فعلي للتأكيد من الطابعة (مثل "الضغط على الزر "حسنًا")، يمكن أن تعرض الطابعة أيضًا للمستخدم زرًا لإلغاء الطلب (مثل "اضغط على إلغاء للرفض". يتيح هذا الإجراء للمستخدمين الذين لم يشغّلوا طلب التسجيل إلغاؤه قبل المهلة التي تبلغ 60 ثانية. ويجب أن يعرض الجهاز الخطأ user_cancel في هذه الحالة.

طلبات نقل الملكية:

وقد يتم حذف الجهاز صراحةً من خدمة السحابة الإلكترونية.

إذا نجح الجهاز في العمل بنجاح، ولكن لم يتم وصفه بناءً على طلب /cloudprint/printer (لخدمة Google Cloud Platform)، يجب أن يعود إلى الوضع التلقائي (الجاهز).
إذا لم تعد بيانات اعتماد الجهاز تعمل (بسبب الإعداد المحدّد (يُذكر أنّه مصدر بيانات الاعتماد)&، أو بيانات الاعتماد غير الصالحة، أو بيانات الاستجابة من الخادم)، يجب إعادة السياسة إلى الوضع التلقائي (الجاهز).

يجب أن تؤدي إعادة الضبط على الإعدادات الأصلية المحلية إلى محو بيانات اعتماد الجهاز وضبطها على الحالة التلقائية.
اختياري: يمكن أن يوفر الجهاز عنصر قائمة لمحو بيانات الاعتماد ووضعها في الوضع التلقائي.

يجب أن تتضمن الأجهزة المتوافقة مع إشعارات XMPP إمكانية فحص اتصال الخادم. يجب التحكّم في مهلة أداة فحص الاتصال من الخادم من خلال "local;settings_local".
قد يجري الجهاز فحصًا صريحًا للخادم (واجهة برمجة التطبيقات/GCP/الطابعة مع Google Cloud Platform، بالإضافة إلى إشعارات XMPP) بمعدل لا يزيد عن مرة واحدة في اليوم (24 ساعة) للتأكُّد من مزامنتها. ننصحك بترتيب عشوائي لنافذة التحقّق خلال فترة تتراوح بين 24 و32 ساعة.
اختياري: بالنسبة إلى الأجهزة التي تعمل بنظام الطباعة في السحابة الإلكترونية، يُنصح بعدم استخدام طريقة يدوية (زر) للسماح للمستخدم ببدء فحص مهام طباعة جديدة من الجهاز. تتوفّر هذه الطابعة في بعض الطابعات.
اختياريّ. قد يكون لدى طابعات المؤسسة خيار إيقاف الاكتشاف المحلي تمامًا. وفي هذه الحالة، يجب أن يعدّل الجهاز هذه الإعدادات المحلية على الخادم. يجب أن تكون الإعدادات المحلية الجديدة فارغة (setting "local_discovery" to "false" وتعني أنه يمكن إعادة تفعيلها من خدمة Google Cloud Platform).

6.1.2 الرسم البياني التلقائي للتسجيل

6.2. هجمات XSSI وXSRF ومنعها

سيشرح هذا القسم احتمالية هجمات XSSI وXSRF على الجهاز وكيفية حمايتها (بما في ذلك أساليب إنشاء الرمز المميّز).
يمكنك الاطّلاع هنا على مزيد من التفاصيل: http://googleonlinesecurity.blogspot.com/2011/05/website-security-for-webmasters.html
عادةً ما تحدث هجمات XSSI وXSRF عند استخدام موقع إلكتروني لآليات مصادقة ملفات تعريف الارتباط. ومع أنّ Google لا تستخدم ملفات تعريف الارتباط مع خدمة "الطباعة السحابية من Google"، ما زالت هذه الهجمات ممكنة. إنّ الوصول إلى الشبكة المحلية بطبيعتها يثق بالطلبات ضمنيًا.

6.2.1. ملف XSSI

من المحتمل أن يتمكن موقع إلكتروني ضار من تخمين عنوان IP ورقم منفذ جهاز متوافق مع البروتوكول ومحاولة استدعاء واجهة برمجة تطبيقات Privet API باستخدام "srcsrclt;api name>" داخل العلامة <script> Tag:

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

بدون حماية، ستتمكن المواقع الإلكترونية الضارة من تنفيذ طلبات بيانات من واجهة برمجة التطبيقات والوصول إلى النتائج.
لمنع هذا النوع من الهجمات، يجب أن تتطلب جميع طلبات البيانات من واجهة برمجة التطبيقات Privet واجهة برمجة التطبيقات "X-Privet-Token" في الطلب. ولا يمكن لـ "srcportraitlt;api>"علامات النص البرمجي إضافة عناوين لحماية موقعك الإلكتروني من هذا النوع من الهجمات.

6.2.2. XSRF

http://en.wikipedia.org/wiki/cross-site_request_forgery
من الممكن لموقع إلكتروني ضار تخمين عنوان IP ورقم منفذ جهاز متوافق مع بروتوكول Privet، واستدعاء واجهة برمجة تطبيقات Privet API باستخدام <iframe> والنماذج أو بعض آليات التحميل الأخرى على مواقع إلكترونية مختلفة. لن يتمكن المهاجمون من الوصول إلى نتائج الطلب، ولكن إذا كان الطلب سينفّذ إجراءً (مثلاً طباعة)، سيتمكنون من تشغيله.

لمنع حدوث هذا الهجوم، نطلب منك توفير الحماية التالية:

اترك واجهة برمجة التطبيقات /privet/info مفتوحة على XSRF
يجب ألّا تنفّذ واجهة برمجة التطبيقات /privet/info أي إجراءات على الجهاز.
استخدام /privet/info API للحصول على x-privet-token
يجب أن تتحقّق جميع واجهات برمجة التطبيقات الأخرى من وجود رمز x-privet-token صالح في رأس "X-Privet-Token" صالح.
يجب أن يكون الرمز المميز x-privet صالحًا لمدة 24 ساعة فقط.

وحتى إذا تمكن أحد المهاجمين من تنفيذ واجهة برمجة التطبيقات /privet/info، لن يتمكّن من قراءة x-privet-token من الاستجابة، وبالتالي لن يتمكّن من طلب أي واجهة برمجة تطبيقات أخرى.

ننصح بشدة بإنشاء الرمز XSRF المميز باستخدام الخوارزمية التالية:

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

عناصر إنشاء الرمز المميز XSRF:

DELIMITER حرف خاص، وعادةً ما يكون ":"
تمثّل سمة issue_timetime عددًا من الثواني يمثّل عددًا معيّنًا من الأحداث (منذ فترة من الطابع الزمني) أو وقت تشغيل الجهاز (بالنسبة إلى عدّادات وحدة المعالجة المركزية (CPU)). وتتزايد قيمة issue_timedown عند بدء تشغيل الجهاز (يُرجى الاطّلاع على التحقّق من الرمز المميّز أدناه).
SHA1 - دالة تجزئة باستخدام خوارزمية SHA1
base64 - ترميز base64
device_secret - سر خاص بالجهاز يجب تعديل سر الجهاز عند كل إعادة تشغيل.

الطرق المقترَحة لإنشاء سر الجهاز:

إنشاء UUID جديد عند كل إعادة تشغيل
إنشاء رقم عشوائي يبلغ 64 بت عند كل عملية إعادة تشغيل

وليس من الضروري أن يحفظ الجهاز جميع رموز XSRF المميزة التي أصدرها. عندما يحتاج الجهاز إلى التحقّق من صحة رمز XSRF المميّز للتأكّد من صلاحيته، يجب أن يفك تشفير الرمز المميّز الأساسي 64. انتقِل إلى السمة issue_timecount من النصف الثاني (cleartext)، وحاوِل إنشاء تجزئة SHA1 من device_secret + + issue_timecount حيث يكون issue_timecount من الرمز المميّز. إذا كانت خوارزمية SHA1 التي تم إنشاؤها حديثًا تتطابق مع تلك الواردة في الرمز المميّز، يجب أن يتحقّق الجهاز الآن مما إذا كانت issue_timeCount ضمن فترة الصلاحية من (24 ساعة) في عدّاد الوقت الحالي. لإجراء ذلك، يتخذ الجهاز العدّاد الزمني الحالي (عدّاد وحدة المعالجة المركزية (CPU) على سبيل المثال) ويطرح issue_timecount منه. يجب أن تكون النتيجة عدد الثواني منذ ظهور الرمز المميّز.

ملاحظة مهمة: هذه هي الطريقة المُقترحة لتنفيذ حماية 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. التحقُّق من سير عمل إعدادات الطابعة