Directory API: Batas dan Kuota

Batas dan kuota melindungi infrastruktur Google dari proses otomatis yang menggunakan Directory API dengan cara yang tidak tepat. Permintaan yang berlebihan dari API dapat disebabkan oleh kesalahan ketik yang tidak berbahaya, atau mungkin disebabkan oleh sistem yang tidak dirancang secara efisien yang membuat panggilan API yang tidak perlu. Apa pun penyebabnya, pemblokiran traffic dari sumber tertentu setelah mencapai tingkat tertentu diperlukan untuk kesehatan sistem Google Workspace secara keseluruhan. Mode Izin memastikan bahwa tindakan developer tertentu tidak dapat berdampak negatif pada komunitas yang lebih luas.

Jika permintaan API Anda gagal, walaupun kemungkinannya kecil, API akan menampilkan kode status HTTP dan alasan terjadinya error. Selain itu, isi respons berisi deskripsi mendetail tentang penyebab error.

Daftar berikut menunjukkan kemungkinan kode error, alasan, deskripsi yang sesuai, dan tindakan yang disarankan untuk error yang disebabkan oleh tercapainya batas kuota.

Kode Alasan Deskripsi Tindakan yang Disarankan
403 userRateLimitExceeded Menunjukkan bahwa batas kapasitas pengguna telah terlampaui. Nilai default yang ditetapkan di Konsol Google Cloud adalah 2.400 kueri per menit per pengguna per project Google Cloud. Tingkatkan batas per pengguna dari halaman Kuota API Admin SDK pada project Google Cloud Anda, atau perlambat pengiriman permintaan menggunakan backoff eksponensial.
403 quotaExceeded Menunjukkan bahwa batas permintaan serentak untuk operasi tertentu telah tercapai. Coba lagi menggunakan back-off eksponensial. Anda perlu memperlambat kecepatan pengiriman permintaan.
429 rateLimitExceeded Menunjukkan bahwa batas permintaan serentak untuk operasi tertentu telah tercapai. Coba lagi menggunakan back-off eksponensial. Anda harus memperlambat kecepatan pengiriman permintaan. Batas ini berlaku per akun Google Workspace, bukan per klien API atau per pengguna. Batas ini tidak dapat ditingkatkan.

Mengimplementasikan Backoff Eksponensial

Backoff eksponensial adalah proses saat klien mencoba kembali permintaan yang gagal secara berkala dengan durasi yang semakin lama. Ini adalah strategi penanganan error standar untuk aplikasi jaringan. Penggunaan backoff eksponensial akan meningkatkan efisiensi penggunaan bandwidth, mengurangi jumlah permintaan yang diperlukan untuk mendapatkan respons yang berhasil, dan memaksimalkan throughput permintaan dalam lingkungan serentak.

Alur untuk mengimplementasikan backoff eksponensial sederhana adalah sebagai berikut.

  1. Membuat permintaan ke API
  2. Menerima respons error yang memiliki kode error yang dapat dicoba lagi
  3. Tunggu 1 dtk + random_number_milliseconds detik
  4. Coba lagi permintaan
  5. Menerima respons error yang memiliki kode error yang dapat dicoba lagi
  6. Tunggu 2 dtk + random_number_milliseconds detik
  7. Coba lagi permintaan
  8. Menerima respons error yang memiliki kode error yang dapat dicoba lagi
  9. Tunggu 4 dtk + random_number_milliseconds detik
  10. Coba lagi permintaan
  11. Menerima respons error yang memiliki kode error yang dapat dicoba lagi
  12. Waktu tunggu 8 dtk + random_number_milliseconds detik
  13. Coba lagi permintaan
  14. Menerima respons error yang memiliki kode error yang dapat dicoba lagi
  15. Tunggu 16 dtk + random_number_milliseconds detik
  16. Coba lagi permintaan
  17. Jika masih mengalami error, hentikan dan catat error tersebut ke dalam log.

Pada alur di atas, random_number_milliseconds adalah angka acak milidetik yang kurang dari atau sama dengan 1.000. Hal ini diperlukan untuk menghindari error penguncian tertentu dalam beberapa implementasi serentak. random_number_milliseconds harus ditetapkan ulang setelah setiap periode tunggu.

Catatan: waktu tunggu selalu (2 ^ n) + random_number_milliseconds, dengan n adalah bilangan bulat yang meningkat secara monoton yang awalnya ditentukan sebagai 0. n bertambah 1 untuk setiap iterasi (setiap permintaan).

Algoritma disetel untuk dihentikan jika n adalah 5. Batas ini hanya diterapkan agar klien tidak terus mencoba tanpa batas, dan mengakibatkan penundaan total sekitar 32 detik sebelum permintaan dianggap "error yang tidak dapat dipulihkan". Klien API Anda dapat mengimplementasikan jumlah upaya yang lebih tinggi jika diperlukan.

Batas dan Kuota API

