מסכות שדה

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

FieldMaskUtil

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

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

// Creates a Campaign object with the proper resource name and any other changes.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation that will update the campaign, using the FieldMasks'
// allSetFieldsOf utility to derive the update mask. This mask tells the Google
// Ads API which attributes of the campaign you want to change.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

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

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

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

Campaign existingCampaign;

// Obtains existingCampaign from elsewhere.
...

// Creates a new campaign based off the existing campaign and updates the
// campaign by setting its status to paused.
Campaign campaignToUpdate =
    existingCampaign.toBuilder()
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation that will update the campaign, using the FieldMasks'
// compare utility to derive the update mask. This mask tells the Google Ads API
// which attributes of the campaign you want to change.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaignToUpdate)
        .setUpdateMask(FieldMasks.compare(existingCampaign, campaignToUpdate))
        .build();

// Sends the operation in a mutate request.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

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

FieldMask fieldMask =
    FieldMask.newBuilder()
        .addPaths("status")
        .addPaths("name")
        .build();

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

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

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

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

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

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

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

במקרה הזה, שימוש בשיטות allSetFieldsOf() ו-compare() של FieldMaskUtil לא מניב את היעד הרצוי.

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

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

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign campaign = Campaign.newBuilder()
    .setResourceName(ResourceNames.campaign(customerId, campaignId))
    .setMaximizeConversions(MaximizeConversions.newBuilder().build())
    .build();

// 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 =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// 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 =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

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

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

// Creates a Campaign object with the proper resource name.
Campaign campaign = Campaign.newBuilder()
    .setResourceName(ResourceNames.campaign(customerId, campaignId))
    .build();

// 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 fieldMask = FieldMasks.allSetFieldsOf(campaign)
    .toBuilder()
    // 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
    .addPaths("maximize_conversions.target_cpa_micros")
    .build();

// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(fieldMask)
        .build();

ניקוי השדות

אפשר למחוק באופן מפורש חלק מהשדות. בדומה לדוגמה שלמעלה, עליכם להוסיף את השדות האלה באופן מפורש לאנונימיזציה של השדות. לדוגמה, נניח שיש לכם קמפיין עם שיטת בידינג 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 campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setMaximizeConversions(
            MaximizeConversions.newBuilder().setTargetCpa(0).build())
        .setStatus(CampaignStatus.PAUSED)
        .build();

// 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 =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// 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 =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

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

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

// Creates a Campaign object with the proper resource name.
Campaign campaign = Campaign.newBuilder()
    .setResourceName(ResourceNames.campaign(customerId, campaignId))
    .build();

// 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)
    .toBuilder()
    .addPaths("maximize_conversions.target_cpa_micros")
    .build();

// Creates an operation to update the campaign with the specified field.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(fieldMask))
        .build();

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

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