Batas dan kuota API

Google Ads API menerapkan batasan pada operasi API, seperti jumlah operasi yang dapat dikirim dalam satu permintaan modifikasi. Tabel berikut merangkum beberapa batasan dan kuota penting yang perlu diperhatikan.

Jenis permintaan, batasan, dan kode error
Operasi dengan tingkat akses Test 15.000 operasi API per hari terhadap akun pengujian RESOURCE_EXHAUSTED
Operasi dengan tingkat akses Penjelajah 2.880 operasi API per hari terhadap akun produksi
15.000 operasi API per hari terhadap akun pengujian 		RESOURCE_EXHAUSTED
Operasi dengan tingkat akses Dasar 15.000 operasi API per hari untuk akun pengujian dan produksi RESOURCE_EXHAUSTED
Operasi dengan tingkat akses Standar Operasi API tanpa batas per hari untuk akun pengujian dan produksi T/A
Permintaan modifikasi 10.000 operasi mutasi per permintaan TOO_MANY_MUTATE_OPERATIONS
Permintaan Layanan Perencanaan 1 QPS RESOURCE_EXHAUSTED
Permintaan Conversion Upload Service 2.000 konversi per permintaan TOO_MANY_CONVERSIONS_IN_REQUEST
Permintaan Billing and Account Budget Service 1 operasi per permintaan modifikasi TOO_MANY_MUTATE_OPERATIONS

Batas operasi API harian

Batas penggunaan API harian didasarkan pada jumlah operasi API yang dilakukan oleh project Google Cloud Anda. Operasi API adalah jumlah total permintaan Search dan SearchStream, operasi mutasi individual, dan permintaan layanan lainnya. Batas untuk operasi API harian bergantung pada tingkat akses API project Google Cloud Anda. Panduan tingkat akses dan penggunaan yang diizinkan menguraikan batas operasi API tertentu untuk setiap tingkat akses.

Permintaan yang melanggar batas ini akan ditolak dengan error: RESOURCE_EXHAUSTED.

Batasan gRPC

Semua library klien Google Ads API menggunakan gRPC untuk membuat permintaan dan respons. Secara default, gRPC memiliki ukuran pesan 4 MB, tetapi library klien kami menetapkan ukuran pesan maksimum ke 64 MB untuk meningkatkan efisiensi.

Respons tidak boleh melebihi batas ini. Misalnya, permintaan penelusuran yang menyertakan banyak kolom dapat menghasilkan respons yang ukurannya melebihi 64 MB. Untuk menghindari batas ini, Anda dapat mengurangi jumlah kolom yang dipilih, atau menggunakan streaming. Untuk mutasi, kirim lebih sedikit operasi per permintaan.

Permintaan yang melanggar batasan ini tidak akan menghasilkan GoogleAdsError, tetapi akan menghasilkan error RESOURCE_EXHAUSTED (kode gRPC 8 / HTTP 429). Lihat daftar kode dan pesan error gRPC.

Permintaan modifikasi

Selain mengurangi kuota operasi harian pengguna, permintaan modifikasi tidak boleh berisi lebih dari 10.000 operasi modifikasi per permintaan. Permintaan yang melanggar batasan ini akan ditolak dengan error: TOO_MANY_MUTATE_OPERATIONS.

Batasan dan pertimbangan tambahan untuk layanan dan jenis permintaan tertentu diuraikan berikutnya.

Telusuri permintaan

Permintaan Search atau SearchStream dihitung sebagai satu operasi terhadap kuota operasi harian pengguna. Satu permintaan SearchStream dihitung sebagai satu operasi API, terlepas dari jumlah batch.

Permintaan yang diberi nomor halaman

Permintaan yang diberi nomor halaman (misalnya, permintaan yang berisi next_page_token yang valid) tidak mengurangi kuota operasi harian pengguna. Namun, permintaan penomoran halaman yang berisi token halaman yang sudah tidak berlaku atau tidak valid akan menghasilkan pengecualian dan akan mengurangi kuota operasi harian.

Untuk mengetahui detail selengkapnya tentang penomoran halaman, lihat Penomoran halaman melalui hasil.

Jenis permintaan lainnya

Permintaan yang bukan permintaan Mutate, Search, atau SearchStream dihitung sebagai satu operasi terhadap kuota operasi harian pengguna.

Beberapa contoh permintaan tersebut mencakup:

Permintaan yang menampilkan pengecualian API

Permintaan yang ditolak dengan GoogleAdsFailure tetap diperhitungkan dalam kuota operasi harian pengguna.

Permintaan yang gagal, tetapi tidak menampilkan GoogleAdsFailure, seperti dari error di tingkat jaringan, tidak akan mengurangi kuota operasi harian pengguna karena permintaan tersebut tidak akan pernah mencapai layanan. Contohnya adalah kegagalan konektivitas jaringan.

Layanan perencanaan kata kunci

Karena biaya dan kompleksitas, metode layanan Perencanaan Kata Kunci berikut tunduk pada batas yang terpisah dari jenis permintaan lainnya.

Perhatikan batasan ini saat membuat rencana kata kunci.

Objek rencana kata kunci Jumlah maksimum
KeywordPlan per akun 10.000
KeywordPlanAdGroup per KeywordPlan 200
KeywordPlanAdGroupKeyword per KeywordPlan 10.000
KeywordPlanCampaignKeyword (kata kunci negatif) per KeywordPlan 1.000
KeywordPlanCampaign per KeywordPlan 1

Layanan analisis audiens

