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 dapat disebabkan oleh sistem yang dirancang secara tidak efisien sehingga melakukan panggilan API yang tidak perlu. Terlepas dari penyebabnya, memblokir traffic dari sumber tertentu setelah mencapai tingkat tertentu diperlukan untuk kesehatan keseluruhan sistem Google Workspace. Hal ini memastikan bahwa tindakan satu developer tidak dapat berdampak negatif pada komunitas yang lebih besar.

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

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

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 project Google Cloud Anda, atau perlambat kecepatan pengiriman permintaan menggunakan penundaan eksponensial.
403	quotaExceeded	Menunjukkan bahwa batas permintaan serentak untuk operasi tertentu telah tercapai.	Coba lagi menggunakan backoff eksponensial. Anda perlu memperlambat kecepatan pengiriman permintaan.
429	rateLimitExceeded	Menunjukkan bahwa batas permintaan serentak untuk operasi tertentu telah tercapai.	Coba lagi menggunakan backoff 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.

Menerapkan Backoff Eksponensial

Backoff eksponensial adalah proses klien yang secara berkala mencoba lagi permintaan yang gagal selama periode waktu 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 detik + random_number_milliseconds detik
4. Coba lagi permintaan
5. Menerima respons error yang memiliki kode error yang dapat dicoba lagi
6. Tunggu 2 detik + random_number_milliseconds detik
7. Coba lagi permintaan
8. Menerima respons error yang memiliki kode error yang dapat dicoba lagi
9. Tunggu 4 detik + random_number_milliseconds detik
10. Coba lagi permintaan
11. Menerima respons error yang memiliki kode error yang dapat dicoba lagi
12. Tunggu 8 detik + random_number_milliseconds detik
13. Coba lagi permintaan
14. Menerima respons error yang memiliki kode error yang dapat dicoba lagi
15. Tunggu 16 detik + random_number_milliseconds detik
16. Coba lagi permintaan
17. Jika Anda masih mendapatkan error, hentikan dan catat error.

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

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

Algoritma disetel untuk dihentikan jika n adalah 5. Batas ini hanya diterapkan untuk menghentikan klien agar tidak terus mencoba tanpa batas, dan mengakibatkan penundaan total sekitar 32 detik sebelum permintaan dianggap "error yang tidak dapat dipulihkan". Klien API Anda dapat menerapkan jumlah percobaan 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 bergantung pada kapasitas sistem.
Perangkat seluler	Dengan Directory API, Anda dapat melakukan hingga: 20 permintaan tindakan per detik. 20 permintaan hapus per detik. 10 permintaan get per detik. 10 permintaan daftar per detik.
Mengganti nama pengguna	Mungkin perlu waktu hingga 10 menit untuk diterapkan di semua 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 kedalaman. Jumlah total unit organisasi per pelanggan tidak boleh melebihi 40.000.
Kategori Kuota API	Kuota
Perangkat Chrome annotatedLocation, jumlah karakter maksimum	Jumlah karakter maksimum untuk informasi lokasi perangkat adalah 200.
Perangkat Chrome notes, jumlah karakter maksimum	Jumlah maksimum karakter untuk informasi catatan perangkat adalah 500.
Perangkat Chrome, maksimal user karakter	Jumlah maksimum karakter untuk nama pengguna perangkat adalah 100.
Alias domain, maksimum	Jumlah maksimum alias domain adalah 20.
Grup, deskripsi	Jumlah maksimum karakter dalam deskripsi adalah 4.096.
Grup, per akun	Dengan akun G Suite Edisi Gratis Versi Lama, jumlah grup dibatasi hingga 10. Edisi lainnya tidak memiliki batas jumlah grup.
Grup, anggota per grup	Dengan akun G Suite Edisi Gratis Lama, grup dapat berisi hingga 100 anggota. Edisi lainnya tidak memiliki batasan jumlah anggota yang dapat dimiliki grup. Untuk batas keanggotaan grup per pengguna, lihat Memahami kebijakan dan batas Grup
String kueri maxResults	API menampilkan: Chrome dan perangkat seluler – Default dan maksimum 100 entri per halaman. Grup dan anggota grup – Default dan maksimum 200 entri per halaman. Pengguna – Default 100 entri dan maksimum 500 entri per halaman. Resource alias pengguna dan 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 maksimum domain yang diizinkan dalam satu akun	600 (1 domain primer + 599 domain tambahan)
Unit Organisasi, jumlah maksimum pengguna yang dipindahkan sekaligus	20 pengguna dapat dipindahkan sekaligus. Selain itu, alamat email utama pengguna harus sudah ada di akun.
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 kembali.

