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

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

Privet

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

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

1. مقدمة

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

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

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

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

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

الاكتشاف هو بروتوكول مستند إلى شبكات متوفّرة بدون ضبط (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. نوع الخدمة

تستخدم ميزة "اكتشاف الخدمات" في نظام أسماء النطاقات التنسيق التالي لأنواع الخدمات: _applicationprotocol._transportprotocol. في حالة بروتوكول Privet، يجب أن يكون نوع الخدمة لنظام أسماء النطاقات المستند إلى اكتشاف الخدمات هو: _privet._tcp

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

بالإضافة إلى نوع الخدمة الرئيسي، يجب أن يعلن الجهاز عن سجلّات PTR الخاصة بأنواع الخدمة الفرعية المقابلة (راجِع مواصفات DNS-SD: "7.1. Selective Instance Enumeration (Subtypes)". يجب أن يكون التنسيق على النحو التالي: _<subtype>._sub._privet._tcp

في الوقت الحالي، نوع الجهاز الفرعي الوحيد المتوافق هو printer. لذا، يجب أن تعلن جميع الطابعات عن سجلَّي PTR:

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

2.2. سجلّ TXT

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

تتطلّب Privet أن يرسل الجهاز أزواج المفتاح/القيمة التالية في سجلّ TXT. إنّ سلاسل المفاتيح/القيم غير حساسة لحالة الأحرف، على سبيل المثال، "CS=online" و "cs=ONLINE" متطابقتان. يجب أن تكون المعلومات الواردة في سجلّ TXT هي نفسها المعلومات التي يمكن الوصول إليها من خلال واجهة برمجة التطبيقات ‎ /info (راجِع 4.1). قسم واجهة برمجة التطبيقات).

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

‫2.2.1. txtvers

إصدار بنية سجلّ TXT، ويجب أن يكون txtvers هو السجلّ الأول في بنية سجلّ TXT. الإصدار الوحيد المتاح حاليًا هو 1.

txtvers=1

2.2.2. ty

تعرض هذه السمة اسمًا للجهاز يمكن للمستخدم قراءته. على سبيل المثال:

ty=Google Cloud Ready Printer Model XYZ

‫2.2.3. ملاحظة (اختياري)

تعرض هذه السمة اسمًا للجهاز يمكن للمستخدم قراءته. على سبيل المثال:

note=1st floor lobby printer

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

‫2.2.4. url

عنوان URL للخادم الذي تم ربط هذا الجهاز به (بما في ذلك البروتوكول) على سبيل المثال:

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

‫2.2.5. النوع

قائمة مفصولة بفواصل لأنواع الأجهزة الفرعية المتوافقة مع هذا الجهاز. التنسيق هو: "type=_subtype1,_subtype2". في الوقت الحالي، نوع الجهاز الفرعي الوحيد المتوافق هو printer.

type=printer

يجب الإعلان عن كل نوع فرعي مُدرَج باستخدام سجلّ موجّه (PTR) مطابق. يجب أن يتضمّن كل نوع فرعي من أنواع الخدمات المتوافقة عنصرًا مطابقًا. يجب أن يكون اسم النوع الفرعي للخدمة (<subtype>._sub._privet._tcp) مساويًا لنوع الجهاز هنا.

‫2.2.6. id

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

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

‫2.2.7. cs

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

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

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

cs=online
cs=offline
cs=connecting

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

3- إعلانات مهمة

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

3.1. التشغيل

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

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

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

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

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

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

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

4.1.1. التسجيل

عند تسجيل الجهاز، يجب تحديد المَعلمة "local_settings" على النحو التالي:

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

يمكن ضبط الإعدادات التالية:

اسم القيمة	نوع القيمة	الوصف
local_discovery	قيمة منطقية	تحدّد هذه السمة ما إذا كان يُسمح بوظيفة الاكتشاف المحلي. إذا كانت القيمة "false"، يجب إيقاف جميع واجهات برمجة التطبيقات المحلية (بما في ذلك /info) واكتشاف DNS-SD. بشكل تلقائي، يجب أن تعرض الأجهزة التي يتم تسجيلها حديثًا القيمة "true".
access_token_enabled	قيمة منطقية (اختيارية)	يشير إلى ما إذا كان يجب عرض واجهة برمجة التطبيقات /accesstoken على الشبكة المحلية. يجب أن تكون القيمة التلقائية هي "true".
printer/local_printing_enabled	قيمة منطقية (اختيارية)	يشير إلى ما إذا كان يجب إتاحة وظيفة الطباعة المحلية (/printer/createjob و/printer/submitdoc و/printer/jobstate) على الشبكة المحلية. يجب أن تكون القيمة التلقائية هي "true".
printer/conversion_printing_enabled	قيمة منطقية (اختيارية)	تحدّد هذه السمة ما إذا كان بإمكان الطباعة المحلية إرسال مهمة إلى الخادم لتحويلها. لا يكون هذا الخيار منطقيًا إلا عند تفعيل ميزة الطباعة المحلية.
xmpp_timeout_value	int (اختياري)	تشير إلى عدد الثواني بين عمليات اختبار الاتصال لقناة XMPP. يجب أن تكون القيمة التلقائية 300 (5 دقائق) أو أكثر.

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

4.1.2. التشغيل

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

/cloudprint/printer?printerid=<printer_id>

أو

/cloudprint/list

يُفضَّل استخدام /cloudprint/printer على /cloudprint/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
         }
}

