ขีดจำกัด API และโควต้า

Google Ads API บังคับใช้ขีดจํากัดในการดำเนินการ API เช่น จํานวนการดำเนินการ ที่ส่งได้ในคําขอเปลี่ยนแปลงข้อมูลในเซิร์ฟเวอร์รายการเดียว ตารางต่อไปนี้สรุปข้อจำกัดและโควต้าที่สำคัญบางส่วนที่ควรทราบ

ประเภทคำขอ ข้อจำกัด และรหัสข้อผิดพลาด
การดำเนินการที่มีระดับการเข้าถึงทดสอบ	การดำเนินการ API 15,000 รายการต่อวันในบัญชีทดสอบ	RESOURCE_EXHAUSTED
การดำเนินการที่มีระดับการเข้าถึง Explorer	การดำเนินการ API 2,880 รายการต่อวันกับบัญชีที่ใช้งานจริง การดำเนินการ API 15,000 รายการต่อวันกับบัญชีทดสอบ	RESOURCE_EXHAUSTED
การดำเนินการที่มีระดับการเข้าถึงพื้นฐาน	การดำเนินการ API 15,000 รายการต่อวันกับทั้งบัญชีทดสอบและบัญชีจริง	RESOURCE_EXHAUSTED
การดำเนินการที่มีสิทธิ์การเข้าถึงระดับมาตรฐาน	การดำเนินการ API ไม่จำกัดต่อวันกับทั้งบัญชีทดสอบและบัญชีจริง	ไม่มี
คำขอเปลี่ยนแปลง	การดำเนินการเปลี่ยนแปลง 10,000 รายการต่อคำขอ	TOO_MANY_MUTATE_OPERATIONS
คำขอวางแผนบริการ	1 QPS	RESOURCE_EXHAUSTED
คำขอของบริการอัปโหลด Conversion	Conversion 2,000 รายการต่อคำขอ	TOO_MANY_CONVERSIONS_IN_REQUEST
คำขอการเรียกเก็บเงินและบริการงบบัญชี	1 การดำเนินการต่อคำขอเปลี่ยนแปลงข้อมูลในเซิร์ฟเวอร์	TOO_MANY_MUTATE_OPERATIONS

ขีดจำกัดการดำเนินการ API ต่อวัน

ขีดจำกัดการใช้งาน API ต่อวันจะอิงตามจำนวนการดำเนินการ API ที่โปรเจ็กต์ที่อยู่ในระบบคลาวด์ Google ของคุณทำ การดำเนินการ API คือผลรวมทั้งหมดของคำขอ Search และ SearchStream การดำเนินการเปลี่ยนแปลงแต่ละรายการ และคำขออื่นๆ ของบริการ ขีดจำกัดสำหรับการดำเนินการ API รายวันจะขึ้นอยู่กับ ระดับการเข้าถึง API ของโปรเจ็กต์ Google Cloud ระดับการเข้าถึงและ คู่มือการใช้งานที่อนุญาตจะระบุขีดจํากัดการดําเนินการของ API สําหรับระดับการเข้าถึงแต่ละระดับ

คำขอที่ละเมิดขีดจำกัดเหล่านี้จะถูกปฏิเสธโดยมีข้อผิดพลาด RESOURCE_EXHAUSTED

ข้อจำกัดของ gRPC

ไลบรารีของไคลเอ็นต์ทั้งหมดของ Google Ads API ใช้ gRPC สำหรับ การสร้างคำขอและการตอบกลับ โดยค่าเริ่มต้น gRPC มีขนาดข้อความ 4 MB แต่ไลบรารีไคลเอ็นต์ของเราตั้งค่าขนาดข้อความสูงสุดเป็น 64 MB เพื่อเพิ่มประสิทธิภาพ

คำตอบต้องไม่เกินขีดจำกัดนี้ เช่น คำขอค้นหาที่มีฟิลด์จำนวนมากอาจสร้างการตอบกลับที่มีขนาดเกิน 64 MB หากต้องการหลีกเลี่ยงขีดจำกัดนี้ คุณสามารถลดจำนวนฟิลด์ที่เลือก หรือใช้การสตรีม สำหรับการเปลี่ยนแปลง ให้ส่งการดำเนินการต่อคำขอน้อยลง

