แนวทางปฏิบัติแนะนําและข้อจํากัด

โปรดคำนึงถึงหลักเกณฑ์ต่อไปนี้เมื่อใช้ BatchJobService

ปรับปรุงอัตราการส่งข้อมูล

  • ระบบจะเลือกงานขนาดใหญ่จำนวนน้อยแทนที่จะเป็นงานขนาดเล็กจำนวนมาก

  • จัดเรียงการดำเนินการที่อัปโหลดตามประเภทการดำเนินการ (ยกเว้นการดำเนินการที่ต้องพึ่งพาซึ่งกันและกัน ซึ่งต้องจัดกลุ่มตามลำดับในกลุ่มย่อยแบบอะตอมมิก) เช่น หากงานของคุณมีการดำเนินการเพื่อเพิ่มแคมเปญมาตรฐาน กลุ่มโฆษณา และเกณฑ์กลุ่มโฆษณา ให้จัดลำดับการดำเนินการในการอัปโหลดเพื่อให้การดำเนินการของแคมเปญทั้งหมดอยู่ก่อน ตามด้วยการดำเนินการของกลุ่มโฆษณาทั้งหมด และสุดท้ายคือการดำเนินการของเกณฑ์กลุ่มโฆษณาทั้งหมด

  • ในการดำเนินการประเภทเดียวกัน การจัดกลุ่มตามทรัพยากรหลักจะช่วยปรับปรุงประสิทธิภาพได้ ตัวอย่างเช่น หากคุณมีออบเจ็กต์ชุด AdGroupCriterionOperation การจัดกลุ่มการดำเนินการตามกลุ่มโฆษณาจะ มีประสิทธิภาพมากกว่าการผสมการดำเนินการที่ส่งผลต่อเกณฑ์กลุ่มโฆษณาในกลุ่มโฆษณาต่างๆ

ความเป็นหน่วยย่อยในการแยกกลุ่ม

Google Ads API จะแบ่งการดำเนินการในงานแบบกลุ่มที่ส่งเป็นชุดย่อยที่เล็กลงเพื่อประมวลผล แม้ว่าชุดย่อยมาตรฐานจะดำเนินการโดยเปิดใช้ความล้มเหลวบางส่วน แต่ระบบจะประมวลผลชุดย่อยสำหรับการดำเนินการที่ขึ้นต่อกันบางอย่างแบบอะตอมมิกเป็นธุรกรรมเดียว

  • การดำเนินการ AdGroupCriterionOperation ติดต่อกัน (create, update และ remove) สำหรับ เกณฑ์ LISTING_GROUP (AdGroupCriterion.listing_group) ที่กำหนดเป้าหมายไปยัง AdGroup เดียวกัน (ล้มเหลวด้วย CriterionError.LISTING_GROUP_ERROR_IN_ANOTHER_OPERATION หากการดำเนินการใดๆ ในกลุ่มล้มเหลว)
  • การดำเนินการ AssetGroupListingGroupFilterOperation ต่อเนื่อง (create, update และ remove) ที่กำหนดเป้าหมายไปยังAssetGroup เดียวกัน (ล้มเหลวด้วย BatchJobError.ASSET_GROUP_LISTING_GROUP_FILTER_TRANSACTION_FAILURE หากการดำเนินการใดๆ ในกลุ่มล้มเหลว)
  • AssetGroupOperation (create) ตามด้วยการดำเนินการ AssetGroupAssetOperation (create) สูงสุด 999 รายการทันที ซึ่งกำหนดเป้าหมายไปยัง AssetGroup เดียวกัน (จะล้มเหลวด้วย BatchJobError.ASSET_GROUP_AND_ASSET_GROUP_ASSET_TRANSACTION_FAILURE หากการดำเนินการใดๆ ในกลุ่มล้มเหลว) แต่ละ AssetGroupOperation (update หรือ remove) จะทำงานใน กลุ่มย่อยแบบเดี่ยวที่แยกต่างหากของตัวเอง
  • CampaignOperation Performance Max (create) ที่เปิดใช้หลักเกณฑ์การใช้แบรนด์ (brand_guidelines_enabled ตั้งค่าเป็น true หรือปล่อยให้ไม่ได้ตั้งค่า เนื่องจากค่าเริ่มต้นคือ true เว้นแต่จะตั้งค่าเป็น false อย่างชัดเจนหรือสร้างแคมเปญ Performance Max สำหรับเป้าหมายการท่องเที่ยว) ตามด้วยการดำเนินการ CampaignAssetOperation (create) สูงสุด 999 รายการ ที่กำหนดเป้าหมายเป็น Campaign เดียวกัน (ล้มเหลวด้วย BatchJobError.CAMPAIGN_AND_CAMPAIGN_ASSET_TRANSACTION_FAILURE หากการดำเนินการใดๆ ในกลุ่มล้มเหลว) คุณสร้างแคมเปญ Performance Max สำหรับการค้าปลีก (ที่มีฟีด Merchant Center) ได้โดยไม่ต้องลิงก์แหล่งข้อมูลแบรนด์CampaignAssetในกลุ่มย่อยแบบอะตอมเดียวกัน

