محدودیتها و سهمیهها، زیرساخت گوگل را از یک فرآیند خودکار که از API دایرکتوری به شیوهای نامناسب استفاده میکند، محافظت میکنند. درخواستهای بیش از حد از یک API ممکن است ناشی از یک اشتباه تایپی بیضرر باشد، یا ممکن است ناشی از یک سیستم با طراحی ناکارآمد باشد که فراخوانیهای API غیرضروری انجام میدهد. صرف نظر از علت، مسدود کردن ترافیک از یک منبع خاص پس از رسیدن به سطح خاصی، برای سلامت کلی سیستم Google Workspace ضروری است. این تضمین میکند که اقدامات یک توسعهدهنده نمیتواند بر جامعه بزرگتر تأثیر منفی بگذارد.
در صورت عدم موفقیت درخواست API شما، API یک کد وضعیت HTTP و دلیل خطا را برمیگرداند. علاوه بر این، بدنه پاسخ شامل شرح مفصلی از علت خطا است.
لیست زیر کدهای خطای احتمالی، دلایل، توضیحات مربوطه و اقدامات پیشنهادی برای خطاهای ناشی از رسیدن به محدودیت سهمیه را نشان میدهد.
| کد | دلیل | توضیحات | اقدام توصیه شده |
|---|---|---|---|
| ۴۰۳ | userRateLimitExceeded | نشان میدهد که از حد مجاز نرخ کاربر عبور شده است. مقدار پیشفرض تعیینشده در کنسول Google Cloud، ۲۴۰۰ پرسوجو در دقیقه برای هر کاربر در هر پروژه Google Cloud است. | محدودیتهای هر کاربر را از صفحه سهمیههای API Admin SDK پروژه Google Cloud خود افزایش دهید، یا با استفاده از روش بازگشت نمایی (exponential backoff) ، سرعت ارسال درخواستها را کاهش دهید. |
| ۴۰۳ | سهمیه تجاوز شد | نشان میدهد که محدودیت درخواستهای همزمان برای یک عملیات خاص به پایان رسیده است. | با استفاده از back-off نمایی دوباره امتحان کنید. شما باید سرعت ارسال درخواستها را کاهش دهید. |
| ۴۲۹ | محدودیت نرختجاوز شده | نشان میدهد که محدودیت درخواستهای همزمان برای یک عملیات خاص به پایان رسیده است. | با استفاده از back-off تصاعدی دوباره امتحان کنید. شما باید سرعت ارسال درخواستها را کاهش دهید. این محدودیت برای هر حساب Google Workspace است، نه برای هر کلاینت API یا برای هر کاربر. این محدودیت قابل افزایش نیست. |
پیاده سازی عقب نشینی نمایی
بازگشت نمایی فرآیندی است که در آن یک کلاینت به صورت دورهای یک درخواست ناموفق را در مدت زمان فزایندهای دوباره امتحان میکند. این یک استراتژی استاندارد مدیریت خطا برای برنامههای شبکه است. استفاده از بازگشت نمایی، کارایی استفاده از پهنای باند را افزایش میدهد، تعداد درخواستهای مورد نیاز برای دریافت پاسخ موفقیتآمیز را کاهش میدهد و توان عملیاتی درخواستها را در محیطهای همزمان به حداکثر میرساند.
روند پیادهسازی روش سادهی پسرانش نمایی به شرح زیر است.
- ارسال درخواست به API
- دریافت پاسخ خطا که دارای کد خطای قابل امتحان مجدد است
- ۱ ثانیه +
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 یک عدد صحیح یکنواخت صعودی است که در ابتدا با 0 تعریف شده است. n برای هر تکرار (هر درخواست) 1 واحد افزایش مییابد.
این الگوریتم طوری تنظیم شده است که وقتی n برابر با ۵ شود، خاتمه یابد. این سقف فقط برای جلوگیری از تلاش مجدد بینهایت کلاینتها تعیین شده است و منجر به تأخیر کلی حدود ۳۲ ثانیه قبل از اینکه یک درخواست "خطای غیرقابل بازیابی" تلقی شود، میشود. کلاینت API شما میتواند در صورت نیاز تعداد تلاشهای بیشتری را پیادهسازی کند.
محدودیتها و سهمیههای API
| دسته بندی های محدود API | محدودیتها |
|---|---|
| ایجاد کاربران | شما نمیتوانید با استفاده از API دایرکتوری، بیش از ۱۰ کاربر در هر دامنه در ثانیه ایجاد کنید. |
| گروه به عنوان عضو به گروه دیگری اضافه شد | ممکن است تا 10 دقیقه تأخیر وجود داشته باشد تا اعضای گروه فرزند به عنوان اعضای گروه والد ظاهر شوند. این محدودیت میتواند بسته به ظرفیت سیستم تغییر کند. |
| دستگاههای تلفن همراه | با استفاده از API دایرکتوری، میتوانید تا موارد زیر را انجام دهید:
|
| تغییر نام کاربران | ممکن است تا ۱۰ دقیقه طول بکشد تا در تمام سرویسها منتشر شود. قبل از تغییر نام کاربر، توصیه میشود کاربر را از تمام جلسات مرورگر و سرویسها خارج کنید. برای جزئیات بیشتر، به بخش بهروزرسانی کاربران مراجعه کنید. |
| ایجاد/بهروزرسانی واحدهای سازمانی |
|
| دسته بندی سهمیه API | سهمیهها |
دستگاههای کروم، annotatedLocation ، حداکثر کاراکترها | حداکثر تعداد کاراکتر برای اطلاعات موقعیت مکانی یک دستگاه ۲۰۰ است. |
notes دستگاههای کروم، حداکثر کاراکترها | حداکثر تعداد کاراکتر برای اطلاعات یادداشتهای یک دستگاه ۵۰۰ کاراکتر است. |
دستگاههای کروم، حداکثر کاراکترهای user | حداکثر تعداد کاراکتر برای نام کاربری دستگاه ۱۰۰ است. |
| نامهای مستعار دامنه، حداکثر | حداکثر تعداد نامهای مستعار دامنه ۲۰ است. |
| گروهها، توضیحات | حداکثر تعداد کاراکترهای قابل استفاده در توضیحات ۴۰۹۶ کاراکتر است. |
| گروهها، به ازای هر حساب | با یک حساب G Suite Legacy Free Edition، تعداد گروهها به ۱۰ گروه محدود میشود. سایر نسخهها هیچ محدودیتی در تعداد گروهها ندارند. |
| گروهها، اعضا در هر گروه | با یک حساب کاربری G Suite Legacy Free Edition، یک گروه میتواند تا ۱۰۰ عضو داشته باشد. سایر نسخهها هیچ محدودیتی برای تعداد اعضایی که یک گروه میتواند داشته باشد، ندارند. برای محدودیتهای عضویت در گروه برای هر کاربر، به بخش «درک سیاستها و محدودیتهای گروهها» مراجعه کنید. |
| رشته پرس و جو maxResults | API برمیگرداند:
|
| دامنه چندگانه، حداکثر تعداد دامنههای مجاز در یک حساب | ۶۰۰ (۱ دامنه اصلی + ۵۹۹ دامنه اضافی) |
| واحد سازمانی، حداکثر تعداد کاربران جابجا شده در یک زمان | میتوان همزمان ۲۰ کاربر را جابجا کرد. و آدرسهای ایمیل اصلی کاربر باید از قبل در حساب کاربری وجود داشته باشند. |
| نامهای مستعار کاربر | تعداد کل نامهای مستعار مجاز برای هر حساب کاربری 30 است. |
| نامهای مستعار کاربر، با استفاده از نام مستعار حذف شده | نام مستعار کاربر حذف شده را میتوان بلافاصله دوباره استفاده کرد. |
| انواع دیگر محدودیتها | محدودیتها و دستورالعملها |
|---|---|
| صدور صورتحساب و ایجاد کاربران | برای کاربرانی که از طرح انعطافپذیر Google Workspace استفاده میکنند، ایجاد کاربران با استفاده از این API تأثیر مالی خواهد داشت و منجر به اعمال هزینههایی به حساب صورتحساب مشتری شما خواهد شد. به عنوان مثال، اگر از طرح انعطافپذیر Google Workspace استفاده میکنید، ایجاد 10 کاربر منجر به اعمال هزینههایی برای 10 مجوز Google Workspace میشود که از زمان ایجاد، به حساب شما اضافه میشوند. اگر از طرح سالانه استفاده میکنید، از قبل متعهد به پرداخت هزینه تعداد مشخصی از مجوزها شدهاید و فقط میتوانید به تعداد تعهد خود کاربر ایجاد کنید. برای اطلاعات بیشتر در مورد طرحهای صورتحساب و حساب صورتحساب خود، به مرکز راهنمای مدیریت مراجعه کنید. |
| نام و نام خانوادگی | نام و نام خانوادگی حداکثر ۴۰ کاراکتر دارند. آنها از کاراکترهای Unicode/UTF-8 پشتیبانی میکنند و میتوانند شامل فاصله، حروف (az)، اعداد (۰-۹)، خط تیره (-)، اسلش (/) و نقطه (.) باشند. برای اطلاعات بیشتر در مورد قوانین استفاده از کاراکترها، به مرکز راهنمای مدیریت مراجعه کنید. |
| گروهها، حذف | حذف یک گروه، حسابهای کاربری اعضای گروه را حذف نمیکند. |
| گروهها و اعضای گروه، تغییر آدرس ایمیل | در این نسخه از API، آدرس ایمیل یک گروه میتواند قبل از فعال شدن سرویس Google Workspace تغییر کند. از کنسول مدیریت گوگل برای تغییر آدرس ایمیل اعضای گروه استفاده کنید. پس از تغییر، API به طور خودکار تغییرات آدرس ایمیل را منعکس میکند. |
| گروهها، تنظیمات | تنظیمات دسترسی به گروهها، گزینههای اشتراکگذاری، نظارت و بایگانی بحثها با استفاده از کنسول مدیریت گوگل مدیریت میشود. برای اطلاعات بیشتر در مورد تنظیمات گروهها، به مرکز راهنمای مدیریت مراجعه کنید. |
| گروهها، ارسال پیام | برای جلوگیری از هرزنامه و سوءاستفاده از ایمیل، گوگل تعداد پیامهایی را که میتوانید همزمان برای گیرندگان خارجی ارسال کنید، محدود میکند. اگر پیامی را به یک گروه ارسال کنید، هر عضو خارجی به عنوان یک گیرنده محاسبه میشود. برای اطلاعات بیشتر، به محدودیتهای ارسال ایمیل و جلوگیری از مسدود شدن یا ارسال ایمیل به کاربران Gmail به هرزنامه مراجعه کنید. |
| گروهها، ارسال پیامهای NDR | شما نمیتوانید رسیدهای عدم تحویل (NDR) که به آنها «پیامهای برگشتی» نیز گفته میشود را به یک گروه ارسال یا فوروارد کنید. |
| گروههای ایجاد شده توسط کاربران، محدودیتها | برای محدودیتهای گروهی ایجاد شده توسط کاربر، به مرکز راهنمای مدیریت مراجعه کنید |
| واحد سازمانی، روشن/خاموش کردن خدمات | از کنسول مدیریت گوگل برای مدیریت روشن و خاموش کردن سرویسها برای یک واحد سازمانی استفاده کنید. |
| رمزهای عبور | میتواند شامل هر ترکیبی از کاراکترها باشد. حداقل ۸ کاراکتر مورد نیاز است. حداکثر طول ۱۰۰ کاراکتر است. |
| عکسها | در این نسخه از API، یک عکس، آخرین عکس پروفایل گوگل کاربر است. |
| نامهای کاربری | نامهای کاربری میتوانند شامل حروف (az)، اعداد (0-9)، خط تیره (-)، زیرخط (_) باشند و Google Workspace نقطه یا نقطه (.) را تشخیص میدهد. این با Gmail متفاوت است. یک نام کاربری نمیتواند شامل علامت مساوی (=)، براکت (<,>) یا بیش از یک نقطه (.) در یک ردیف باشد. برای اطلاعات بیشتر، به مرکز راهنمای مدیریت مراجعه کنید. |
| نامهای کاربری، تغییر نام | گوگل هنگاوتس پس از تغییر نام، تمام دعوتنامههای چت ذخیرهشده را حذف میکند. کاربر باید برای چت مجدد با دوستانش درخواست اجازه کند. نام کاربری قدیمی به عنوان نام مستعار ایمیل حفظ میشود تا در صورت تنظیمات ارسال ایمیل، تحویل مداوم ایمیل تضمین شود و به عنوان نام کاربری جدید در دسترس نخواهد بود. برای جزئیات مهم در مورد تأثیر تغییر نام کاربران، به مرکز راهنمای مدیریت مراجعه کنید. پس از تغییر نام، از عملیات حذف نام مستعار کاربر برای حذف نام مستعار ایمیل استفاده کنید. |
| کاربران در چندین دامنه | یک حساب Google Workspace میتواند شامل هر یک از دامنههای شما باشد. در یک حساب چند دامنهای، کاربران در یک دامنه میتوانند خدمات را با کاربران در دامنههای حسابهای دیگر به اشتراک بگذارند. اجزای چند دامنه عبارتند از:
|
| هشدارها، اعضای گروه | GROUP_CANNOT_CONTAIN_CYCLE – این API اجازه چرخه در عضویت گروهها را نمیدهد. برای مثال، اگر group1 عضو group2 باشد، group2 نمیتواند عضو group1 باشد. |