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

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

שיפור התפוקה

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

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

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

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

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

גם בAssetGroup וגם בקמפיינים למיקסום הביצועים Campaign, יצירת קבוצות משנה (sub-batches) של פעולות (עד 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. שימו לב: למרות שבמאמרי העזרה של BatchJobError.REQUEST_TOO_LARGE מצוין סף של 10,484,504 בייט, AddBatchJobOperations מחזירה את אותו קוד שגיאה כשחורגים מאחד משלושת הספים של הבקשה (41,937,920 בייט בסך הכול של הבקשה, 10,484,504 בייט של פעולה יחידה או 10,000 פעולות לכל קריאה), והשדה message של השגיאה מציין איזו מגבלה הופרה.

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