يشير العنصر "current" إلى الإعدادات السارية في الوقت الحالي.

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

بعد أن يرى الجهاز الإعدادات "في انتظار المراجعة"، يجب أن يحدّث حالته (راجِع ما يلي).

4.1.3. تعديل

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

<device_id>/update_settings

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

/cloudprint/printer?printerid=<printer_id>

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

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

4.1.3.1. الإعدادات المحلية في انتظار المراجعة

يجب ألا تتضمّن المَعلمة "local_settings" التي يستخدمها الجهاز لاستدعاء واجهة برمجة التطبيقات للخادم القسم "pending".

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

يمكن للجهاز فقط تغيير قسم "الحالية" في "local_settings". سيغيّر جميع المستخدمين الآخرين قسم "في انتظار المراجعة"، وسينتظرون إلى أن ينقل الجهاز التغييرات إلى قسم "الحالية".

4.1.4. بلا إنترنت

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

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

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

<device_id>/delete

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

/cloudprint/printer?printerid=<printer_id>

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

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

4.2. ‫/privet/info API

إنّ واجهة برمجة التطبيقات الخاصة بالمعلومات إلزامية ويجب أن يتم تنفيذها على كل جهاز. وهو طلب HTTP GET لعنوان URL "/privet/info": GET /privet/info HTTP/1.1

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

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

4.2.1. الإدخال

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

4.2.2. الإرجاع

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

يشير عمود TXT إلى الحقل المقابل في سجلّ TXT الخاص بخدمة DNS-SD.

