محدودیت ها و سهمیه های استفاده

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

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

اگر درخواست‌های شما باید در یک دوره زمانی ثابت تکمیل شوند، درخواست‌های خود را به صورت موازی ارسال کنید یا از چندین thread در برنامه جاوا یا C# خود استفاده کنید. نمونه‌ای از درخواست‌های موازی، درخواست دسته‌های کوچک ایمیل از کاربران مختلف به جای اضافه کردن یا حذف تعداد زیادی ایمیل از یک کاربر به طور همزمان است. در مورد threadها، سعی کنید با 10 thread شروع کنید، یک thread برای هر ایمیل کاربر. توجه داشته باشید، توصیه thread دارای بده بستان‌هایی است و برای همه موقعیت‌های API مفید نیست. اگر تعداد درخواست‌ها خیلی زیاد شود، خطاهای سهمیه رخ می‌دهد. نمونه دیگری از بده بستان، سهمیه برای API حسابرسی ایمیل برای حداکثر نرخ کلی آپلود پیام است. نرخ آپلود یک درخواست API - در هر ثانیه - برای هر کاربر است، مهم نیست که چند thread درخواست آپلود انجام می‌دهند.

برای همه خطاهایی که مبتنی بر زمان هستند (حداکثر N مورد برای N ثانیه در هر نخ)، به خصوص خطاهای کد وضعیت 503 ، توصیه می‌کنیم کد شما استثنا را دریافت کند و با استفاده از یک الگوریتم بازگشت نمایی ، قبل از تلاش مجدد برای فراخوانی ناموفق، کمی تأخیر داشته باشد. یک مثال API حسابرسی ایمیل برای یک نخ، 5 ثانیه صبر کردن و تلاش مجدد برای فراخوانی ناموفق است. اگر درخواست موفقیت‌آمیز بود، این الگو را برای نخ‌های دیگر تکرار کنید. اگر درخواست دوم موفقیت‌آمیز نبود، برنامه شما باید فرکانس درخواست را تا زمانی که یک فراخوانی موفقیت‌آمیز باشد، کاهش دهد. به عنوان مثال، تأخیر 5 ثانیه‌ای اولیه را به 10 ثانیه افزایش دهید و دوباره فراخوانی ناموفق خود را امتحان کنید. همچنین، در مورد محدودیت تلاش مجدد تصمیم بگیرید. به عنوان مثال، یک درخواست را 5 تا 7 بار با زمان‌های تأخیر مختلف دوباره امتحان کنید تا اینکه برنامه شما خطایی را به کاربر برگرداند.

جدول زیر محدودیت‌های مربوط به API حسابرسی ایمیل را فهرست می‌کند:

دسته بندی های محدود API	محدودیت‌ها
ایجاد فایل‌های صندوق پستی رمزگذاری‌شده	بسته به حجم فایل‌ها، آماده‌سازی سیستم برای ایجاد فایل‌های صندوق پستی رمزگذاری‌شده ممکن است تا چند روز طول بکشد.
فایل‌های صندوق پستی رمزگذاری شده، خطاهایی در هنگام حذف	هنگام حذف یک صندوق پستی رمزگذاری شده و بروز خطا، به درخواست وضعیت MARKED_DELETE داده می‌شود. این خلاصه‌ها و فایل‌های خروجی به طور خودکار ظرف ۲۴ ساعت (و احتمالاً فایل‌های باقی مانده) توسط گوگل برای حذف مجدد انتخاب می‌شوند. اگر وضعیت MARKED_DELETE به طور مداوم بازگردانده شد، یک استراتژی بازگشت نمایی را امتحان کنید.

جدول زیر سهمیه‌های مربوط به API حسابرسی ایمیل را فهرست می‌کند:

دسته بندی سهمیه API	سهمیه‌ها
توکن‌های احراز هویت ClientLogin	به مدت ۲۴ ساعت معتبر است. خطای 401 token expired است.
قالب‌های تاریخ	قبل از استفاده از تاریخ‌ها در API حسابرسی ایمیل، تمام تاریخ‌ها را به قالب زمان هماهنگ جهانی (UTC) تبدیل کنید. برای اطلاعات بیشتر، به مبدل UTC مراجعه کنید.
فایل‌های صندوق پستی رمزگذاری‌شده، خلاصه‌های EXPIRED و فایل‌های خروجی	گوگل فایل‌های رمزگذاری‌شده‌ی صندوق پستی را به مدت ۳ هفته نگه می‌دارد. پس از این مدت، آنها حذف می‌شوند. دانلود این فایل‌های صندوق پستی در این بازه زمانی بر عهده‌ی مدیر دامنه است.
فایل‌های صندوق پستی رمزگذاری‌شده، فرمت	فایل‌های صندوق پستی رمزگذاری‌شده در قالب mbox هستند.
فایل‌های صندوق پستی رمزگذاری‌شده، حداکثر درخواست‌های ایجاد	حداکثر درخواست‌های ایجاد خروجی صندوق پستی در روز، در مجموع ۱۰۰ درخواست از همه مدیران دامنه است.
وضعیت فایل صندوق پستی رمزگذاری شده، صفحه بندی	هنگام درخواست وضعیت همه درخواست‌های صندوق پستی، پاسخ‌ها می‌توانند حجم زیادی از داده‌ها را برگردانند. API حسابرسی ایمیل این داده‌ها را در صفحاتی دسته‌بندی می‌کند که هر صفحه حداکثر شامل ۱۰۰ ورودی است و یک URI در برچسب link rel='next' به صفحه بعدی نتایج اشاره می‌کند. هنگام توسعه برنامه کلاینت، کد شما باید این نتایج اضافی را مدیریت کند.
مانیتور ایمیل	حداکثر تعداد درخواست‌های نظارت بر ایمیل در روز ۱۵۰۰ است. این محدودیت برای دامنه است و شامل تمام درخواست‌های ارسال شده توسط هر مدیری در طول روز می‌شود.
کلید عمومی	API حسابرسی ایمیل فقط از یک کلید پشتیبانی می‌کند. کلید عمومی از نرم‌افزار GNU Privacy Guard (GPG) استفاده می‌کند. این کلید در قالب PGP است و یک کلید رمزگذاری RSA با کدگذاری ASCII است. قبل از آپلود کلید عمومی، ابتدا باید آن را به یک رشته کدگذاری شده با base64 تبدیل کنید. فایل کلید عمومی باید با مجموعه کاراکتر US-ASCII (نام مجموعه کاراکتر ترجیحی IANA برای ASCII) خوانده شود.
جستجو	پارامترهای searchQuery و includeDeleted مانعه الجمع هستند. اگر includeDeleted="true" جستجوی عبارت مورد نظر امکان‌پذیر نیست.