محدودیت‌ها و سهمیه‌ها از زیرساخت Google دربرابر فرایند خودکاری که از Directory API به‌شیوه‌ای نامناسب استفاده می‌کند محافظت می‌کنند. درخواست‌های بیش‌ازحد از یک API ممکن است ناشی از یک اشتباه تایپی بی‌ضرر باشد، یا ممکن است ناشی از یک سیستم با طراحی ناکارآمد باشد که تماس‌های API غیرضروری برقرار می‌کند. صرف‌نظر از علت، مسدود کردن ترافیک از منبعی خاص پس‌از رسیدن به سطحی مشخص برای سلامت کلی سیستم Google Workspace ضروری است. این کار تضمین می‌کند که اقدامات یک توسعه‌دهنده نمی‌تواند تأثیر منفی بر انجمن بزرگ‌تر داشته باشد.
در موارد نادری که درخواست API شما ناموفق باشد، API یک کد وضعیت HTTP و دلیل خطا را برمی‌گرداند. علاوه‌براین، بدنه پاسخ حاوی شرح مفصلی از علت بروز خطا است.
فهرست زیر کدهای خطای احتمالی، دلایل، شرح‌های مربوطه، و اقدام توصیه‌شده برای خطاهای ناشی از رسیدن به محدودیت‌های سهمیه را نشان می‌دهد.
| کد | استدلال | شرح | اقدام توصیه‌شده |
|---|---|---|---|
| 403 | userRateLimitExceeded | نشان می‌دهد که از حد نرخ کاربر فراتر رفته است. مقدار پیش‌فرض تنظیم‌شده در کنسول Google Cloud ۲٬۴۰۰ پُرسمان در دقیقه به‌ازای هر کاربر برای هر پروژه Google Cloud است. | حدود هر کاربر را از صفحه سهمیه‌های Admin SDK API پروژه Google Cloud خود افزایش دهید، یا سرعت ارسال درخواست‌ها را بااستفاده از عقب‌نشینی نمایی کاهش دهید. |
| 403 | quotaExceeded | نشان می‌دهد که حد درخواست‌های هم‌زمان برای عملیاتی خاص به‌پایان رسیده است. | بااستفاده از عقب‌نشینی نمایی دوباره امتحان کنید. باید سرعت ارسال درخواست‌ها را کاهش دهید. |
| 429 | rateLimitExceeded | نشان می‌دهد که حد درخواست‌های هم‌زمان برای عملیاتی خاص به‌پایان رسیده است. | بااستفاده از عقب‌نشینی نمایی دوباره امتحان کنید. باید سرعت ارسال درخواست‌ها را کاهش دهید. این محدودیت برای هر حساب Google Workspace است، نه برای هر کارخواه میانای برنامه‌سازی کاربردی یا هر کاربر. این حد را نمی‌توان افزایش داد. |
پیاده‌سازی «عقب‌نشینی نمایی»
عقب‌گرد نمایی فرایندی است که در آن مشتری به‌صورت دوره‌ای درخواست ناموفق را در مدت زمان فزاینده‌ای امتحان مجدد می‌کند. این یک استراتژی استاندارد رسیدگی به خطا برای برنامه‌های شبکه است. استفاده از عقب‌گرد نمایی کارایی استفاده از پهنای باند را افزایش می‌دهد، تعداد درخواست‌های لازم برای دریافت پاسخ موفق را کاهش می‌دهد، و توان عملیاتی درخواست‌ها را در محیط‌های هم‌زمان به حداکثر می‌رساند.
جریان پیاده‌سازی عقب‌نشینی نمایی ساده به‌صورت زیر است.
- درخواست دادن به میانای برنامه‌سازی کاربردی
- پاسخ خطایی دریافت کنید که کد خطای قابل‌تکرار دارد
- ۱ ثانیه +
random_number_millisecondsثانیه صبر کنید - امتحان مجدد درخواست
- پاسخ خطایی دریافت کنید که کد خطای قابل‌تکرار دارد
- ۲ ثانیه +
random_number_millisecondsثانیه صبر کنید - امتحان مجدد درخواست
- پاسخ خطایی دریافت کنید که کد خطای قابل‌تکرار دارد
- ۴ ثانیه +
random_number_millisecondsثانیه صبر کنید - امتحان مجدد درخواست
- پاسخ خطایی دریافت کنید که کد خطای قابل‌تکرار دارد
- ۸ ثانیه +
random_number_millisecondsثانیه صبر کنید - امتحان مجدد درخواست
- پاسخ خطایی دریافت کنید که کد خطای قابل‌تکرار دارد
- ۱۶ ثانیه +
random_number_millisecondsثانیه صبر کنید - امتحان مجدد درخواست
- اگر همچنان خطا دریافت می‌کنید، متوقف شوید و خطا را ثبت کنید.
در جریان بالا، random_number_milliseconds عدد تصادفی
میلی‌ثانیه کمتر یا برابر با ۱۰۰۰ است. این کار برای جلوگیری از برخی خطاهای قفل در برخی پیاده‌سازی‌های هم‌زمان ضروری است.
random_number_milliseconds باید بعداز هر انتظار بازتعریف شود.
توجه: زمان انتظار همیشه
(2 ^ n) + random_number_milliseconds است، که در آن
n عدد صحیحی است که به‌طور یکنواخت افزایش می‌یابد و در ابتدا
به‌عنوان ۰ تعریف شده است. n برای هر تکرار (هر درخواست) ۱ عدد افزایش می‌یابد.
الگوریتم طوری تنظیم شده است که وقتی n برابر با ۵ است خاتمه یابد. این سقف فقط برای جلوگیری از تلاش مجدد بی‌نهایت مشتریان وجود دارد و منجر به تأخیر کلی حدود ۳۲ ثانیه قبل‌از اینکه درخواست «خطای غیرقابل‌بازیابی» تلقی شود می‌شود. کارخواه میانای برنامه‌سازی کاربردی شما می‌تواند درصورت نیاز تعداد تلاش‌های بیشتری را اجرا کند.
محدودیت‌ها و سهمیه‌های میانای برنامه‌سازی کاربردی
| دسته‌های محدودیت میانای برنامه‌سازی کاربردی | محدودیت‌ها |
|---|---|
| درحال ایجاد کاربران | بااستفاده از Directory API، نمی‌توانید بیش‌از ۱۰ کاربر در هر دامنه در هر ثانیه ایجاد کنید. |
| درحال حذف کاربران | بااستفاده از Directory API می‌توانید در هر ثانیه حداکثر ۵ کاربر را در هر دامنه حذف کنید. این محدودیت سرویس پسای هر دامنه است که نمی‌توان آن را در سهمیه‌های پروژه کنسول Google Cloud تنظیم کرد. هنگام ارسال درخواست‌های دسته‌ای، مطمئن شوید که مجموع عملیات در دسته‌ها کمتر از ۵ پُرسمان در ثانیه (QPS) باقی بماند. |
| درحال حذف اعضای گروه | بااستفاده از Directory API می‌توانید در هر ثانیه حداکثر ۳۰ عضو گروه را در هر دامنه حذف کنید. این محدودیت سرویس پسای برای هر دامنه است که نمی‌توان آن را در سهمیه‌های پروژه کنسول Google Cloud تنظیم کرد. هنگام ارسال درخواست‌های دسته‌ای، مطمئن شوید که مجموع عملیات در دسته‌ها کمتر از ۳۰ پُرسمان در ثانیه (QPS) باقی بماند. |
| گروه به‌عنوان عضو به گروه دیگری اضافه شد | ممکن است تا ۱۰ دقیقه طول بکشد تا اعضای گروه فرزند به‌عنوان اعضای گروه ولی نشان داده شوند. این حد ممکن است بسته به ظرفیت سیستم تغییر کند. |
| دستگاه‌های تلفن همراه |
بااستفاده از Directory API، می‌توانید تا این تعداد درخواست را انجام دهید:
|
| درحال تغییر نام کاربران | ممکن است تا ۱۰ دقیقه طول بکشد تا در همه سرویس‌ها منتشر شود. قبل‌از تغییر نام کاربر، توصیه می‌شود کاربر را از همه جلسات و سرویس‌های مرورگر خارج کنید. برای جزئیات بیشتر، به به‌روزرسانی کاربران مراجعه کنید. |
| درحال ایجاد/ به‌روزرسانی واحدهای سازمانی |
|
| دسته‌های سهمیه میانای برنامه‌سازی کاربردی | سهمیه‌ها |
دستگاه‌های Chrome annotatedLocation، حداکثر نویسه
|
حداکثر تعداد نویسه برای اطلاعات مکان دستگاه ۲۰۰ است. |
دستگاه‌های Chrome notes، حداکثر نویسه
|
حداکثر تعداد نویسه برای اطلاعات یادداشت‌های دستگاه ۵۰۰ است. |
دستگاه‌های Chrome، حداکثر user نویسه
|
حداکثر تعداد نویسه برای نام کاربر دستگاه ۱۰۰ است. |
| نام‌های مستعار دامنه، حداکثر | حداکثر تعداد نام‌های مستعار دامنه ۲۰ است. |
| گروه‌ها، شرح | حداکثر تعداد نویسه‌ها در شرح ۴٬۰۹۶ است. |
| گروه‌ها، در هر حساب | با حساب «ویرایش قدیمی و رایگان G Suite»، تعداد گروه‌ها به ۱۰ محدود می‌شود. ویرایش‌های دیگر محدودیتی برای تعداد گروه‌ها ندارند. |
| گروه‌ها، اعضا در هر گروه | با حساب «نسخه رایگان قدیمی G Suite»، گروه می‌تواند تا ۱۰۰ عضو داشته باشد. ویرایش‌های دیگر محدودیتی برای تعداد اعضایی که یک گروه می‌تواند داشته باشد ندارند. برای اطلاع از حدود عضویت در گروه برای هر کاربر، آشنایی با حدود و خط‌مشی‌های «گروه‌ها» را ببینید |
| رشته پُرسمان maxResults | میانای برنامه‌سازی کاربردی این را برمی‌گرداند:
|
| چند دامنه‌ای، حداکثر تعداد دامنه‌های مجاز در یک حساب | ۶۰۰ (۱ دامنه اصلی + ۵۹۹ دامنه اضافی) |
| واحد سازمانی، حداکثر تعداد کاربرانی که به‌طور هم‌زمان منتقل شده‌اند | ۲۰ کاربر را می‌توان به‌طور هم‌زمان منتقل کرد. و نشانی ایمیل اصلی کاربر باید ازقبل در حساب وجود داشته باشد. |
| نام‌های مستعار کاربر | تعداد کل نام‌های مستعار مجاز برای هر حساب کاربری ۳۰ عدد است. |
| نام‌های مستعار کاربر، استفاده از نام مستعار حذف‌شده | نام مستعار حذف‌شده کاربر را می‌توان بلافاصله دوباره استفاده کرد. |
| انواع دیگر محدودیت‌ها | محدودیت‌ها و دستورالعمل‌ها |
|---|---|
| صدور صورت‌حساب و ایجاد کاربران | برای کاربرانی که در طرح انعطاف‌پذیر Google Workspace هستند، ایجاد کاربر بااستفاده از این API تأثیر پولی خواهد داشت و منجر به کسر هزینه از حساب صورت‌حساب مشتری شما خواهد شد. برای مثال، اگر در طرح انعطاف‌پذیر Google Workspace باشید، ایجاد ۱۰ کاربر منجر به کسر هزینه ۱۰ پروانه Google Workspace از حسابتان می‌شود که از زمان ایجاد به‌صورت سرشکن‌شده محاسبه می‌شود. اگر در طرح سالانه هستید، ازقبل متعهد شده‌اید که هزینه تعداد مشخصی پروانه را پیش‌پرداخت کنید و فقط می‌توانید به‌تعداد تعهدتان کاربر ایجاد کنید. برای اطلاعات بیشتر درباره طرح‌های صورت‌حساب و حساب صورت‌حساب، به مرکز راهنمایی مدیریت مراجعه کنید. |
| نام و نام خانوادگی | نام و نام خانوادگی حداکثر ۴۰ نویسه دارد. این برچسب‌ها از نویسه‌های Unicode/UTF-8 پشتیبانی می‌کنند و می‌توانند حاوی فاصله، حروف (a-z)، اعداد (0-9)، خط تیره (-)، خط مورب (/)، و نقطه (.) باشند. برای اطلاعات بیشتر درباره قوانین استفاده از نویسه، به مرکز راهنمایی سرپرست مراجعه کنید. |
| گروه‌ها، درحال حذف | حذف گروه باعث حذف حساب‌های کاربری اعضای گروه نمی‌شود. |
| گروه‌ها و اعضای گروه، تغییر نشانی ایمیل | در این نسخه از میانای برنامه‌سازی کاربردی، آدرس ایمیل گروه را می‌توان قبل‌از فعال شدن سرویس Google Workspace تغییر داد. از کنسول سرپرست Google برای تغییر نشانی ایمیل عضو گروه استفاده کنید. پس‌از تغییر، API به‌طور خودکار تغییرات نشانی ایمیل را منعکس می‌کند. |
| گروه‌ها، تنظیمات | تنظیمات دسترسی، گزینه‌های هم‌رسانی، نظارت، و بایگانی بحث «گروه‌ها» بااستفاده از کنسول «سرپرست Google» مدیریت می‌شود. برای اطلاعات بیشتر درباره تنظیمات گروه‌ها، مرکز راهنمایی سرپرست را ببینید. |
| گروه‌ها، ارسال پیام | برای جلوگیری از هرزنامه و سوءاستفاده از ایمیل، Google تعداد پیام‌هایی را که می‌توانید به‌طور هم‌زمان به گیرندگان خارجی ارسال کنید محدود می‌کند. اگر پیامی به گروه ارسال کنید، هر عضو خارجی به‌عنوان یک گیرنده محسوب می‌شود. برای اطلاعات بیشتر، به حد ارسال ایمیل و جلوگیری از مسدود شدن ایمیل‌های ارسال‌شده به کاربران Gmail یا منتقل شدن آن‌ها به هرزنامه مراجعه کنید. |
| گروه‌ها، ارسال پیام‌های NDR | نمی‌توانید رسیدهای عدم تحویل (NDR) را که «پیام‌های برگشتی» نیز نامیده می‌شوند به گروه ارسال یا بازارسال کنید. |
| گروه‌های ایجادشده توسط کاربران، محدودیت‌ها | برای محدودیت‌های گروه ایجادشده توسط کاربر، به مرکز راهنمایی مدیریت مراجعه کنید |
| واحد سازمانی، روشن/خاموش کردن سرویس‌ها | از کنسول «سرپرست Google» برای مدیریت روشن و خاموش کردن سرویس‌ها برای واحد سازمانی استفاده کنید. |
| گذرواژه‌ها | می‌تواند حاوی هر ترکیبی از نویسه‌ها باشد. حداقل ۸ نویسه لازم است. حداکثر طول ۱۰۰ نویسه است. |
| Photos | در این نسخه از میانای برنامه‌سازی کاربردی، عکس همان جدیدترین عکس نمایه Google کاربر است. |
| نام‌های کاربری | نام‌های کاربری می‌توانند شامل حروف (a-z)، اعداد (0-9)، خط تیره (-)، زیرخط (_) باشند و Google Workspace نقطه (.) را تشخیص می‌دهد. این با Gmail متفاوت است. نام کاربری نباید حاوی علامت مساوی (=)، براکت (<،>)، یا بیش‌از یک نقطه (.) پشت سر هم باشد. برای اطلاعات بیشتر، مرکز راهنمایی سرپرست را ببینید. |
| نام‌های کاربری، تغییر نام | Google Hangouts پس‌از تغییر نام، همه دعوت‌های گپ به‌خاطر سپرده‌شده را دور می‌اندازد. کاربر باید برای گپ زدن دوباره با دوستانش اجازه درخواست کند. نام کاربری قدیمی به‌عنوان ایمیل مستعار حفظ می‌شود تا درصورت تنظیمات بازارسال ایمیل، از ارسال مداوم ایمیل اطمینان حاصل شود و به‌عنوان نام کاربری جدید دردسترس نخواهد بود. برای جزئیات مهم درباره تأثیر تغییر نام کاربران، به مرکز راهنمایی سرپرست مراجعه کنید. از عملیات حذف نام مستعار کاربر برای برداشتن نام مستعار ایمیل پس‌از تغییر نام استفاده کنید. |
| کاربران در چند دامنه | حساب Google Workspace می‌تواند شامل هرکدام از دامنه‌هایتان باشد. در حساب چنددامنه‌ای، کاربران یک دامنه می‌توانند سرویس‌ها را با کاربران دامنه‌های دیگر حساب هم‌رسانی کنند. چندین مؤلفه دامنه عبارت‌اند از:
|
| هشدارها، اعضای گروه | GROUP_CANNOT_CONTAIN_CYCLE – میانای برنامه‌سازی کاربردی اجازه نمی‌دهد چرخه در عضویت‌های گروه وجود داشته باشد. برای مثال، اگر group1 عضو group2 باشد، group2 نمی‌تواند عضو group1 باشد. |