Jenis Batas Lainnya	Batasan dan Pedoman
Penagihan dan pembuatan pengguna	Untuk pengguna yang menggunakan paket fleksibel untuk Google Workspace, pembuatan pengguna menggunakan API ini akan berdampak pada keuangan, dan akan menimbulkan biaya pada akun penagihan pelanggan Anda. Misalnya, jika Anda menggunakan paket fleksibel untuk Google Workspace, membuat 10 pengguna akan menyebabkan tagihan untuk 10 lisensi Google Workspace diposting ke akun Anda, yang dihitung secara pro-rata dari waktu pembuatan. Jika menggunakan paket tahunan, Anda sudah berkomitmen untuk membayar sejumlah lisensi tertentu di muka, dan Anda hanya dapat membuat pengguna sebanyak yang sesuai dengan komitmen Anda. Untuk mengetahui informasi selengkapnya tentang paket penagihan dan akun penagihan Anda, lihat pusat bantuan administrasi.
Nama Depan dan Belakang	Nama depan dan belakang memiliki maksimum 40 karakter. Nama ini mendukung karakter Unicode/UTF-8, dan dapat berisi spasi, huruf (a-z), angka (0-9), tanda hubung (-), garis miring (/), dan titik (.). Untuk mengetahui informasi selengkapnya tentang aturan penggunaan karakter, lihat pusat bantuan administrasi.
Grup, menghapus	Menghapus grup tidak akan menghapus akun pengguna anggota grup.
Grup dan anggota grup, perubahan alamat email	Dalam versi API ini, alamat email grup dapat diubah sebelum layanan Google Workspace diaktifkan. Gunakan konsol Google Admin untuk mengubah alamat email anggota grup. Setelah diubah, API akan otomatis mencerminkan perubahan alamat email.
Grup, setelan	Setelan akses grup, opsi berbagi, pemantauan, dan arsip diskusi dikelola menggunakan konsol Google Admin. Untuk mengetahui 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 mengetahui batas grup yang dibuat pengguna, lihat pusat bantuan administrasi
Unit Organisasi, mengaktifkan/menonaktifkan layanan	Gunakan konsol Google Admin untuk mengelola pengaktifan dan penonaktifan 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 pengguna.
Nama pengguna	Nama pengguna dapat berisi huruf (a-z), angka (0-9), tanda hubung (-), garis bawah (_), dan Google Workspace mengenali titik (.). Hal ini tidak sama dengan Gmail. Nama pengguna tidak boleh berisi tanda sama dengan (=), tanda kurung (<,>), atau lebih dari satu titik (.) secara berturut-turut. Untuk mengetahui informasi selengkapnya, lihat pusat bantuan administrasi.
Nama pengguna, mengganti nama	Google Hangouts akan menghapus semua undangan chat yang diingat setelah mengganti nama. Pengguna harus meminta izin untuk melakukan chat dengan teman lagi. Nama pengguna lama dipertahankan sebagai alias email untuk memastikan pengiriman email terus berlanjut dalam kasus setelan penerusan email 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 mencakup domain Anda. Di akun multi-domain, pengguna di satu domain dapat berbagi layanan dengan pengguna di domain akun lain. Komponen beberapa domain adalah: Domain utama -- Domain utama 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 utama, dan cadangkan domain lainnya untuk penggunaan khusus seperti uji coba dan pengujian. Semua administrator super dapat mengelola akun sepenuhnya. API tidak dapat mengubah atau memindahkan domain primer akun Google Workspace. Namun, API 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 utama Anda. Untuk domain tambahan, Anda harus memverifikasi kepemilikan domain sebelum menggunakan domain untuk alamat email utama pengguna. Dalam kasus ini, masa tenggang 21 hari tidak berlaku. Dalam versi API ini, setelan domain utama berlaku untuk semua domain yang terkait dengan akun, kecuali akses pengguna ke layanan Google Workspace. Domain akun tambahan -- Setelah menetapkan domain utama dan menyiapkan akun, Anda dapat menambahkan domain tambahan ke akun. Untuk domain tambahan, verifikasi kepemilikan Anda saat menyiapkan domain ini dan sebelum menggunakan domain tersebut untuk alamat email utama pengguna. Domain asal pengguna -- Domain yang digunakan dalam alamat email utama pengguna adalah domain asal pengguna. Domain ini dapat berupa domain apa pun di akun, termasuk domain primer. Untuk mengetahui batasan beberapa domain terbaru, lihat batasan beberapa domain. Hal ini mencakup informasi untuk alias domain, penggabungan akun, dll.
Peringatan, anggota grup	GROUP_CANNOT_CONTAIN_CYCLE – API tidak mengizinkan siklus dalam keanggotaan grup. Misalnya, jika group1 adalah anggota group2, group2 tidak dapat menjadi anggota group1.