คำขอที่ละเมิดข้อจำกัดนี้จะไม่สร้าง GoogleAdsError แต่จะสร้างข้อผิดพลาด RESOURCE_EXHAUSTED (รหัส gRPC 8 / HTTP 429) ดูรายการรหัสและข้อความแสดงข้อผิดพลาดของ gRPC

คำขอเปลี่ยนแปลง

นอกเหนือจากการนับรวมในโควต้าการดำเนินการรายวันของผู้ใช้แล้ว คำขอ mutate ต้องมีการดำเนินการ mutate ไม่เกิน 10,000 รายการต่อคำขอ คำขอที่ละเมิดข้อจำกัดนี้จะถูกปฏิเสธโดยมีข้อผิดพลาด TOO_MANY_MUTATE_OPERATIONS

ข้อจำกัดและการพิจารณาเพิ่มเติมสำหรับบริการและคำขอประเภทต่างๆ ระบุไว้ในส่วนถัดไป

คำขอค้นหา

คำขอ Search หรือ SearchStream จะนับเป็นการดำเนินการ 1 รายการเทียบกับ โควต้าการดำเนินการรายวันของผู้ใช้ SearchStream คำขอ 1 รายการจะนับเป็นการดำเนินการ API 1 รายการ ไม่ว่าจะมีจำนวนกลุ่มเท่าใด

คำขอแบบแบ่งหน้า

ระบบจะไม่นับคำขอที่มีการแบ่งหน้า (เช่น คำขอที่มี next_page_tokenที่ถูกต้อง) รวมกับโควต้าการดำเนินการรายวันของผู้ใช้ อย่างไรก็ตาม คำขอการแบ่งหน้าที่มีโทเค็นหน้าที่หมดอายุหรือไม่ถูกต้องจะ สร้างข้อยกเว้นและจะนับรวมในโควต้าการดำเนินการรายวัน

ดูรายละเอียดเพิ่มเติมเกี่ยวกับการแบ่งหน้าได้ที่การแบ่งหน้าผ่านผลลัพธ์

คำขอประเภทอื่นๆ

คำขอที่ไม่ใช่คำขอ Mutate, Search หรือ SearchStream จะนับเป็นการดำเนินการ 1 รายการเทียบกับโควต้าการดำเนินการรายวันของผู้ใช้

ตัวอย่างคำขอดังกล่าวมีดังนี้

• BatchJobService.ListBatchJobResults
• ConversionUploadService.UploadCallConversions
• ConversionUploadService.UploadClickConversions
• OfflineUserDataJobService.AddOfflineUserDataJobOperations
• OfflineUserDataJobService.CreateOfflineUserDataJob
• UserDataService.UploadUserData

คำขอที่แสดงข้อยกเว้นของ API

คำขอที่ถูกปฏิเสธพร้อมด้วย GoogleAdsFailure จะยังคง นับรวมในโควต้าการดำเนินการรายวันของผู้ใช้

คำขอที่ไม่สำเร็จแต่ไม่ได้ส่งกลับ GoogleAdsFailure เช่น จากข้อผิดพลาดที่ระดับเครือข่าย จะไม่นับรวมในโควต้าการดำเนินการรายวันของผู้ใช้ เนื่องจากคำขอจะไม่ไปถึงบริการ ตัวอย่างของ ปัญหานี้คือการเชื่อมต่อเครือข่ายล้มเหลว

บริการวางแผนคีย์เวิร์ด

เนื่องจากต้นทุนและความซับซ้อน วิธีการบริการการวางแผนคีย์เวิร์ดต่อไปนี้จึงมี ขีดจำกัดแยกต่างหากจากคำขอประเภทอื่นๆ

• จำกัดไว้ที่ 1 คำขอต่อวินาทีต่อ CID

  • KeywordPlanIdeaService.GenerateKeywordIdeas
  • KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics
  • KeywordPlanIdeaService.GenerateKeywordForecastMetrics

  คำขอที่ละเมิดข้อจำกัดเหล่านี้จะถูกปฏิเสธโดยมีข้อผิดพลาด RESOURCE_EXHAUSTED

