שיטות מומלצות ומגבלות

כדאי לפעול לפי ההנחיות הבאות כשמשתמשים ב-BatchJobService.

שיפור קצב העברת הנתונים

  • עדיף להגדיר פחות משימות גדולות מאשר הרבה משימות קטנות.

  • מסדרים את הפעולות שמעלים לפי סוג הפעולה (חוץ מפעולות שתלויות זו בזו, שצריך לקבץ אותן ברצף באצוות משנה אטומיות). לדוגמה, אם המשימה כוללת פעולות להוספת קמפיינים רגילים, קבוצות של מודעות וקריטריונים של קבוצות של מודעות, צריך לסדר את הפעולות בהעלאה כך שכל הפעולות ברמת הקמפיין יהיו ראשונות, אחריהן כל הפעולות ברמת קבוצת המודעות, ולבסוף כל הפעולות ברמת הקריטריונים של קבוצת המודעות.

  • בפעולות מאותו סוג, אפשר לשפר את הביצועים על ידי קיבוץ שלהן לפי משאב הורה. לדוגמה, אם יש לכם סדרה של אובייקטים מסוג AdGroupCriterionOperation, יעיל יותר לקבץ את הפעולות לפי קבוצת מודעות, במקום לערבב פעולות שמשפיעות על קריטריונים של קבוצות מודעות בקבוצות מודעות שונות.

אטומיות בפיצול אצוות

‫Google Ads API מפצל את הפעולות במשימת אצווה שנשלחה לאצוות משנה קטנות יותר לצורך עיבוד. בזמן שקבוצות משנה רגילות מופעלות עם כשל חלקי, קבוצות משנה של פעולות מסוימות שתלויות זו בזו מעובדות באופן אטומי כטרנזקציה אחת:

גם בקבוצות משנה ליצירת AssetGroup וגם בקבוצות משנה ליצירת קמפיינים למיקסום הביצועים 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 מפצל אותן לקבוצות משנה נפרדות, וכתוצאה מכך השינוי לא עומד בדרישות המינימליות לגבי נכסים או שעצי הקבוצות של כרטיסי המוצר נשארים לא שלמים. פרטים נוספים זמינים במאמרים שימוש במסננים של קבוצות כרטיסי מוצר במשימות באצווה ועיבוד באצווה בקמפיינים למיקסום הביצועים.

קיבוץ לוגי

כשמשנים היררכיית טירגוט של מוצרים (AssetGroupListingGroupFilterOperation בקמפיינים למיקסום הביצועים או AdGroupCriterionOperation בקמפיינים של שופינג) או כשיוצרים AssetGroup חדש או Campaign חדש בקמפיין למיקסום הביצועים, צריך לקבץ את כל הפעולות שמטרגטות את אותו משאב הורה (AssetGroup,‏ AdGroup או Campaign) ברצף. כך אפשר לצמצם את התחרות על נעילת הקצה העורפי ולשמור על עצים תלויים זה בזה ביחד.

עקביות הנתונים

מכיוון שהעצים של מסנני קבוצות של כרטיסי מוצר והדרישות לגבי נכסים בקמפיינים למיקסום הביצועים מאומתים בסוף כל טרנזקציה של תת-אצווה אטומית, כדאי להימנע מפיצול עדכונים לאותו משאב הורה בטווחים לא רציפים במשימה או במשימות בו-זמניות.

איך למנוע בעיות שקשורות לפעולות בו-זמניות

  • כששולחים כמה משימות בו-זמנית לאותו חשבון, כדאי להקטין את הסיכוי שהמשימות יפעלו על אותם אובייקטים באותו זמן, תוך שמירה על גודל משימות גדול. אם יש הרבה משימות לא גמורות בסטטוס RUNNING שמנסות לשנות את אותה קבוצת אובייקטים, יכול להיווצר מצב שדומה למבוי סתום, שגורם להאטה משמעותית ואפילו לכישלון של המשימות.

  • אל תשלחו כמה פעולות שמשנות את אותו אובייקט באותה משימה, כי התוצאה יכולה להיות בלתי צפויה.

אחזור תוצאות בצורה אופטימלית

  • אל תדגמו את סטטוס המשימה בתדירות גבוהה מדי, אחרת אתם עלולים להגיע לשגיאות של הגבלת קצב של יצירת בקשות.

  • כשמפעילים את ListBatchJobResults, כדאי להשאיר את page_size לא מוגדר (או להגדיר אותו למקסימום של 1000) כדי לצמצם את מספר הבקשות והתגובות של חלוקה לדפים, ולהגדיר את 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 תומך בעד מיליון פעולות. חריגה מהמגבלה הזו בקריאה ל-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 בייטים (10MiB פחות 1,256 בייטים). אם חורגים מהמגבלה הזו, מוחזרת השגיאה BatchJobError.REQUEST_TOO_LARGE. שימו לב שב, AddBatchJobOperations מחזיר את אותו קוד שגיאה כשחורגים מאחד משלושת הספים של הבקשות (סך של 41,937,920 בייטים לבקשה, 10,484,504 בייטים לפעולה בודדת או 10,000 פעולות לכל קריאה), ובשדה message של השגיאה מצוין באיזו מגבלה חרגתם. זאת למרות שב מאמרי העזרה של BatchJobError.REQUEST_TOO_LARGE מצוין הסף של 10,484,504 בייטים.

הקודם
מסננים של קבוצות של כרטיסי מוצר