Kategori Batas API Batas
Membuat pengguna Anda tidak dapat membuat lebih dari 10 pengguna per domain per detik menggunakan Directory API.
Grup ditambahkan sebagai anggota ke grup lain Mungkin ada penundaan hingga 10 menit sebelum anggota grup turunan muncul sebagai anggota grup induk. Batas ini dapat berubah tergantung pada kapasitas sistem.
Perangkat seluler

Dengan Directory API, Anda dapat melakukan hingga:

  • 20 permintaan tindakan per detik.
  • 20 permintaan penghapusan per detik.
  • 10 permintaan get per detik.
  • 10 permintaan daftar per detik.
Mengganti nama pengguna Diperlukan waktu hingga 10 menit untuk diterapkan di seluruh layanan. Sebelum mengganti nama pengguna, sebaiknya logout pengguna dari semua sesi dan layanan browser. Untuk mengetahui detail selengkapnya, lihat Memperbarui pengguna.
Membuat/memperbarui Unit Organisasi
  • Anda tidak dapat membuat/memperbarui lebih dari 1 unit organisasi per pelanggan per detik menggunakan Directory API.
  • Hierarki unit organisasi pelanggan dibatasi hingga 35 tingkat.
  • Jumlah total unit organisasi per pelanggan tidak boleh lebih dari 40.000.
Kategori Kuota API Kuota
Perangkat Chrome annotatedLocation, maks karakter Jumlah karakter maksimum untuk informasi lokasi perangkat adalah 200.
Perangkat Chrome notes, maks karakter Jumlah karakter maksimum untuk informasi catatan perangkat adalah 500.
Perangkat Chrome, maksimum user karakter Jumlah karakter maksimum untuk nama pengguna perangkat adalah 100.
Alias domain, maksimum Jumlah maksimum alias domain adalah 20.
Grup, deskripsi Jumlah karakter maksimum dalam deskripsi adalah 4.096.
Grup, per akun Dengan akun G Suite Edisi Gratis Versi Lama, jumlah grup dibatasi hingga 10 grup. Edisi lainnya tidak membatasi jumlah grup.
Grup, anggota per grup Dengan akun G Suite Edisi Gratis Versi Lama, grup dapat berisi hingga 100 anggota. Edisi lainnya tidak membatasi jumlah anggota yang dapat dimiliki sebuah grup. Untuk batas keanggotaan grup per pengguna, lihat Memahami kebijakan dan batas Grup
String kueri maxResults API akan menampilkan:
  • Chrome dan perangkat seluler – Default dan maksimum 100 entri per halaman.
  • Grup dan anggota grup – Entri default dan maksimum 200 per halaman.
  • Pengguna – Default 100 entri dan maksimum 500 entri per halaman.
Alias pengguna dan resource unit organisasi tidak menggunakan penomoran halaman respons. Semua email utama pengguna ditampilkan dalam urutan abjad dan urutan respons tidak peka huruf besar/kecil.
Beberapa domain, jumlah domain maksimum yang diizinkan di satu akun 600 (1 domain primer + 599 domain tambahan)
Unit Organisasi, jumlah maksimum pengguna yang dipindahkan dalam satu waktu 20 pengguna dapat dipindahkan sekaligus. Selain itu, alamat email primer pengguna harus sudah ada di akun tersebut.
Alias pengguna Jumlah total alias yang diizinkan untuk setiap akun pengguna adalah 30.
Alias pengguna, menggunakan alias yang dihapus Alias pengguna yang dihapus dapat segera digunakan lagi.