• 1 QPS จะคำนวณเป็นคำขอ 60 รายการต่อ 60 วินาที

• จำกัดไว้ที่ 2 คำขอต่อวินาทีต่อ CID

  • KeywordPlanIdeaService.GenerateAdGroupThemes

โปรดคำนึงถึงขีดจำกัดเหล่านี้เมื่อสร้างแผนคีย์เวิร์ด

ออบเจ็กต์แผนคีย์เวิร์ด	จำนวนสูงสุด
KeywordPlan ต่อบัญชี	10,000
KeywordPlanAdGroup ต่อ KeywordPlan	200
KeywordPlanAdGroupKeyword ต่อ KeywordPlan	10,000
KeywordPlanCampaignKeyword (คีย์เวิร์ดเชิงลบ) ต่อ KeywordPlan	1,000
KeywordPlanCampaign ต่อ KeywordPlan	1

บริการข้อมูลเชิงลึกของกลุ่มเป้าหมาย

เมธอดต่อไปนี้ภายใน AudienceInsightsService มีโควต้า ที่เฉพาะเจาะจง

• จำกัดคำขอประมาณ 200 รายการต่อวันต่อ CID
  • AudienceInsightsService.GenerateAudienceCompositionInsights
  • AudienceInsightsService.GenerateSuggestedTargetingInsights
• จำกัดไว้ที่ 2 คำขอต่อวินาทีต่อโปรเจ็กต์ Google Cloud ดังนี้
  • AudienceInsightsService.GenerateTargetingSuggestionMetrics

บริการอัปโหลด Conversion

• จำกัด Conversion การโทรหรือการคลิกที่ 2,000 รายการต่อคำขอ

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

  คำขอที่ละเมิดขีดจำกัดเหล่านี้จะถูกปฏิเสธโดยมีข้อผิดพลาด TOO_MANY_CONVERSIONS_IN_REQUEST

หมายเหตุ: ตั้งแต่วันที่ 15 มิถุนายน 2026 เป็นต้นไป ConversionUploadService.UploadClickConversions จะถูกจํากัด สําหรับผู้ใช้ใหม่ (ผู้ใช้เดิม NotAllowlistedError.CUSTOMER_NOT_ALLOWLISTED_FOR_THIS_FEATURE) การผสานรวมการอัปโหลด Conversion ใหม่ต้องใช้ Data Manager API

บริการอัปโหลดการปรับ Conversion

• จำกัดการปรับ Conversion ไว้ที่ 2,000 รายการต่อคำขอ

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

  คำขอที่ละเมิดขีดจำกัดเหล่านี้จะถูกปฏิเสธโดยมีข้อผิดพลาด TOO_MANY_ADJUSTMENTS_IN_REQUEST

กฎมูลค่า Conversion

• จำกัดกฎมูลค่า Conversion 100,000 รายการต่อบัญชี

  ระบบจะปฏิเสธคำขอที่ละเมิดขีดจำกัดนี้โดยมีข้อผิดพลาด ResourceCountLimitExceededError.ACCOUNT_LIMIT

หมายเหตุ: กฎมูลค่า Conversion ที่สร้างขึ้นโดยใช้ Google Ads API จะทํางานก็ต่อเมื่อกฎดังกล่าว เป็นส่วนหนึ่งของชุดกฎมูลค่า Conversion ที่มีชื่อทรัพยากร ConversionValueRule ในฟิลด์ conversion_value_rules และมีสถานะ ConversionValueRuleSet ตั้งค่าเป็น ENABLED กฎมูลค่า Conversion ที่ไม่ได้เป็นส่วนหนึ่งของชุดกฎมูลค่า Conversion จะ ไม่ปรากฏใน UI ของ Google Ads และจะจัดการได้โดยใช้ API เท่านั้น

