أفضل الممارسات

التفويض

يجب أن يوافق مستخدم مُعتمَد على كلّ الطلبات الموجّهة إلى Google Photos APIs.

تختلف تفاصيل عملية الموافقة على الطلبات لبروتوكول OAuth 2.0 نوعًا ما تبعًا لنوع التطبيق الذي تكتبه. العملية العامة التالية ينطبق على جميع أنواع التطبيقات:

  1. استعد لعملية التفويض من خلال تنفيذ ما يلي:
  2. للوصول إلى بيانات المستخدمين، يطلب التطبيق إلى Google نطاق وصول معين.
  3. تعرِض Google شاشة موافقة للمستخدم تطلب منه السماح لتطبيقك بطلب بعض بياناته.
  4. إذا وافق المستخدم، ستوفّر Google للتطبيق رمز الدخول. تنتهي صلاحيتها بعد فترة زمنية قصيرة.
  5. يقدّم التطبيق طلبًا للحصول على بيانات المستخدم، مع إرفاق رمز الوصول بالطلب.
  6. وإذا حددت Google أن الطلب والرمز المميز صالحين، فسيعرض البيانات المطلوبة.

ولتحديد النطاقات المناسبة لتطبيقك، يُرجى الاطّلاع على مقالة منح الأذونات. والنطاقات.

تتضمن العملية المتعلقة ببعض أنواع التطبيقات خطوات إضافية، مثل استخدام تحديث الرموز المميزة للحصول على رموز دخول جديدة. لمزيد من المعلومات التفصيلية حول عمليات الربط لأنواع مختلفة من التطبيقات، يُرجى الاطّلاع على مقالة استخدام بروتوكول OAuth 2.0 للوصول إلى Google APIs.

التخزين المؤقت

حافظ على حداثة البيانات.

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

يجب أيضًا عدم تخزين baseUrls التي تنتهي صلاحيتها بعد 60 دقيقة تقريبًا.

إنّ معرّفات عناصر الوسائط ومعرّفات الألبومات التي تحدّد المحتوى بشكل فريد في مكتبة المستخدم exempt from the caching restriction. يمكنك تخزين أرقام التعريف هذه لأجل غير مسمى (يخضع لسياسة خصوصية طلبك). استخدام معرّفات عناصر الوسائط ومعرّفات الألبومات لاسترداد عناوين URL والبيانات التي يمكن الوصول إليها مرة أخرى باستخدام نقاط النهاية المناسبة. بالنسبة الحصول على مزيد من المعلومات، يُرجى الاطّلاع على الحصول على وسائط عنصر أو قائمة الألبومات.

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

الوصول إلى طبقة المقابس الآمنة

يجب توفُّر بروتوكول HTTPS لجميع طلبات خدمة الويب لواجهات برمجة تطبيقات "صور Google" التي تستخدم عنوان URL التالي:

https://photoslibrary.googleapis.com/v1/service/output?parameters

يتم رفض الطلبات التي يتم إجراؤها عبر HTTP.

خطأ أثناء المعالجة

لمزيد من المعلومات حول كيفية التعامل مع الأخطاء الناتجة عن واجهة برمجة التطبيقات، يمكنك الاطّلاع على التعامل مع واجهات برمجة التطبيقات الأخطاء.

إعادة محاولة إرسال الطلبات التي تعذّر تنفيذها

على العملاء إعادة المحاولة بشأن أخطاء 5xx مع رقود أسي كما هو موضّح في رقود أسي: يجب أن يكون الحد الأدنى للمهلة 1 s. ما لم يتم توثيق خلاف ذلك.

في حال حدوث أخطاء 429، يمكن للعميل إعادة المحاولة بعد 30s ثانية كحد أدنى. بالنسبة إلى كلّ الأخطاء الأخرى، قد لا يكون إعادة المحاولة مناسبة. تأكَّد من أنّ طلبك أحادي المفعول واطّلِع على رسالة الخطأ للحصول على إرشادات.

تراجع أسي

في حالات نادرة، قد يحدث خطأ أثناء عرض طلبك. قد تتلقّى رمز استجابة HTTP هو 4XX أو 5XX، أو قد يتعذّر اتصال TCP في مكان ما بين العميل وخادم Google. غالبًا ما يكون من المفيد إعادة محاولة تنفيذ الطلب. قد ينجح طلب المتابعة عندما يتعذّر تنفيذ الطلب الأصلي. ومع ذلك، من المهم عدم التكرار الحلقي، وتقديم طلبات إلى خوادم Google بشكل متكرر. يمكن أن يؤدي هذا السلوك المتكرّر إلى زيادة عدد عمليات الربط بين برنامجك وGoogle، ما يؤدي بدوره إلى التسبب في مشاكل للعديد من الجهات.

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

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

الاستخدام اللائق لواجهات برمجة تطبيقات Google

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

الطلبات المتزامنة

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

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

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

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

وبغض النظر عن بداية تلك اللحظة، هناك أوقات مزامنة شائعة أخرى ينبغي أن يحرص على عدم الاستهداف في بداية ساعة وبداية كل يوم في منتصف الليل.