بهترین شیوه ها

مجوز

همه درخواست‌های مربوط به Google Photos Library API باید توسط یک کاربر احراز هویت مجاز باشد.

جزئیات فرآیند مجوز برای OAuth 2.0 بسته به نوع برنامه ای که می نویسید کمی متفاوت است. فرآیند کلی زیر برای همه انواع برنامه ها اعمال می شود:

  1. با انجام مراحل زیر برای فرآیند مجوز آماده شوید:
    • برنامه خود را با استفاده از Google API Console ثبت کنید.
    • کتابخانه API را فعال کنید و جزئیات OAuth مانند شناسه مشتری و راز مشتری را بازیابی کنید. برای اطلاعات بیشتر، به شروع مراجعه کنید.
  2. برای دسترسی به داده‌های کاربر، برنامه درخواستی از Google برای محدوده خاصی از دسترسی می‌کند.
  3. Google یک صفحه رضایت به کاربر نمایش می دهد که از آنها می خواهد به برنامه اجازه دهد تا برخی از داده های خود را درخواست کند.
  4. اگر کاربر تأیید کند، Google یک رمز دسترسی به برنامه ارائه می دهد که پس از مدت کوتاهی منقضی می شود.
  5. برنامه درخواستی برای داده های کاربر می کند و رمز دسترسی را به درخواست پیوست می کند.
  6. اگر گوگل تشخیص دهد که درخواست و رمز معتبر هستند، داده های درخواستی را برمی گرداند.

برای تعیین اینکه چه محدوده هایی برای برنامه شما مناسب است، به محدوده های مجوز مراجعه کنید.

فرآیند برخی از انواع برنامه‌ها شامل مراحل اضافی است، مانند استفاده از نشانه‌های تازه‌سازی برای به دست آوردن نشانه‌های دسترسی جدید. برای اطلاعات دقیق درباره جریان‌ها برای انواع مختلف برنامه‌ها، به استفاده از OAuth 2.0 برای دسترسی به Google API مراجعه کنید.

ذخیره سازی

داده ها را تازه نگه دارید

اگر به دلایل عملکردی نیاز به ذخیره موقت رسانه (مانند تصاویر کوچک، عکس‌ها یا ویدیوها) دارید، طبق دستورالعمل‌های استفاده ما، آن را بیش از 60 دقیقه در حافظه پنهان ذخیره نکنید.

همچنین نباید baseUrls ذخیره کنید، که پس از تقریباً 60 دقیقه منقضی می‌شوند.

شناسه‌های آیتم رسانه و شناسه‌های آلبوم که محتوای موجود در کتابخانه کاربر را به‌طور منحصربه‌فردی شناسایی می‌کنند، از محدودیت ذخیره‌سازی مستثنی هستند. می‌توانید این شناسه‌ها را به‌طور نامحدود ذخیره کنید (با توجه به سیاست حفظ حریم خصوصی برنامه‌تان). از شناسه‌های آیتم رسانه و شناسه‌های آلبوم برای بازیابی نشانی‌های وب در دسترس و داده‌ها با استفاده از نقاط پایانی مناسب استفاده کنید. برای اطلاعات بیشتر، به دریافت یک مورد رسانه یا فهرست آلبوم‌ها مراجعه کنید.

اگر موارد رسانه‌ای زیادی برای بازخوانی دارید، ممکن است کارآمدتر باشد که پارامترهای جستجویی را که موارد رسانه را برگردانده‌اند ذخیره کنید و درخواست را برای بارگیری مجدد داده ارسال کنید.

دسترسی SSL

HTTPS برای همه درخواست‌های سرویس وب کتابخانه API با استفاده از URL زیر لازم است:

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

درخواست های ارائه شده از طریق HTTP رد می شود.

رسیدگی به خطا

برای اطلاعات در مورد نحوه رسیدگی به خطاهای بازگشتی از API، به Cloud APIs Handling errors مراجعه کنید.

تلاش مجدد درخواست های ناموفق

مشتریان باید روی خطاهای 5xx با عقب نشینی نمایی همانطور که در عقب نشینی نمایی توضیح داده شده است دوباره امتحان کنند. حداقل تأخیر باید 1 s باشد مگر اینکه خلاف آن مستند شده باشد.

