מסכות שדה

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

המחלקות FieldMasks

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

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

// 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 });

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

Campaign existingCampaign;

// Obtain existingCampaign from an earlier API call.

// Create a new campaign based on 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)
};

טיפול בשגיאות 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()
};

CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

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

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

במקרים כאלה, אפשר להוסיף נתיבים באופן ידני ל-fieldMask.Paths (שהוא RepeatedField<string>):

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

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 at:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
fieldMask.Paths.Add("maximize_conversions.target_cpa_micros");

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

ניקוי השדות

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

בדוגמת הקוד הבאה אפשר לראות איך מוחקים את השדה target_cpa_micros של שיטת בידינג MaximizeConversions:

קוד נכון

הקוד הבא מנקה את השדה target_cpa_micros כי הוא מוסיף את maximize_conversions.target_cpa_micros למסכת השדה בלי להגדיר את המאפיין campaign.MaximizeConversions.TargetCpaMicros:

// 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
// clears this field from the bidding strategy without impacting any other
// fields on the bidding strategy.
FieldMask fieldMask = FieldMasks.AllSetFieldsOf(campaign);
fieldMask.Paths.Add("maximize_conversions.target_cpa_micros");

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

קוד שגוי

הקוד הבא לא מנקה את השדה target_cpa_micros, כי הוא מגדיר את השדה לערך 0. גם כלי השירות FieldMasks וגם השרת של Google Ads API מתעלמים מהערך הזה אם TargetCpaMicros הוא 0 או אם הנתיב מושמט מהמסכה, והשרת לא מחזיר שגיאה:

// Creates a campaign with the proper resource name and a
// MaximizeConversions object. Attempts to clear the target_cpa_micros
// field by setting it to 0.
Campaign campaign = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    MaximizeConversions = new MaximizeConversions()
    {
        TargetCpaMicros = 0
    }
};

// Constructs an operation using FieldMasks.AllSetFieldsOf to derive the
// update mask.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaign,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaign)
};

// Sends the operation in a mutate request that succeeds without clearing
// the previous 'target_cpa_micros' value cleanly.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
    customerId.ToString(), new CampaignOperation[] { operation });