สําหรับทั้งAssetGroupและ Performance Max Campaign การสร้างกลุ่มย่อย (การดําเนินการทั้งหมดสูงสุด 1,000 รายการต่อกลุ่มย่อย การดําเนินการ create ของบัญชีย่อยใดๆ ที่เกิน 999 รายการจะไปอยู่ในกลุ่มย่อยแบบไม่เป็นกลุ่มย่อยถัดไป):

  • createการดำเนินการหลัก (resource_nameใน AssetGroup หรือ Campaign) และcreateการดำเนินการย่อยที่ต่อเนื่องกัน (asset_groupใน AssetGroupAsset หรือ campaignใน CampaignAsset) ต้องระบุรหัสชั่วคราวที่ติดลบเดียวกัน
  • วางการดำเนินการAssetOperation (create) ที่จำเป็น สำหรับทรัพยากร Asset ใหม่ก่อนทรัพยากรหลัก AssetGroupOperation หรือ CampaignOperation (create) โดยห้ามวางระหว่างทรัพยากรหลัก create กับการดำเนินการของลิงก์ย่อย create (ซึ่งจะปิดกลุ่มย่อยแบบอะตอมทันทีและแยกการสร้างทรัพยากรหลักออกจาก ชิ้นงานที่ลิงก์)

เมื่อชุดย่อยแบบอะตอมล้มเหลว BatchJobResult.status ของการดำเนินการที่ทำให้เกิดข้อผิดพลาดจะมีข้อผิดพลาดในการตรวจสอบพื้นฐาน ในขณะที่การดำเนินการที่เหลือในชุดย่อยนั้นจะย้อนกลับพร้อมกับข้อผิดพลาดของธุรกรรมที่เกี่ยวข้องสำหรับชุดย่อยนั้น ตรวจสอบรายการBatchJobResultที่อยู่ติดกันซึ่งใช้รหัส AdGroup, AssetGroup หรือ Campaign เดียวกัน เพื่อระบุข้อผิดพลาดที่เป็นสาเหตุหลัก

หากไม่ได้เพิ่มการดำเนินการที่เกี่ยวข้องในกลุ่มเหล่านี้อย่างต่อเนื่อง Google Ads API จะแยกการดำเนินการเหล่านั้นออกเป็นกลุ่มย่อยๆ แยกกัน ซึ่งจะทำให้การแก้ไข ไม่เป็นไปตามข้อกำหนดขั้นต่ำของชิ้นงาน หรือทำให้โครงสร้างกลุ่มรายชื่อไม่สมบูรณ์ ดูรายละเอียดได้ที่ ใช้ตัวกรองกลุ่มรายชื่อในงานแบบกลุ่มและ การประมวลผลแบบกลุ่มของ Performance Max

การจัดกลุ่มเชิงตรรกะ

เมื่อแก้ไขลําดับชั้นการกําหนดเป้าหมายผลิตภัณฑ์ (AssetGroupListingGroupFilterOperation ในแคมเปญ Performance Max หรือ AdGroupCriterionOperation ใน แคมเปญ Shopping) หรือสร้าง AssetGroup ใหม่หรือ Performance Max Campaign ให้จัดกลุ่มการดําเนินการทั้งหมดที่กําหนดเป้าหมายไปยัง ทรัพยากรระดับบนสุดเดียวกัน (AssetGroup, AdGroup หรือ Campaign) ต่อเนื่องกัน ซึ่งจะช่วยลดการแย่งชิงการล็อกในแบ็กเอนด์และ เก็บต้นไม้ที่ขึ้นต่อกันไว้ด้วยกัน