برای 429 خطا، مشتری ممکن است با حداقل 30s تاخیر دوباره امتحان کند. برای همه خطاهای دیگر، ممکن است سعی مجدد قابل اجرا نباشد. اطمینان حاصل کنید که درخواست شما ناتوان است و پیام خطا را برای راهنمایی ببینید.

عقب نشینی نمایی

در موارد نادر، ممکن است هنگام ارائه درخواست شما مشکلی پیش بیاید. ممکن است یک کد پاسخ HTTP 4XX یا 5XX دریافت کنید، یا ممکن است اتصال TCP در جایی بین سرویس گیرنده شما و سرور Google خراب شود. اغلب، ارزش دارد که درخواست را دوباره امتحان کنید. درخواست پیگیری ممکن است زمانی موفق شود که درخواست اصلی با شکست مواجه شود. با این حال، مهم است که از حلقه کردن، درخواست های مکرر به سرورهای Google استفاده نکنید. این رفتار حلقه‌ای می‌تواند شبکه بین مشتری و Google را بیش از حد بارگذاری کند و برای بسیاری از طرف‌ها مشکل ایجاد کند.

یک رویکرد بهتر، تلاش مجدد با افزایش تاخیر بین تلاش ها است. معمولاً تأخیر با یک عامل ضربی با هر تلاش افزایش می‌یابد، رویکردی که به عنوان عقب‌نشینی نمایی شناخته می‌شود.

همچنین باید مراقب باشید که در زنجیره فراخوانی برنامه کدی که به درخواست‌های مکرر پی در پی منجر می‌شود، کدی برای امتحان مجدد وجود نداشته باشد.

استفاده مودبانه از Google API

کلاینت‌های API با طراحی ضعیف می‌توانند بار بیشتری را هم روی اینترنت و هم روی سرورهای Google قرار دهند. این بخش شامل برخی از بهترین شیوه ها برای مشتریان API است. پیروی از این بهترین شیوه ها می تواند به شما کمک کند تا از مسدود شدن برنامه خود به دلیل سوء استفاده ناخواسته از API ها جلوگیری کنید.

درخواست های همگام شده

تعداد زیادی از درخواست‌های همگام‌سازی‌شده به APIهای Google می‌توانند مانند حمله انکار سرویس توزیع‌شده (DDoS) به زیرساخت‌های Google به نظر برسند و مطابق با آن رفتار شود. برای جلوگیری از این امر، باید مطمئن شوید که درخواست‌های API بین کلاینت‌ها همگام‌سازی نمی‌شوند.

به عنوان مثال، برنامه ای را در نظر بگیرید که زمان را در منطقه زمانی فعلی نمایش می دهد. این برنامه احتمالاً زنگ هشداری را در سیستم عامل مشتری تنظیم می کند که آن را در ابتدای دقیقه بیدار می کند تا زمان نمایش داده شده به روز شود. برنامه نباید هیچ گونه تماس API را به عنوان بخشی از پردازش مرتبط با آن هشدار برقرار کند.

برقراری تماس‌های API در پاسخ به زنگ هشدار ثابت بد است زیرا باعث می‌شود که تماس‌های API با شروع دقیقه، حتی بین دستگاه‌های مختلف، به جای توزیع یکنواخت در طول زمان، همگام‌سازی شوند. یک برنامه بد طراحی شده که این کار را انجام می دهد، در شروع هر دقیقه یک افزایش ترافیک در سطح عادی شصت برابر ایجاد می کند.

در عوض، یک طرح خوب ممکن این است که زنگ دوم را روی زمان انتخابی تصادفی تنظیم کنید. هنگامی که این زنگ دوم فعال می شود، برنامه با هر API مورد نیاز تماس می گیرد و نتایج را ذخیره می کند. برای به روز رسانی صفحه نمایش خود در ابتدای دقیقه، برنامه به جای فراخوانی مجدد API از نتایج ذخیره شده قبلی استفاده می کند. با این رویکرد، فراخوانی های API در طول زمان به طور مساوی پخش می شوند. علاوه بر این، تماس‌های API هنگام به‌روزرسانی نمایشگر، رندر را به تأخیر نمی‌اندازند.

به غیر از شروع دقیقه، سایر زمان‌های همگام‌سازی رایج که باید مراقب باشید که هدف قرار نگیرید، شروع یک ساعت و شروع هر روز در نیمه‌شب است.