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

โปรดคำนึงถึงหลักเกณฑ์เหล่านี้เมื่อใช้ 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 (create) ของ Performance Max ที่เปิดใช้หลักเกณฑ์การใช้แบรนด์ (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 ใหม่หรือ Campaign ของ Performance Max ให้จัดกลุ่มการดำเนินการทั้งหมดที่กำหนดเป้าหมายไปยังทรัพยากรหลักเดียวกัน (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 ของข้อผิดพลาดจะระบุขีดจำกัดที่ละเมิด

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