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

التفويض

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

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

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

لتحديد النطاقات المناسبة لتطبيقك، اطّلِع على نطاقات التفويض.

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

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

يجب إبقاء البيانات محدَّثة.

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

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

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

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

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

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

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

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

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

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

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

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

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

الرقود الأسي

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

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

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

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

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

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

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

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

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

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

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