ความสอดคล้องของข้อมูล

เนื่องจากระบบจะตรวจสอบโครงสร้างตัวกรองกลุ่มรายชื่อและข้อกำหนดของชิ้นงาน Performance Max เมื่อสิ้นสุดธุรกรรมการดำเนินการย่อยแบบอะตอมแต่ละรายการ โปรดหลีกเลี่ยงการแยก การอัปเดตไปยังทรัพยากรหลักเดียวกันในขอบเขตที่ไม่ต่อเนื่องในงาน หรือ ในงานที่ทํางานพร้อมกัน

หลีกเลี่ยงปัญหาการทำงานพร้อมกัน

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

  • อย่าส่งการดำเนินการหลายรายการที่เปลี่ยนแปลงออบเจ็กต์เดียวกันในงานเดียวกัน เนื่องจากผลลัพธ์อาจคาดเดาไม่ได้

ดึงข้อมูลผลลัพธ์อย่างเหมาะสม

  • อย่าสำรวจสถานะของงานบ่อยเกินไป มิฉะนั้นคุณอาจเสี่ยงที่จะได้รับข้อผิดพลาดเนื่องจากเกินขีดจำกัดอัตราคำขอ

  • ปล่อยให้ page_size ไม่ได้ตั้งค่า (หรือตั้งค่าเป็นสูงสุดที่ 1000) เมื่อเรียกใช้ ListBatchJobResults เพื่อลด การเดินทางไปกลับของการแบ่งหน้า และตั้งค่า response_content_type เป็น MUTABLE_RESOURCE เฉพาะในกรณีที่แอปพลิเคชันตรวจสอบฟิลด์ทรัพยากรที่ส่งคืนนอกเหนือจาก resource_name

  • ลำดับผลลัพธ์จะเหมือนกับลำดับการอัปโหลด

คำแนะนำเพิ่มเติมในการใช้งาน

  • คุณสามารถกำหนดขอบเขตบนสำหรับระยะเวลาที่อนุญาตให้งานแบบกลุ่มทำงานก่อนที่จะ ถูกยกเลิก เมื่อสร้างงานแบบกลุ่มใหม่ ให้ตั้งค่าฟิลด์ metadata.execution_limit_seconds เป็น ระยะเวลาที่ต้องการเป็นวินาที ไม่มีการจำกัดเวลาเริ่มต้นหากไม่ได้ตั้งค่า metadata.execution_limit_seconds

  • แม้ว่าขีดจำกัดของโปรโตคอลคือ 10,000 การดำเนินการต่อคำขอ แต่เราขอแนะนำให้เพิ่มการดำเนินการไม่เกิน 1,000 รายการต่อAddBatchJobOperationsRequest และใช้ sequence_token เพื่ออัปโหลดการดำเนินการที่เหลือไปยังงานเดียวกัน การส่งการดำเนินการมากเกินไปใน AddBatchJobOperationsRequest เดียวอาจทำให้เกิดข้อผิดพลาด BatchJobError.REQUEST_TOO_LARGE ทั้งนี้ขึ้นอยู่กับขนาดของการดำเนินการ คุณสามารถจัดการข้อผิดพลาดนี้ได้โดยลดจำนวนการดำเนินการและลองส่งคำขอ AddBatchJobOperationsRequest อีกครั้ง