اسم القيمة	نوع القيمة	الوصف	TXT
إصدار	سلسلة	أعلى إصدار (رئيسي.ثانوي) من واجهة برمجة التطبيقات المتوافقة، وهو حاليًا 1.0
الاسم	سلسلة	اسم الجهاز الذي يمكن للمستخدِم قراءته	ty
الوصف	سلسلة	(اختياري) وصف الجهاز يجب أن يكون قابلاً للتعديل من قِبل المستخدم.	ملاحظة
url	سلسلة	عنوان URL للخادم الذي يتواصل معه هذا الجهاز يجب أن يتضمّن عنوان URL مواصفات البروتوكول، مثلاً: https://www.google.com/cloudprint.	url
النوع	قائمة السلاسل	قائمة بأنواع الأجهزة المتوافقة	النوع
id	سلسلة	معرّف الجهاز، يكون فارغًا إذا لم يتم تسجيل الجهاز بعد.	id
device_state	سلسلة	حالة الجهاز: idle تعني أنّ الجهاز جاهز processing تعني أنّ الجهاز مشغول وقد تكون الوظائف محدودة لبعض الوقت stopped تعني أنّ الجهاز لا يعمل ويجب أن يتدخّل المستخدم
connection_state	سلسلة	حالة الاتصال بالخادم (base_url) online - الاتصال متاح offline - لا يوجد اتصال connecting - يتم تنفيذ خطوات بدء التشغيل not-configured - لم يتم ضبط الاتصال بعد قد يبلغ الجهاز المسجّل عن حالة الاتصال استنادًا إلى حالة قناة الإشعارات (مثل حالة اتصال XMPP).	cs
الشركة المصنّعة	سلسلة	اسم الشركة المصنّعة للجهاز
نموذج	سلسلة	طراز الجهاز
serial_number	سلسلة	معرّف الجهاز الفريد في هذا المواصفات، يجب أن يكون هذا المعرّف معرّفًا فريدًا عالميًا (UUID). (مواصفات GCP 1.1) (اختياري) ننصح بشدة باستخدام معرّف الرقم التسلسلي نفسه في كل مكان، حتى تتمكّن البرامج المختلفة من التعرّف على الجهاز نفسه. على سبيل المثال، يمكن للطابعات التي تستخدم بروتوكول IPP استخدام معرّف الرقم التسلسلي هذا في حقل "printer-device-id".
البرامج الثابتة	سلسلة	إصدار البرامج الثابتة على الجهاز
مدة التشغيل	int	عدد الثواني منذ تشغيل الجهاز
setup_url	سلسلة	(اختياري) عنوان URL (بما في ذلك البروتوكول) للصفحة التي تتضمّن تعليمات الإعداد
support_url	سلسلة	(اختياري) عنوان URL (بما في ذلك البروتوكول) للصفحة التي تتضمّن معلومات حول الدعم والأسئلة الشائعة
update_url	سلسلة	(اختياري) عنوان URL (بما في ذلك البروتوكول) للصفحة التي تتضمّن تعليمات تحديث البرامج الثابتة
x-privet-token	سلسلة	قيمة العنوان X-Privet-Token التي يجب تمريرها إلى جميع واجهات برمجة التطبيقات لمنع هجمات XSSI وXSRF يمكنك الاطّلاع على القسم 6.1 للحصول على التفاصيل.
api	وصف لواجهات برمجة التطبيقات	قائمة بواجهات برمجة التطبيقات المتوافقة (موضّحة أدناه)
semantic_state	JSON	(اختياري) الحالة الدلالية للجهاز بتنسيق CloudDeviceState.

‫api: هي قائمة JSON تحتوي على قائمة واجهات برمجة التطبيقات المتاحة من خلال الشبكة المحلية. يُرجى العِلم أنّه قد لا تتوفّر جميع واجهات برمجة التطبيقات في الوقت نفسه على الشبكة المحلية. على سبيل المثال، يجب أن يتيح الجهاز الذي تم ربطه حديثًا استخدام واجهة برمجة التطبيقات /register فقط:

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

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

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

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

