מסכות שדה

ב-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));

הקוד הזה יוצר תחילה אובייקט 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 בלי להגדיר אף אחד משדות המשנה של שיטת הבידינג.

במקרה הזה, שימוש בשיטות 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:

// 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.

// 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.