Jenis Batas Lainnya Batasan dan Pedoman
Menagih dan membuat pengguna Bagi pengguna yang menggunakan paket fleksibel untuk Google Workspace, membuat pengguna menggunakan API ini akan memiliki dampak keuangan, dan akan menimbulkan tagihan pada akun penagihan pelanggan Anda. Misalnya, jika Anda menggunakan paket fleksibel untuk Google Workspace, pembuatan 10 pengguna akan menimbulkan tagihan untuk 10 lisensi Google Workspace yang diposting ke akun Anda, prorata sejak saat pembuatan selesai. Jika menggunakan paket tahunan, Anda sudah berkomitmen untuk membayar sejumlah lisensi di awal, dan Anda hanya dapat membuat pengguna sebanyak mungkin sesuai komitmen. Untuk informasi selengkapnya tentang paket penagihan dan akun penagihan, lihat pusat bantuan administrasi.
Nama Depan dan Belakang Nama depan dan belakang maksimal 40 karakter. Karakter tersebut mendukung karakter Unicode/UTF-8, dan dapat berisi spasi, huruf (a-z), angka (0-9), tanda hubung (-), garis miring (/), dan titik (.). Untuk informasi selengkapnya tentang aturan penggunaan karakter, lihat pusat bantuan administrasi.
Grup, menghapus Menghapus grup tidak akan menghapus akun pengguna anggota grup tersebut.
Grup dan anggota grup, perubahan alamat email Dalam versi API ini, alamat email grup dapat diubah sebelum layanan Google Workspace diaktifkan. Gunakan konsol Admin untuk mengubah alamat email anggota grup. Setelah diubah, API secara otomatis mencerminkan perubahan alamat email.
Grup, setelan Setelan akses, opsi berbagi, pemantauan, dan arsip diskusi Grup dikelola menggunakan konsol Admin. Untuk informasi selengkapnya tentang setelan grup, lihat pusat bantuan administrasi.
Grup, mengirim pesan Untuk mencegah spam dan penyalahgunaan email, Google membatasi jumlah pesan yang dapat Anda kirim sekaligus kepada penerima eksternal. Jika Anda mengirim pesan ke grup, setiap anggota eksternal dihitung sebagai satu penerima. Untuk mengetahui informasi selengkapnya, lihat Batas pengiriman email dan Mencegah email ke pengguna Gmail diblokir atau dikirim ke spam .
Grup, mengirim pesan NDR Anda tidak dapat mengirim atau meneruskan laporan tidak terkirim (NDR), juga disebut "pesan email tidak terkirim", ke grup.
Grup yang dibuat oleh pengguna, batasan Untuk batas grup yang dibuat pengguna, lihat pusat bantuan administrasi
Unit Organisasi, mengaktifkan/menonaktifkan layanan Gunakan konsol Admin untuk mengelola cara mengaktifkan dan menonaktifkan layanan untuk unit organisasi.
Sandi Dapat berisi kombinasi karakter apa pun. Diperlukan minimal 8 karakter. Panjang maksimum adalah 100 karakter.
Foto Dalam versi API ini, foto adalah foto profil Google terbaru milik pengguna.
Nama pengguna Nama pengguna dapat berisi huruf (a-z), angka (0-9), tanda hubung (-), garis bawah (_), dan Google Workspace mengenali titik atau titik (.). Ini tidak sama dengan Gmail. Nama pengguna tidak boleh berisi tanda sama dengan (=), tanda kurung (<,>), atau lebih dari satu titik (.) secara berturut-turut. Untuk informasi selengkapnya, lihat pusat bantuan administrasi.
Nama pengguna, mengganti nama Google Hangouts menghapus semua undangan chat yang diingat setelah mengganti nama. Pengguna harus meminta izin untuk melakukan chat dengan teman lagi. Nama pengguna lama tetap digunakan sebagai alias email untuk memastikan pengiriman email berkelanjutan saat setelan penerusan email dilakukan dan tidak akan tersedia sebagai nama pengguna baru. Untuk mengetahui detail penting tentang dampak penggantian nama pengguna, lihat pusat bantuan administrasi. Gunakan operasi Hapus alias pengguna untuk menghapus alias email setelah mengganti nama.
Pengguna di beberapa domain Akun Google Workspace dapat menyertakan semua domain Anda. Di akun beberapa domain, pengguna di satu domain dapat berbagi layanan dengan pengguna di domain akun lain. Beberapa komponen domain:
  • Domain primer -- Domain primer akun Anda adalah domain administrator yang menyetujui perjanjian Persyaratan Layanan Google Workspace. Domain ini berada di tingkat akun di unit organisasi tingkat teratas. Saat mendaftar akun Google Workspace, sebaiknya gunakan domain bisnis Anda untuk domain primer, dan cadangkan domain Anda lainnya untuk penggunaan khusus seperti uji coba dan pengujian.
    • Semua administrator super dapat mengelola akun lengkap.
    • API tidak dapat mengubah atau memindahkan domain primer akun Google Workspace. Namun, API tersebut dapat mengganti nama akun pengguna, mengubah alamat emailnya dari satu domain ke domain lain.
    • Untuk akun Google Workspace, Anda memiliki waktu 21 hari untuk memverifikasi kepemilikan domain primer. Untuk domain tambahan, Anda harus memverifikasi kepemilikan domain sebelum menggunakan domain untuk alamat email primer pengguna. Dalam kasus ini, masa tenggang 21 hari tidak berlaku.
    • Dalam versi API ini, setelan domain primer berlaku untuk semua domain yang dikaitkan dengan akun tersebut, kecuali untuk akses pengguna ke layanan Google Workspace.
  • Domain akun tambahan -- Setelah membuat domain primer dan menyiapkan akun, Anda dapat menambahkan domain tambahan ke akun. Untuk domain tambahan, verifikasi kepemilikan Anda saat menyiapkan domain ini dan sebelum menggunakan domain untuk alamat email primer pengguna.
  • Domain beranda pengguna -- Domain yang digunakan di alamat email primer pengguna adalah domain beranda pengguna. Domain ini dapat berupa domain apa pun di akun, termasuk domain primer.
Untuk mengetahui batasan beberapa domain terbaru, lihat beberapa batasan domain. Hal ini termasuk informasi untuk alias domain, penggabungan akun, dll.
Peringatan, anggota grup GROUP_CANNOT_CONTAIN_CYCLE – API tidak mengizinkan siklus dalam keanggotaan grup. Misalnya, jika grup1 adalah anggota grup2, grup2 tidak dapat menjadi anggota grup1.