ข้อจำกัด

  • BatchJob แต่ละรายการรองรับการดำเนินการได้สูงสุด 1 ล้านรายการ การโทร AddBatchJobOperations ที่เกินขีดจำกัดนี้จะทำให้เกิดข้อผิดพลาด ResourceCountLimitExceededError.RESOURCE_LIMIT (โดยมี ResourceLimitType.BATCH_JOB_OPERATIONS_PER_JOB ใน ErrorDetails.resource_count_details)

  • แต่ละบัญชีจะมีงานที่ใช้งานอยู่หรือรอดำเนินการได้สูงสุด 100 งานในเวลาเดียวกัน การเกินขีดจำกัดนี้เมื่อสร้างงานแบบกลุ่มด้วย MutateBatchJob จะทำให้เกิดข้อผิดพลาด ResourceCountLimitExceededError.RESOURCE_LIMIT (พร้อม ResourceLimitType.BATCH_JOBS_PER_CUSTOMER ใน ErrorDetails.resource_count_details)

  • ระบบจะนำงานที่รอดำเนินการซึ่งเก่ากว่า 7 วันออกโดยอัตโนมัติ

  • AddBatchJobOperationsRequest แต่ละรายการมีขีดจำกัดที่แน่นอนของการดำเนินการเปลี่ยนแปลง 10,000 รายการต่อคำขอ การดำเนินการเกิน 10,000 รายการในคำขอเดียวจะแสดงข้อผิดพลาด BatchJobError.REQUEST_TOO_LARGE

  • สำหรับฟิลด์ page_size ใน ListBatchJobResultsRequest ให้ทำดังนี้

    • หากไม่ได้ตั้งค่า page_size หรือตั้งค่าเป็น 0 ระบบจะใช้ค่าเริ่มต้นเป็น สูงสุด 1000
    • หาก page_size เกิน 1000 หรือน้อยกว่า 0 API จะ แสดงข้อผิดพลาด BatchJobError.INVALID_PAGE_SIZE

  • AddBatchJobOperationsRequestแต่ละรายการมีขนาดสูงสุด 41,937,920 ไบต์ หากเกินขีดจำกัดนี้ คุณจะได้รับข้อผิดพลาด BatchJobError.REQUEST_TOO_LARGE (หรือ INTERNAL_ERROR หากถูกปฏิเสธที่เลเยอร์การรับส่ง) คุณ สามารถกำหนดขนาดที่แปลงเป็นอนุกรมของคำขอก่อนส่งและดำเนินการ ที่เหมาะสมหากมีขนาดใหญ่เกินไปได้โดยทำดังนี้

    Java

    
static final int MAX_REQUEST_BYTES = 41_937_920;

// ... (code to get the AddBatchJobOperationsRequest object)

int sizeInBytes = request.getSerializedSize();

    C#

    
const int MAX_REQUEST_BYTES = 41_937_920;

// ... (code to get the AddBatchJobOperationsRequest object)

int sizeInBytes = request.CalculateSize();

    PHP

    
const MAX_REQUEST_BYTES = 41937920;

// ... (code to get the AddBatchJobOperationsRequest object)

$size_in_bytes = $request->byteSize();

    Python

    
MAX_REQUEST_BYTES = 41_937_920

# ... (code to get the AddBatchJobOperationsRequest object)

size_in_bytes = type(request).pb(request).ByteSize()

    Ruby

    
MAX_REQUEST_BYTES = 41_937_920

# ... (code to get the AddBatchJobOperationsRequest object)

size_in_bytes = request.to_proto.bytesize

    Perl

    
use JSON::XS;
use constant MAX_REQUEST_BYTES => 41937920;

# ... (code to get the AddBatchJobOperationsRequest object)

# The Perl client library uses REST/JSON; UTF-8 JSON byte length provides a
# conservative upper-bound estimate of the serialized request size.
my $json_encoder = JSON::XS->new->utf8->convert_blessed;
my $size_in_bytes = length($json_encoder->encode($request));

ขนาดของการดำเนินการเปลี่ยนแปลงรายการเดียว

แม้ว่าคำขอโดยรวมจะมีขนาดได้สูงสุด 41,937,920 ไบต์ แต่ขนาดที่แปลงเป็นอนุกรมของ MutateOperation รายการเดียวในกลุ่มจะจำกัดไว้ที่ 10,484,504 ไบต์ (10 MiB ลบ 1,256 ไบต์) หากเกินขีดจำกัดนี้ ระบบจะแสดงข้อผิดพลาด BatchJobError.REQUEST_TOO_LARGE โปรดทราบว่าแม้ว่าเอกสารอ้างอิงสำหรับ BatchJobError.REQUEST_TOO_LARGE จะอ้างอิงถึงเกณฑ์ 10,484,504 ไบต์ แต่ AddBatchJobOperations จะแสดงรหัสข้อผิดพลาดเดียวกันนี้ เมื่อมีการเกินเกณฑ์คำขอทั้ง 3 รายการ (ไบต์คำขอทั้งหมด 41,937,920 ไบต์ ไบต์การดำเนินการเดียว 10,484,504 ไบต์ หรือการดำเนินการ 10,000 รายการต่อการเรียกใช้) โดยฟิลด์ message ของข้อผิดพลาดจะระบุว่ามีการละเมิดขีดจำกัดใด

ก่อนหน้า
ตัวกรองกลุ่มรายชื่อ