מסכות שדה

ב-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:

אזהרה: הקוד הזה לא יוצר שגיאה, אבל 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.

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