التفويض
يجب أن يوافق مستخدم مصادَق عليه على كلّ الطلبات الموجّهة إلى Google Photos Library API.
تختلف تفاصيل عملية الحصول على الإذن لبروتوكول OAuth 2.0 قليلاً حسب نوع التطبيق الذي تكتبه. وتنطبق العملية العامة التالية على جميع أنواع التطبيقات:
- استعِدّ لعملية التفويض من خلال تنفيذ ما يلي:
- سجِّل تطبيقك باستخدام وحدة التحكم في واجهة Google API.
- فعِّل واجهة برمجة التطبيقات Library API واسترداد تفاصيل OAuth، مثل معرِّف العميل وسر العميل. لمزيد من المعلومات، راجِع البدء.
- للوصول إلى بيانات المستخدمين، يطلب التطبيق إلى Google نطاق وصول معيّنًا.
- تعرض Google شاشة موافقة للمستخدم تطلب منه السماح للتطبيق بطلب بعض بياناته.
- فإذا وافق المستخدم، ستزود Google التطبيق برمز دخول تنتهي صلاحيته بعد فترة زمنية قصيرة.
- يُجري التطبيق طلبًا لبيانات المستخدم من خلال إرفاق رمز الدخول بالطلب.
- يعرض محرّك البحث Google البيانات المطلوبة بعد تحققه من صلاحية الطلب والرمز المميّز.
لتحديد النطاقات المناسبة لتطبيقك، يُرجى الاطّلاع على نطاقات التفويض.
إنّ عملية بعض أنواع التطبيقات تتضمّن خطوات إضافية، مثل استخدام رموز إعادة التحميل للحصول على رموز دخول جديدة. للحصول على معلومات تفصيلية حول التدفقات لأنواع مختلفة من التطبيقات، راجِع استخدام OAuth 2.0 للوصول إلى Google API.
التخزين المؤقت
إبقاء البيانات محدَّثة:
إذا أردت تخزين الوسائط مؤقتًا (مثل الصور المصغّرة أو الصور أو الفيديوهات) لأسباب تتعلق بالأداء، لا تخزِّنها مؤقتًا لأكثر من 60 دقيقة وفقًا لإرشادات الاستخدام الموضّحة لدينا.
لا يُسمح أيضًا بتخزين "baseUrls" التي تنتهي صلاحيتها بعد 60
دقيقة تقريبًا.
يتم استثناء معرّفات عناصر الوسائط ومعرّفات الألبومات التي تعرّف المحتوى في مكتبة المستخدم بشكل فريد من قيود التخزين المؤقت. يمكنك تخزين أرقام التعريف هذه إلى أجل غير مسمى (وفقًا لسياسة خصوصية تطبيقك). استخدم معرفات عناصر الوسائط ومعرفات الألبوم لاسترداد عناوين URL والبيانات التي يمكن الوصول إليها مرة أخرى باستخدام نقاط النهاية المناسبة. لمزيد من المعلومات، راجع الحصول على عنصر وسائط أو إدراج الألبومات.
وإذا كان لديك العديد من عناصر الوسائط المُراد تحديثها، قد يكون من الأفضل تخزين معلمات البحث التي أدّت إلى عرض عناصر الوسائط وإعادة إرسال الاستعلام لإعادة تحميل البيانات.
الوصول إلى طبقة المقابس الآمنة
يكون بروتوكول HTTPS مطلوبًا لجميع طلبات خدمة الويب لواجهة برمجة تطبيقات المكتبة التي تستخدم عنوان URL التالي:
https://photoslibrary.googleapis.com/v1/service/output?parameters
يتم رفض الطلبات المقدَّمة عبر HTTP.
خطأ أثناء المعالجة
للحصول على معلومات عن كيفية التعامل مع الأخطاء الناتجة عن واجهة برمجة التطبيقات، يُرجى الاطّلاع على أخطاء المعالجة في Cloud API.
إعادة محاولة إرسال الطلبات التي تعذّر تنفيذها
على العملاء إعادة محاولة تصحيح أخطاء 5xx باستخدام خوارزمية الرقود الأسي الثنائي على النحو الموضَّح في مقالة
الرقود الأسي الثنائي. يجب أن يكون الحد الأدنى لمدة التأخير 1 s
ما لم يرِد خلاف ذلك.
بالنسبة إلى أخطاء 429، قد يعيد العميل المحاولة مع تأخير مدته 30s على الأقل. بالنسبة لجميع الأخطاء الأخرى،
قد لا تكون إعادة المحاولة سارية. تأكد من أن طلبك عالق وشاهد
رسالة الخطأ للحصول على إرشادات.
خوارزمية الرقود الأسي الثنائي
في حالات نادرة، قد يحدث خطأ ما أثناء تقديم طلبك.وقد تتلقى رمز استجابة HTTP 4XX أو 5XX، أو قد يفشل اتصال TCP في مكان ما بين العميل وخادم Google. في كثير من الأحيان، من المفيد إعادة محاولة
الطلب. قد ينجح طلب المتابعة عند تعذّر تنفيذ الإجراء الأصلي. ومع ذلك، من المهم عدم التكرار، وتقديم طلبات بشكل متكرر إلى خوادم Google. ويمكن أن يؤدي هذا السلوك التكراري إلى زيادة الحمل على الشبكة بين العميل وGoogle، ما يسبب مشاكل للعديد من الأطراف.
أفضل نهج هو إعادة المحاولة مع زيادة التأخيرات بين المحاولات. عادةً، يزداد التأخير بعامل مضاعف مع كل محاولة، وهو أسلوب يُعرف باسم التراجع الأسي.
يجب أيضًا توخي الحذر لأنّه لا توجد إعادة محاولة رمز أعلى في سلسلة استدعاء التطبيق تؤدي إلى طلبات متكررة في تتابع سريع.
استخدام مهذب لواجهات Google APIs
يمكن لبرامج واجهة برمجة التطبيقات السيئة التصميم تحميل حِمل أكبر من اللازم على كل من الإنترنت وخوادم Google. يحتوي هذا القسم على بعض أفضل الممارسات لعملاء واجهات برمجة التطبيقات. يمكن أن يساعدك اتّباع أفضل الممارسات هذه في تجنُّب حظر تطبيقك بسبب إساءة الاستخدام غير المقصودة لواجهات برمجة التطبيقات.
الطلبات المتزامنة
قد تبدو الأعداد الكبيرة من الطلبات المتزامنة إلى واجهات برمجة تطبيقات Google مثل هجوم الحرمان من الخدمات الموزعة (DDoS) على البنية الأساسية لـ Google، وسيتم التعامل معها وفقًا لذلك. لتجنّب حدوث ذلك، عليك التأكّد من عدم مزامنة طلبات البيانات من واجهة برمجة التطبيقات بين البرامج.
على سبيل المثال، جرّب تطبيقًا يعرض الوقت في المنطقة الزمنية الحالية. من المحتمل أن يضبط هذا التطبيق منبهًا في نظام تشغيل العميل لإيقاظه في بداية الدقيقة حتى يمكن تحديث الوقت المعروض. ويجب ألا يُجري التطبيق أي طلبات بيانات من واجهة برمجة التطبيقات كجزء من عملية المعالجة المرتبطة بهذا التنبيه.
يُعدّ إجراء طلبات بيانات من واجهة برمجة التطبيقات استجابةً لأي تنبيه ثابت أمر سيئ، لأنّه يؤدي إلى مزامنة طلبات البيانات من واجهة برمجة التطبيقات مع بداية الدقيقة، حتى بين الأجهزة المختلفة، بدلاً من توزيعها بالتساوي على مدار الوقت. وينتج عن التطبيق الذي صُمم بشكل سيئ في هذه الحالة ارتفاعًا في عدد الزيارات بمعدل ستين مرة على المستويات العادية في بداية كل دقيقة.
بدلاً من ذلك، فإن أحد التصميمات الجيدة المحتملة هو تعيين تنبيه ثانٍ على وقت يتم اختياره عشوائيًا. عندما ينطلق هذا الإنذار الثاني، يُجري التطبيق اتصالاً بأية واجهات برمجة تطبيقات يحتاج إليها ويخزِّن النتائج. لتحديث عرضه في بداية الدقيقة، يستخدم التطبيق النتائج المخزنة مسبقًا بدلاً من استدعاء واجهة برمجة التطبيقات مرة أخرى. ومن خلال هذه الطريقة، يتم توزيع طلبات البيانات من واجهة برمجة التطبيقات بشكل متساوٍ على مدار الوقت. علاوة على ذلك، لا تؤخر طلبات البيانات من واجهة برمجة التطبيقات العرض عند تحديث الشاشة.
باستثناء بداية الدقيقة، هناك أوقات مزامنة شائعة أخرى يجب أن تحرص على عدم استهدافها في بداية الساعة ومن بداية كل يوم في منتصف الليل.