Metode berikut dalam AudienceInsightsService tunduk pada batas kuota tertentu.

Layanan upload konversi

Layanan upload penyesuaian konversi

Aturan nilai konversi

Jika ConversionValueRuleSet dengan attachment_type CUSTOMER sudah ada untuk akun, Anda harus menambahkan aturan nilai konversi baru ke kumpulan tersebut agar aktif. Jika set aturan nilai konversi tersebut tidak ada, Anda harus membuatnya dan menambahkan aturan nilai konversi ke set aturan tersebut seperti yang dijelaskan di bagian Membuat set aturan.

Layanan anggaran akun dan penagihan

  • Mutasi hanya dapat dilakukan terhadap akun yang dikonfigurasi untuk invoice bulanan.

    Permintaan yang melanggar batasan ini akan ditolak dengan error: MUTATE_NOT_ALLOWED.

  • Hanya 1 operasi yang diizinkan untuk permintaan modifikasi.

    Permintaan yang melanggar batasan ini akan ditolak dengan error: TOO_MANY_MUTATE_OPERATIONS.

  • Anda harus menunggu setidaknya 12 jam antara perubahan anggaran akun (AccountBudget atau AccountBudgetProposal) pada akun yang sama. Melakukan perubahan sebelum 12 jam berlalu dapat mengakibatkan kegagalan yang tidak dapat dipulihkan dan hanya dapat diselesaikan oleh perwakilan akun Google Ads Anda.

Undangan ke akun pelanggan

Pengguna baru dapat diundang ke akun klien yang ada dengan CustomerUserAccessInvitationService. Karena fitur ini mengirimkan email undangan kepada pengguna lain, fitur ini berpotensi disalahgunakan, sehingga ada batasan untuk perilakunya:

  • Pengguna tidak dapat menerima lebih dari satu undangan yang tertunda untuk akun klien yang sama. Jika permintaan berikutnya dibuat untuk mengirim undangan kepada pengguna yang sudah memiliki undangan yang menunggu keputusan, error ini akan ditampilkan: EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.

  • Akun klien tidak boleh memiliki lebih dari 70 undangan yang menunggu keputusan sekaligus. Jika permintaan yang dikirim menyebabkan nilai ini terlampaui, error ini akan ditampilkan: PENDING_INVITATIONS_LIMIT_EXCEEDED.

Data pengguna

Data pengguna dikelola dengan UserDataService dan OfflineUserDataJobService.

Setiap objek UserData dalam operasi create atau remove berkaitan dengan satu pengguna akhir. Kolom user_identifiers dalam satu objek UserData dibatasi hingga maksimum 20 ID. Jika batas ini terlampaui dalam satu objek UserData, akan terjadi error OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS atau UserDataError.TOO_MANY_USER_IDENTIFIERS.

Menangani pengguna dengan lebih dari 20 ID

Jika satu pengguna akhir memiliki lebih dari 20 ID yang perlu Anda upload, Anda harus mendistribusikan ID ini ke beberapa objek UserData. Untuk memastikan Google dapat mengaitkan semua ID ini dengan pengguna akhir yang sama, setiap objek UserData untuk pengguna tersebut harus menyertakan setidaknya satu user_identifier umum, seperti hashed_email, hashed_phone_number, atau third_party_user_id yang sama. Google menggunakan ID bersama ini untuk menautkan dan menggabungkan informasi dari operasi UserData terpisah ke profil pengguna akhir yang benar.

Jika Anda mengandalkan PII seperti email atau nomor telepon yang di-hash, pastikan data tersebut dinormalisasi dan di-hash sesuai dengan persyaratan Google Ads API (SHA-256, huruf kecil, tanpa spasi) untuk mencegah kegagalan penautan.

Misalnya, jika pengguna memiliki 30 alamat email, Anda dapat mengirim dua objek UserData yang memiliki third_party_user_id yang sama (menempatkan thirdPartyUserId ditambah email 1 hingga 19 di objek pertama agar tetap berada dalam batas 20 ID, dan thirdPartyUserId ditambah email 20 hingga 30 di objek kedua):

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_1" },
    // Hashed emails 2 through 18 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_19" }
  ]
}

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_20" },
    // Hashed emails 21 through 29 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_30" }
  ]
}

Batas total untuk user_identifiers di semua operasi dalam satu AddOfflineUserDataJobOperationsRequest adalah 100.000 (OfflineUserDataJob dapat menerima beberapa panggilan AddOfflineUserDataJobOperationsRequest, hingga maksimum yang direkomendasikan, yaitu 1.000.000 operasi per tugas). Untuk upload sinkron menggunakan UploadUserDataRequest (UserDataService.UploadUserData), setiap permintaan dibatasi hingga maksimum 10 operasi dan 100 user_identifiers di seluruh permintaan.

Jenis batas lainnya

Kolom berulang, seperti daftar operasi, yang memiliki terlalu banyak item dalam permintaan dapat menimbulkan error: REQUEST_SIZE_LIMIT_EXCEEDED. Pesan error yang sama ini juga dapat disebabkan oleh masalah lain.

Jika Anda mengalami batasan ini dan membuat permintaan yang menggunakan kolom berulang, coba kurangi jumlah item di kolom berulang dengan membagi daftar operasi di beberapa permintaan modifikasi.

Saat membuat kueri GAQL, jumlah maksimum item dalam klausa IN adalah 20.000. Jika Anda melebihi batas tersebut, error FILTER_HAS_TOO_MANY_VALUES akan ditampilkan.

Sebelumnya
Ringkasan
Berikutnya
Batas sistem