หากมีConversionValueRuleSet ที่มีattachment_typeของ CUSTOMER อยู่แล้วสําหรับบัญชี คุณต้องเพิ่มกฎมูลค่า Conversion ใหม่ลงในชุดดังกล่าวเพื่อให้กฎเหล่านั้นทํางาน หากไม่มีชุดกฎมูลค่า Conversion ดังกล่าว คุณต้องสร้างชุดกฎและเพิ่มกฎมูลค่า Conversion ลงในชุดกฎตามที่อธิบายไว้ในสร้างชุดกฎ

บริการการเรียกเก็บเงินและงบประมาณบัญชี

• การเปลี่ยนแปลงจะทำได้กับบัญชีที่กำหนดค่าสำหรับการแจ้งหนี้รายเดือนเท่านั้น

  คำขอที่ละเมิดข้อจำกัดนี้จะถูกปฏิเสธโดยมีข้อผิดพลาด MUTATE_NOT_ALLOWED

• อนุญาตให้ดำเนินการได้เพียง 1 รายการสำหรับคำขอการเปลี่ยนแปลง

  คำขอที่ละเมิดข้อจำกัดนี้จะถูกปฏิเสธโดยมีข้อผิดพลาด TOO_MANY_MUTATE_OPERATIONS

• คุณควรรออย่างน้อย 12 ชั่วโมงระหว่างการเปลี่ยนแปลงงบประมาณบัญชี (AccountBudget หรือ AccountBudgetProposal) ในบัญชีเดียวกัน การเปลี่ยนแปลงก่อนครบ 12 ชั่วโมงอาจส่งผลให้เกิดข้อผิดพลาดที่กู้คืนไม่ได้ ซึ่งแก้ไขได้โดยตัวแทนบัญชี Google Ads ของคุณเท่านั้น

คำเชิญไปยังบัญชีลูกค้า

คุณเชิญผู้ใช้ใหม่ให้เข้าร่วมบัญชีลูกค้าที่มีอยู่ได้โดยใช้CustomerUserAccessInvitationService เนื่องจากฟีเจอร์นี้จะส่งอีเมลคำเชิญไปยังผู้ใช้รายอื่น จึงอาจมีการนำไปใช้ในทางที่ผิด ดังนั้นจึงมีข้อจำกัดเกี่ยวกับลักษณะการทำงานของฟีเจอร์นี้ดังนี้

• ผู้ใช้จะรับคำเชิญที่รอดำเนินการสำหรับบัญชีลูกค้าเดียวกันได้เพียง 1 รายการ หากมีการส่งคำขอในภายหลังเพื่อส่งคำเชิญไปยังผู้ใช้ที่มีคำเชิญที่รอดำเนินการอยู่แล้ว ระบบจะแสดงข้อผิดพลาด EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION

• บัญชีลูกค้ามีคำเชิญที่รอดำเนินการได้ไม่เกิน 70 รายการในครั้งเดียว หากส่งคำขอที่ทำให้ค่านี้เกิน ระบบจะแสดงข้อผิดพลาดต่อไปนี้ PENDING_INVITATIONS_LIMIT_EXCEEDED

ข้อมูลผู้ใช้

ระบบจะจัดการข้อมูลผู้ใช้ด้วย UserDataService และ OfflineUserDataJobService

หมายเหตุ: ตั้งแต่วันที่ 1 เมษายน 2026 เป็นต้นไป UserDataService และ OfflineUserDataJobService สำหรับการจับคู่ข้อมูลลูกค้า จะจำกัดสำหรับผู้ใช้ใหม่ (NotAllowlistedError.CUSTOMER_NOT_ALLOWLISTED_FOR_THIS_FEATURE ที่กลับมา) การผสานรวมการจับคู่ข้อมูลลูกค้าใหม่ต้องใช้ Data Manager API

ออบเจ็กต์ UserData แต่ละรายการในการดำเนินการ create หรือ remove จะเกี่ยวข้องกับผู้ใช้ปลายทางรายเดียว ฟิลด์ user_identifiers ภายในออบเจ็กต์ UserData รายการเดียวจะจำกัดไว้ที่ตัวระบุสูงสุด 20 รายการ การเกินขีดจำกัดนี้ในออบเจ็กต์ UserData เดียวจะทำให้เกิดข้อผิดพลาด OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS หรือ UserDataError.TOO_MANY_USER_IDENTIFIERS

