محدودیتها و سهمیهها، زیرساخت گوگل را از یک فرآیند خودکار که از Reports API به شیوهای نامناسب استفاده میکند، محافظت میکنند. درخواستهای بیش از حد از یک API ممکن است ناشی از یک اشتباه تایپی بیضرر باشد، یا ممکن است ناشی از یک سیستم با طراحی ناکارآمد باشد که فراخوانیهای غیرضروری API را انجام میدهد. صرف نظر از علت، مسدود کردن ترافیک از یک منبع خاص پس از رسیدن به سطح خاصی، برای سلامت کلی سیستم Google Workspace ضروری است. این تضمین میکند که اقدامات یک توسعهدهنده نمیتواند بر جامعه بزرگتر تأثیر منفی بگذارد.
در صورت عدم موفقیت درخواست API شما، یک پاسخ با کد وضعیت HTTP دریافت خواهید کرد. کد وضعیت ۴۰۳ حاوی اطلاعات خطایی در مورد ورودی نادرست است و کد وضعیت HTTP ۵۰۳ حاوی اطلاعات خطایی است که نشان میدهد کدام سهمیههای API از حد مجاز فراتر رفتهاند. این پاسخها به برنامه سفارشی شما اجازه میدهند تا این خطاها را تشخیص داده و اقدامات مناسب را انجام دهد.
اگر درخواستهای شما باید در یک دوره زمانی ثابت تکمیل شوند، درخواستهای خود را به صورت موازی ارسال کنید یا از چندین thread در برنامه جاوا یا C# خود استفاده کنید. نمونهای از درخواستهای موازی، درخواست دستههای کوچک ایمیل از کاربران مختلف به جای اضافه کردن یا حذف تعداد زیادی ایمیل از یک کاربر به طور همزمان است. در مورد threadها، سعی کنید با 10 thread شروع کنید، یک thread برای هر ایمیل کاربر. توجه داشته باشید، توصیه thread دارای معایبی است و برای همه موقعیتهای API مفید نیست. اگر تعداد درخواستها خیلی زیاد شود، خطاهای quota رخ میدهد.
برای همه خطاهایی که مبتنی بر زمان هستند (حداکثر N مورد برای N ثانیه در هر نخ)، به خصوص خطاهای کد وضعیت 503، توصیه میکنیم کد شما استثنا را دریافت کند و با استفاده از یک الگوریتم بازگشت نمایی ، قبل از تلاش مجدد برای فراخوانی ناموفق، کمی تأخیر ایجاد کند. یک مثال API گزارشها برای یک نخ این است که 5 ثانیه صبر کند و فراخوانی ناموفق را دوباره امتحان کند. اگر درخواست موفقیتآمیز بود، این الگو را برای نخهای دیگر تکرار کنید. اگر درخواست دوم موفقیتآمیز نبود، برنامه شما باید فرکانس درخواست را تا زمانی که یک فراخوانی موفقیتآمیز باشد، کاهش دهد. به عنوان مثال، تأخیر 5 ثانیهای اولیه را به 10 ثانیه افزایش دهید و دوباره فراخوانی ناموفق خود را امتحان کنید. همچنین، در مورد محدودیت تلاش مجدد تصمیم بگیرید. به عنوان مثال، یک درخواست را 5 تا 7 بار با زمانهای تأخیر مختلف دوباره امتحان کنید تا اینکه برنامه شما خطایی را به کاربر برگرداند.
محدودیتها
| دسته بندی های محدود API | محدودیتها |
|---|---|
| گزارش نرخهای QPS و QPD | این API تعداد درخواستها برای پروژه Google Cloud شما را محدود میکند. مقدار پیشفرض تعیینشده در کنسول Google Cloud، ۲۴۰۰ درخواست در دقیقه برای هر کاربر در هر پروژه Google Cloud است. میتوانید این محدودیت را از صفحه سهمیههای API Admin SDK پروژه Google Cloud خود افزایش دهید. اگر از این محدودیتها عبور شود، سرور کد وضعیت HTTP 503 را برمیگرداند. هنگام تلاش مجدد برای درخواستهای خود، از الگوریتم بازگشت نمایی استفاده کنید. |
محدودیتهای اضافی برای activities.list | API activities.list محدودیت اضافی ۲۵۰ درخواست فیلتر در دقیقه (۱۵۰۰۰ درخواست فیلتر در ساعت) دارد. یک درخواست فیلتر، درخواستی از API است که حداقل شامل یکی از پارامترهای درخواست زیر باشد:
|
| دسته بندی سهمیه API | سهمیهها |
| نتایج حداکثر | تعداد رکوردهای فهرستشده در هر صفحه از پاسخ یک API از ۰ تا ۱۰۰۰ رکورد است. مقدار پیشفرض ۱۰۰۰ رکورد است. |
انواع دیگر محدودیتها
| انواع دیگر محدودیتها | محدودیتها و دستورالعملها |
|---|---|
| قالب داده، پیشفرض | فرمت داده پیشفرض JSON است. این API از فرمت Atom نیز پشتیبانی میکند. |
| درخواستهای غیرمجاز | گوگل درخواستهای غیرمجاز به API را مجاز نمیداند. اگر هیچ توکن مجوزی ارائه نشود، درخواست غیرمجاز تلقی میشود. برای اطلاعات بیشتر، به درخواستهای مجاز مراجعه کنید. |
| پیامهای هشدار دهنده |
|
بهترین شیوهها برای activities.list
انتظار میرود از متد activities.list برای بررسیهای حسابرسی استفاده شود. برای بهترین عملکرد، درخواست شما باید شامل یک محدوده زمانی با استفاده از پارامترهای startTime و endTime باشد. محدودههای زمانی محدودتر منجر به زمان پاسخدهی بسیار سریعتر میشوند. این روش برای بازیابی حجم بالای لاگهای حسابرسی در نظر گرفته نشده است. اگر مرتباً سهمیه درخواست فیلتر activities.list خود را تمام میکنید، گزینههای زیر را در نظر بگیرید:
- لاگهای فضای کاری گوگل را راهاندازی کنید، به BigQuery صادر کنید و از APIهای قدرتمند پرسوجوی BigQuery برای بازیابی و تجزیه و تحلیل دادههای مورد نیاز خود بدون هیچ محدودیت سهمیه API استفاده کنید.
- به جای استفاده از درخواستهای فیلتر، از درخواستهای بدون فیلتر با محدوده زمانی استفاده کنید و فیلترینگ سمت کلاینت را انجام دهید (یعنی منطق فیلترینگ را در برنامه خود انجام دهید). این به شما امکان میدهد از محدودیت ۲۵۰ درخواست فیلتر در دقیقه عبور کنید، اما همچنان مشمول محدودیت ۲۴۰۰ درخواست در دقیقه برای هر کاربر در هر پروژه Google Cloud هستید.