מסכות שדה

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

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

דוגמה לעדכון קמפיין:

    $campaign = new Campaign([
        'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
        'status' => CampaignStatus::PAUSED
    ]);

    $campaignOperation = new CampaignOperation();
    $campaignOperation->setUpdate($campaign);
    $campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

הקוד הזה קודם יוצר אובייקט של קמפיין ולאחר מכן מגדיר את שם המשאב שלו באמצעות ResourceNames, כדי שממשק ה-API ידע איזה קמפיין מתעדכן. status מוגדר גם כ-PAUSED.

לאחר מכן הקוד יוצר אובייקט CampaignOperation ומגדיר אליו את הקמפיין שנוצר בעבר. לאחר מכן הוא ישתמש ב-FieldMasks::allSetFieldsOf() כדי ליצור מסכת שדות לקמפיין על ידי שימוש בכל השדות שהשתנו. לבסוף, היא מעבירה את המסכה שמוחזרת לאובייקט הפעולה של הקמפיין.

שימו לב ש-FieldMasks::allSetFieldsOf היא שיטה נוחה ל-FieldMasks::compare(). היא משווה בין האובייקט שהעברתם לאובייקט ריק מאותה מחלקה. למשל, בקוד הקודם הייתם יכולים להשתמש ב-FieldMasks::compare(new Campaign(), $campaign) במקום ב-allSetFieldsOf().

עדכון שדות של הודעות ושדות המשנה שלהם

השדות MESSAGE יכולים להכיל שדות משנה (כמו MaximizeConversions שכוללים שלושה: target_cpa_micros, cpc_bid_ceiling_micros ו-cpc_bid_floor_micros), או לא לכלול אותם בכלל (למשל ManualCpm).

שדות הודעה ללא שדות משנה מוגדרים

כשמעדכנים שדה MESSAGE שלא מוגדר בשדות משנה, משתמשים ב-FieldMasks כדי ליצור מסיכת שדות, כפי שהוסבר למעלה.

שדות הודעה עם שדות משנה מוגדרים

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

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

במקרה הזה, שימוש ב-methods allSetFieldsOf() ו-compare() של FieldMasks לא תורם להשגת היעד.

הקוד הבא יוצר אנונימיזציה של שדות עם maximize_conversions. עם זאת, הדבר לא אפשרי ב-Google Ads API, כדי למנוע ניקוי מקרי של שדות ויוצר הודעת שגיאה FieldMaskError.FIELD_HAS_SUBFIELDS.

אזהרה: הקוד הבא מייצר שגיאה.

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
    'maximize_conversions' => new MaximizeConversions()
]);

// Constructs an operation, using the FieldMasks' allSetFieldsOf utility to
// derive the update mask. The field mask will include 'maximize_conversions`,
// which will produce a FieldMaskError.FIELD_HAS_SUBFIELDS error.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

// Sends the operation in a mutate request that will result in a
// FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
// be included in a field mask.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns($customerId, [$campaignOperation]);

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

הצלחה: הקוד שבהמשך מעדכן בהצלחה את שיטת הבידינג של הקמפיין.

// Creates a Campaign object with the proper resource name.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId)
]);

// Creates a field mask from the existing campaign and adds all of the mutable
// fields (only one in this case) on the MaximizeConversions bidding strategy to
// the field mask. Because this field is included in the field mask but
// excluded from the campaign object, the Google Ads API will set the campaign's
// bidding strategy to a MaximizeConversions object without any of its subfields
// set.
fieldMask = FieldMasks::allSetFieldsOf($campaign);
// Only include 'maximize_conversions.target_cpa_micros' in the field mask
// as it is the only mutable subfield on MaximizeConversions when used as a
// standard bidding strategy.
//
// Learn more about standard and portfolio bidding strategies here:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
$fieldMask->setPaths(array_merge(
    iterator_to_array($fieldMask->getPaths()->getIterator()),
    ['maximize_conversions.target_cpa_micros']
));

// Creates an operation to update the campaign with the specified fields.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask($fieldMask);

ניקוי שדות

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

הקוד הבא פועל, אבל ה-maximize_conversions.target_cpa_micros לא יתווסף למסכת השדות ולכן לא יבוצעו שינויים בשדה target_cpa_micros:

אזהרה: הקוד הזה לא מייצר שגיאה, אבל target_cpa_micros של שיטת הבידינג MaximizeConversions לא יוסר.

// Creates a campaign with the proper resource name and a MaximizeConversions
// object with target_cpa_micros set to 0.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
    'maximize_conversions' => new MaximizeConversions(['target_cpa' => 0]),
    'status' => CampaignStatus::PAUSED
]);

// Constructs an operation, using the FieldMasks' allSetFieldsOf utility to
// derive the update mask. However, the field mask will NOT include
// 'maximize_conversions.target_cpa_micros'.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

// Sends the operation in a mutate request that will succeed but will NOT update
// the 'target_cpa_micros' field because
// 'maximize_conversions.target_cpa_micros' was not included in the field mask.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns($customerId, [$campaignOperation]);

הקוד הבא מדגים איך לנקות את השדה target_cpa_micros בשיטת הבידינג MaximizeConversions בצורה נכונה.

הצלחה: הקוד הבא מנקה את target_cpa_micros.

// Creates a Campaign object with the proper resource name.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId)
]);

// Constructs a field mask from the existing campaign and adds the
// 'maximize_conversions.target_cpa_micros' field to the field mask, which will
// clear this field from the bidding strategy without impacting any other fields
// on the bidding strategy.
$fieldMask = FieldMasks::allSetFieldsOf($campaign);
$fieldMask->setPaths(array_merge(
    iterator_to_array($fieldMask->getPaths()->getIterator()),
    ['maximize_conversions.target_cpa_micros']
));

// Creates an operation to update the campaign with the specified field.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask($fieldMask);

שימו לב שהקוד 'שגוי' פועל כמו שצריך בשדות שמוגדרים כ-optional ב-Google Ads API protocol buffers. אבל מכיוון שהשדה target_cpa_micros לא מכיל optional, הקוד 'שגוי' לא מעדכן את שיטת הבידינג כדי למחוק את השדה target_cpa.

נקודה חשובה: אם אתם מתכוונים לנקות שדה, הדרך הבטוחה ביותר היא להוסיף את השדה הזה במפורש למסכת השדות.