จัดการผู้ใช้ที่มีตัวระบุมากกว่า 20 รายการ

หากผู้ใช้ปลายทางรายเดียวมีตัวระบุมากกว่า 20 รายการที่คุณต้องอัปโหลด คุณควรกระจายตัวระบุเหล่านี้ในออบเจ็กต์ UserData หลายรายการ เพื่อให้มั่นใจว่า Google สามารถเชื่อมโยงตัวระบุทั้งหมดนี้กับผู้ใช้ปลายทางรายเดียวกันได้ ออบเจ็กต์ UserData แต่ละรายการสําหรับผู้ใช้รายนั้นต้องมีuser_identifierร่วมกันอย่างน้อย 1 รายการ เช่น hashed_email, hashed_phone_number หรือ third_party_user_id เดียวกัน Google ใช้ตัวระบุที่แชร์เหล่านี้เพื่อลิงก์และผสานรวม ข้อมูลจากการUserDataดำเนินการแยกกันเข้ากับโปรไฟล์ผู้ใช้ปลายทางที่ถูกต้อง

หากคุณใช้ PII เช่น อีเมลหรือหมายเลขโทรศัพท์ที่แฮช โปรดตรวจสอบว่าข้อมูลดังกล่าวได้รับการ แปลงเป็นรูปแบบมาตรฐานและแฮชตามข้อกำหนดของ Google Ads API (SHA-256, ตัวพิมพ์เล็ก, ไม่มีช่องว่าง) เพื่อป้องกันไม่ให้เกิดข้อผิดพลาดในการลิงก์

เช่น หากผู้ใช้มีอีเมล 30 รายการ คุณสามารถส่งUserDataออบเจ็กต์ 2 รายการที่ใช้third_party_user_idร่วมกัน (โดยใส่thirdPartyUserId บวกอีเมล 1-19 ในออบเจ็กต์แรกเพื่อให้ไม่เกินขีดจำกัดตัวระบุ 20 รายการ และใส่thirdPartyUserIdบวกอีเมล 20-30 ในออบเจ็กต์ที่ 2)

{
  "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" }
  ]
}

ขีดจํากัดรวมสําหรับ user_identifiers ในการดำเนินการทั้งหมดใน AddOfflineUserDataJobOperationsRequest เดียวคือ 100,000 รายการ (OfflineUserDataJob สามารถรับการเรียก AddOfflineUserDataJobOperationsRequest หลายรายการได้ โดยมีการดำเนินการสูงสุดที่แนะนําคือ 1,000,000 รายการต่องาน) สำหรับการอัปโหลดแบบซิงโครนัสโดยใช้ UploadUserDataRequest (UserDataService.UploadUserData) แต่ละคำขอจะจำกัด การดำเนินการสูงสุด 10 รายการและ 100 user_identifiers ใน คำขอทั้งหมด

ขีดจำกัดประเภทอื่นๆ

ฟิลด์ที่ซ้ำได้ เช่น รายการการดำเนินการ ซึ่งมีรายการมากเกินไปในคำขอ อาจทำให้เกิดข้อผิดพลาด REQUEST_SIZE_LIMIT_EXCEEDED ข้อความแสดงข้อผิดพลาดเดียวกันนี้อาจเกิดจากปัญหาอื่นๆ ด้วย

หากพบข้อจำกัดนี้และกำลังส่งคำขอที่ใช้ฟิลด์ที่ทำซ้ำ ให้ลองลดจำนวนรายการในฟิลด์ที่ทำซ้ำโดยแยกรายการการดำเนินการออกเป็นคำขอ mutate หลายรายการ

เมื่อทำการค้นหา GAQL จำนวนรายการสูงสุดภายใน คําสั่ง IN คือ 20,000 รายการ หากเกินขีดจำกัดดังกล่าว ระบบจะแสดงข้อผิดพลาด FILTER_HAS_TOO_MANY_VALUES