מסכות שדה

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

FieldMaskUtil

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

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

// Update campaign by setting its status to paused, and "Search network" to false.
Campaign campaignToUpdate = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    Status = CampaignStatus.Paused,
    NetworkSettings = new NetworkSettings()
    {
        TargetSearchNetwork = false
    }
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaignToUpdate)
};

// Update the campaign.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

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

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

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

Campaign existingCampaign;

// Obtain existingCampaign from elsewhere.
...

// Create a new campaign based off the existing campaign for update.
Campaign campaignToUpdate = new Campaign(existingCampaign);

// Update campaign by setting its status to paused, and "Search network" to
// false.
campaignToUpdate.Status = CampaignStatus.Paused;
campaignToUpdate.NetworkSettings = new NetworkSettings()
{
    TargetSearchNetwork = false
}

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.FromChanges(existingCampaign, campaignToUpdate)
};

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

FieldMask fieldMask = new FieldMask();
fieldMask.Paths.AddRange(new string[] { "status", "name" });

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

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

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

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

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

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

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

במקרה הזה, באמצעות השיטות AllSetFieldsOf() ו-FromChanges() של FieldMasks לא משיג את היעד הרצוי.

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

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    MaximizeConversions = 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 operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = 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.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

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

// Creates a Campaign object with the proper resource name.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
};

// Creates a field mask from the existing campaign and adds all of the fields
// on the MaximizeConversions bidding strategy to the field mask. Because these
// fields are 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 with none of its subfields set.
FieldMask 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.Paths.AddRange(new string[] {
    "maximize_conversions.target_cpa_micros",
});

// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = 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 campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    MaximizeConversions = new MaximizeConversions()
    {
        TargetCpaMicros = 0
    }
};

// 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 operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = 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.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });

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

// Creates a Campaign object with the proper resource name.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(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 fieldMask = FieldMasks.AllSetFieldsOf(campaign);
fieldMask.Paths.AddRange(new string[] {
    "maximize_conversions.target_cpa_micros",
});

// Creates an operation to update the campaign with the specified field.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = fieldMask
};

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