‫/privet/register: واجهة برمجة التطبيقات لتسجيل الأجهزة على الشبكة المحلية (راجِع واجهة برمجة التطبيقات /privet/register للحصول على التفاصيل). يجب إخفاء واجهة برمجة التطبيقات هذه بعد تسجيل الجهاز بنجاح في السحابة الإلكترونية.
‫/privet/accesstoken - واجهة برمجة التطبيقات لطلب رمز دخول من الجهاز (راجِع واجهة برمجة التطبيقات ‎/privet/accesstoken للحصول على التفاصيل).
‫/privet/capabilities: واجهة برمجة تطبيقات لاسترداد إمكانات الجهاز (راجِع واجهة برمجة التطبيقات /privet/capabilities للحصول على التفاصيل).
‫/privet/printer/*: واجهة برمجة تطبيقات خاصة بنوع الجهاز "طابعة"، راجِع واجهات برمجة التطبيقات الخاصة بالطابعة لمعرفة التفاصيل.

في ما يلي مثال على الردّ ‎ /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 خطأً فقط في حال عدم توفّر عنوان X-Privet-Token. يجب أن يكون الخطأ HTTP 400:

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

4.3. ‫/privet/register API

‫/privet/register API هو اختياري. وهو طلب POST لبروتوكول HTTP. يجب أن تتحقّق واجهة برمجة التطبيقات /privet/register من توفّر عنوان X-Privet-Token صالح. يجب أن ينفّذ الجهاز واجهة برمجة التطبيقات هذه على عنوان URL "/privet/register":

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

يجب أن يعرض الجهاز واجهة برمجة التطبيقات ‎ /privet/register فقط عندما يسمح بالتسجيل بدون إذن في الوقت الحالي. على سبيل المثال:

عند تشغيل الجهاز (أو بعد النقر على زر خاص على الجهاز) ولم يتم تسجيله بعد، يجب أن يعرض واجهة برمجة التطبيقات /privet/register للسماح لمستخدم من الشبكة المحلية بطلب ملكية الطابعة.
بعد اكتمال عملية التسجيل، يجب أن يتوقف الجهاز عن عرض واجهة برمجة التطبيقات ‎ /privet/register لمنع مستخدم آخر على الشبكة المحلية من استعادة الجهاز.
قد تتوفّر طرق مختلفة لتسجيل الأجهزة على بعضها، ويجب ألا تعرض واجهة برمجة التطبيقات ‎/privet/register على الإطلاق (على سبيل المثال، موصّل الطباعة السحابية من Chrome).

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

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

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

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

أكمِل عملية التسجيل.

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

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

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

4.3.1. الإدخال

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

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

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

4.3.2. الإرجاع

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

اسم القيمة	نوع القيمة	الوصف
إجراء	سلسلة	الإجراء نفسه كما في مَعلمة الإدخال
المستخدم	سلسلة (اختيارية)	المستخدم نفسه الوارد في مَعلمة الإدخال (قد يكون غير متوفّر إذا تم حذفه من الإدخال).
الرمز المميز	سلسلة (اختيارية)	الرمز المميز للتسجيل (إلزامي لاستجابة "getClaimToken"، ويتم حذفه في "start" و"complete" و"cancel")
claim_url	سلسلة (اختيارية)	عنوان URL للتسجيل (إلزامي لاستجابة getClaimToken، ويتم حذفه في "البدء" و"الإكمال" و"الإلغاء") بالنسبة إلى الطابعات السحابية، يجب أن يكون هذا الحقل هو "complete_invite_url" الذي تم تلقّيه من الخادم.
automated_claim_url	سلسلة (اختيارية)	عنوان URL للتسجيل (إلزامي لاستجابة getClaimToken، ويتم حذفه في "البدء" و"الإكمال" و"الإلغاء") بالنسبة إلى الطابعات السحابية، يجب أن يكون عنوان URL هو "automated_invite_url" الذي تم تلقّيه من الخادم.
device_id	سلسلة (اختيارية)	معرّف الجهاز الجديد (يتم حذفه في ردّ "البدء"، وهو إلزامي في ردّ "الإكمال").

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

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

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

4.4. ‫/privet/accesstoken API

واجهة برمجة التطبيقات ‎/privet/accesstoken اختيارية. وهو طلب استرداد بيانات باستخدام GET HTTP. يجب أن تتحقّق واجهة برمجة التطبيقات ‎/privet/accesstoken من توفّر عنوان صالح "X-Privet-Token". يجب أن ينفّذ الجهاز واجهة برمجة التطبيقات هذه على عنوان URL التالي: ‎/privet/accesstoken

GET /privet/accesstoken HTTP/1.1

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

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

/cloudprint/proximitytoken

ومرِّر المَعلمتَين "printerid=<printer_id>" و "user" من واجهة برمجة التطبيقات المحلية. في حال نجاح العملية، سيتضمّن ردّ الخادم العنصر التالي:

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

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

4.4.1. الإدخال

تحتوي واجهة برمجة التطبيقات ‎/privet/accesstoken على مَعلمات الإدخال التالية:

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

4.4.2. الإرجاع

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

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

مثال:

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

4.4.3. الأخطاء

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

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

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

4.5. ‫/privet/capabilities API

واجهة برمجة التطبيقات ‎/privet/capabilities اختيارية. وهو طلب استرداد بيانات باستخدام GET HTTP. يجب أن تتحقّق واجهة برمجة التطبيقات ‎/privet/capabilities من توفّر عنوان صالح "X-Privet-Token". يجب أن ينفّذ الجهاز واجهة برمجة التطبيقات هذه على عنوان URL ‏"/privet/capabilities":

GET /privet/capabilities HTTP/1.1

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

4.5.1. الإدخال

تحتوي واجهة برمجة التطبيقات ‎/privet/capabilities على مَعلمات الإدخال التالية:

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

4.5.2. الإرجاع

تعرض واجهة برمجة التطبيقات ‎/privet/capabilities إمكانات الجهاز بتنسيق Cloud Device Description (CDD) JSON (راجِع مستند 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/capabilities الأخطاء التالية (راجِع قسم "الأخطاء" للحصول على التفاصيل):

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

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

4.6. الأخطاء

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

اسم القيمة	نوع القيمة	الوصف
خطأ	سلسلة	نوع الخطأ (محدّد لكل واجهة برمجة تطبيقات)
الوصف	سلسلة (اختيارية)	وصف يمكن للمستخدم قراءته للخطأ.
server_api	سلسلة (اختيارية)	في حال حدوث خطأ في الخادم، يحتوي هذا الحقل على واجهة برمجة التطبيقات الخاصة بالخادم التي تعذّر تنفيذها.
server_code	int (اختياري)	في حال حدوث خطأ في الخادم، يحتوي هذا الحقل على رمز الخطأ الذي أرجعه الخادم.
server_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- Printer API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

5.1. ‫/privet/printer/createjob API

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

POST /privet/printer/createjob HTTP/1.1

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

5.1.1. الإدخال

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

5.1.2. الإرجاع

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

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

مثال:

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

5.1.3. الأخطاء

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

خطأ	الوصف
invalid_ticket	تذكرة الطباعة التي تم إرسالها غير صالحة.
printer_busy	الطابعة مشغولة ولا يمكنها حاليًا معالجة /إنشاء مهمة. أعِد المحاولة بعد انتهاء المهلة.
printer_error	الطابعة في حالة خطأ وتتطلّب تفاعلاً من المستخدم لإصلاحها. يجب أن يتضمّن الوصف شرحًا أكثر تفصيلاً (مثلاً "انحشار الورق في الدرج 1").
invalid_x_privet_token	الرمز المميّز X-Privet-Token غير صالح أو فارغ في الطلب.

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

5.2. ‫/privet/printer/submitdoc API

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

POST /privet/printer/submitdoc HTTP/1.1

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

إذا لم تتمكّن الطابعة من الاحتفاظ بكل البيانات في المخزن المؤقت الداخلي، عليها استخدام آليات TCP لإبطاء عملية نقل البيانات إلى أن تطبع جزءًا من المستند، ما يتيح استخدام جزء من المخزن المؤقت مرة أخرى. (على سبيل المثال، قد تضبط الطابعة windowsize=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" (مَعلمة متكرّرة) و "ticket" (تذكرة المهمة بتنسيق CloudJobTicket). يُرجى العِلم أنّ PrintJobState المقدَّم يجب أن يكون نهائيًا، أي يجب أن يكون نوعه DONE أو ABORTED، ويجب تقديم سبب في حال كان ABORTED (راجِع JobState للحصول على التفاصيل). يُرجى أيضًا العِلم أنّ هذا الاستخدام لواجهة /cloudprint/submit للإبلاغ عن مهام الطباعة المحلية غير مذكور في مواصفاتها لأنّ هذا القسم يهدف إلى وصف الاستخدام الأساسي للواجهة، وهو إرسال مهمة طباعة مع المستند المطلوب طباعته والمقدَّم في المعلَمة "content".

5.2.1. الإدخال

تحتوي واجهة برمجة التطبيقات ‎/privet/printer/submitdoc على مَعلمات الإدخال التالية:

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

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

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

5.2.2. الإرجاع

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

اسم القيمة	نوع القيمة	الوصف
job_id	سلسلة	معرّف مهمة الطباعة التي تم إنشاؤها حديثًا (الطباعة البسيطة) أو job_id المحدّد في الطلب (الطباعة المتقدّمة).
expires_in	int	عدد الثواني التي تكون فيها مهمة الطباعة هذه صالحة
job_type	سلسلة	نوع المحتوى للمستند الذي تم إرساله
job_size	عدد صحيح 64 بت	حجم بيانات الطباعة بالبايت.
job_name	سلسلة	(اختياري) اسم الوظيفة نفسه كما في الإدخال (إن وُجد).

مثال:

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

5.2.3. الأخطاء

قد تعرض واجهة برمجة التطبيقات ‎/privet/printer/submitdoc الأخطاء التالية (راجِع قسم "الأخطاء" للحصول على التفاصيل):

خطأ	الوصف
invalid_print_job	تم تحديد رقم تعريف مهمة غير صالح أو منتهي الصلاحية في الطلب. أعِد المحاولة بعد انتهاء المهلة.
invalid_document_type	نوع MIME للمستند غير متوافق مع الطابعة.
invalid_document	المستند الذي تم إرساله غير صالح.
document_too_large	يتجاوز المستند الحد الأقصى للحجم المسموح به.
printer_busy	الطابعة مشغولة ولا يمكنها معالجة المستند حاليًا. أعِد المحاولة بعد انتهاء المهلة.
printer_error	الطابعة في حالة خطأ وتتطلّب تفاعلاً من المستخدم لإصلاحها. يجب أن يتضمّن الوصف شرحًا أكثر تفصيلاً (مثلاً "انحشار الورق في الدرج 1").
invalid_params	تم تحديد مَعلمات غير صالحة في الطلب. (يجب تجاهل المَعلمات غير المعروفة بأمان لضمان التوافق في المستقبل)
user_cancel	ألغى المستخدم عملية الطباعة بشكل صريح من الجهاز.
server_error	تعذّر نشر المستند على "الطباعة السحابية".
invalid_x_privet_token	الرمز المميّز X-Privet-Token غير صالح أو فارغ في الطلب.

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

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

5.3. ‫/privet/printer/jobstate API

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

GET /privet/printer/jobstate HTTP/1.1

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

5.3.1. الإدخال

تحتوي واجهة برمجة التطبيقات ‎/privet/printer/jobstate على مَعلمات الإدخال التالية:

الاسم	القيمة
job_id	معرّف مهمة الطباعة المطلوب عرض حالتها.

5.3.2. الإرجاع

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

اسم القيمة	نوع القيمة	الوصف
job_id	سلسلة	معرّف مهمة الطباعة التي تتعلّق بها معلومات الحالة
الولاية	سلسلة	draft: تم إنشاء مهمة الطباعة على الجهاز (لم يتم تلقّي أي مكالمات /privet/printer/submitdoc بعد). في قائمة الانتظار: تم تلقّي مهمة الطباعة وإضافتها إلى قائمة الانتظار، ولكن لم تبدأ عملية الطباعة بعد. ‫ in_progress: مهمة الطباعة قيد التنفيذ. stopped: تم إيقاف مهمة الطباعة مؤقتًا، ولكن يمكن إعادة تشغيلها يدويًا أو تلقائيًا. done: اكتملت مهمة الطباعة. تمت مقاطعتها - تعذّر إكمال مهمة الطباعة.
الوصف	سلسلة	(اختياري) وصف لحالة مهمة الطباعة يمكن للمستخدمين قراءته يجب تضمين معلومات إضافية إذا كانت قيمة الحالة هي متوقّفة أو ملغاة. يوفّر الحقل semantic_state عادةً وصفًا أفضل وأكثر دلالة للعميل.
expires_in	int	عدد الثواني التي تكون فيها مهمة الطباعة هذه صالحة
job_type	سلسلة	(اختياري) نوع المحتوى للمستند المُرسَل
job_size	عدد صحيح 64 بت	(اختياري) حجم بيانات الطباعة بالبايت
job_name	سلسلة	(اختياري) اسم الوظيفة نفسه كما في الإدخال (إن وُجد).
server_job_id	سلسلة	(اختياري) معرّف مهمة الطباعة الذي يعرضه الخادم (في حال تم نشر مهمة الطباعة في خدمة "الطباعة السحابية"). تم استبعادها للطباعة بلا إنترنت.
semantic_state	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 للحصول على مزيد من التفاصيل حول حالة الجهاز:

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

خطأ	الوصف
invalid_print_job	تم تحديد معرّف وظيفة غير صالح أو منتهي الصلاحية في الطلب.
server_error	تعذّر الحصول على حالة مهمة الطباعة (بالنسبة إلى مهام الطباعة التي تم نشرها على "الطباعة السحابية").
invalid_x_privet_token	الرمز المميّز X-Privet-Token غير صالح أو فارغ في الطلب.

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

6. الملحق

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

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

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

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

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

أنّهم يؤكّدون طلب التسجيل
ماذا يحدث إذا لم يرسل المستخدم الطلب؟

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

عمليات نقل الملكية:

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

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

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

يجب أن تتضمّن الأجهزة التي تتيح تلقّي إشعارات XMPP إمكانية إرسال طلب اختبار اتصال إلى الخادم. يجب أن يكون بإمكان الخادم التحكّم في مهلة إرسال طلبات ping من خلال "local_settings".
قد يرسل الجهاز إشارة إلى الخادم (/cloudprint/printer API للطباعة السحابية من Google، بالإضافة إلى إشارات XMPP) بمعدّل لا يزيد عن مرّة واحدة في اليوم (24 ساعة) للتأكّد من المزامنة. يُنصح بتحديد فترة عشوائية للتحقّق تتراوح بين 24 و32 ساعة.
اختياري: بالنسبة إلى أجهزة Cloud Print، يُنصح بتوفير طريقة يدوية (زر) للسماح للمستخدم ببدء البحث عن مهام طباعة جديدة من الجهاز، ولكن ليس ذلك إلزاميًا. تتضمّن بعض الطابعات هذه الميزة.
اختيارية: قد تتضمّن طابعات المؤسسة خيارًا لإيقاف ميزة "الاكتشاف المحلي" بالكامل. في هذه الحالة، على الجهاز تعديل هذه الإعدادات المحلية على الخادم. يجب أن تكون الإعدادات المحلية الجديدة فارغة (ضبط "local_discovery" على "false" يعني أنّه يمكن إعادة تفعيلها من خدمة GCP).

‫6.1.2 مخطط التسجيل التلقائي

6.2. هجمات XSSI وXSRF وطرق الوقاية منها

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

6.2.1. XSSI

من المحتمل أن يخمن موقع إلكتروني ضار عنوان IP ورقم منفذ لجهاز متوافق مع Privet، وأن يحاول استدعاء واجهة برمجة تطبيقات Privet باستخدام "src=<اسم واجهة برمجة التطبيقات>" داخل علامة <script>:

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

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

6.2.2. XSRF

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

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

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

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

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

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

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

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

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

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

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

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

Privet تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

1. مقدمة

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

2.1. نوع الخدمة

2.2. سجلّ TXT

‫2.2.1. txtvers

2.2.2. ty

‫2.2.3. ملاحظة (اختياري)

‫2.2.4. url

‫2.2.5. النوع

‫2.2.6. id

‫2.2.7. cs

3- إعلانات مهمة

3.1. التشغيل

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

3.3. تعديل

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

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

4.1.1. التسجيل

4.1.2. التشغيل

4.1.3. تعديل

4.1.3.1. الإعدادات المحلية في انتظار المراجعة

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

4.1.4. بلا إنترنت

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

4.2. ‫/privet/info API

4.2.1. الإدخال

4.2.2. الإرجاع

4.2.3. الأخطاء

4.3. ‫/privet/register API

4.3.1. الإدخال

4.3.2. الإرجاع

4.3.3. الأخطاء

4.4. ‫/privet/accesstoken API

4.4.1. الإدخال

4.4.2. الإرجاع

4.4.3. الأخطاء

4.5. ‫/privet/capabilities API

4.5.1. الإدخال

4.5.2. الإرجاع

4.5.3. الأخطاء

4.6. الأخطاء

5- Printer API

5.1. ‫/privet/printer/createjob API

5.1.1. الإدخال

5.1.2. الإرجاع

5.1.3. الأخطاء

5.2. ‫/privet/printer/submitdoc API

5.2.1. الإدخال

5.2.2. الإرجاع

5.2.3. الأخطاء

5.3. ‫/privet/printer/jobstate API

5.3.1. الإدخال

5.3.2. الإرجاع

5.3.3. الأخطاء

6. الملحق

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

‫6.1.2 مخطط التسجيل التلقائي

6.2. هجمات XSSI وXSRF وطرق الوقاية منها

6.2.1. XSSI

6.2.2. XSRF

‫6.2.3 مخطط التسلسل لإنشاء رمز مميّز X-Privet والتحقّق منه

‫6.3. مخططات سير العمل

6.3.1. سير عمل الطابعة الجاهزة للاستخدام

6.3.2. بدء تشغيل الطابعة المسجّلة

‫6.3.3 سير عمل معالجة إشعارات XMPP

6.3.4. سير عمل التحقّق من إعدادات الطابعة

Privet