מסכות שדה

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

השירות FieldMasks

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

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

my $campaign = Google::Ads::GoogleAds::V19::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V19::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    status => PAUSED,
    networkSettings =>
      Google::Ads::GoogleAds::V19::Resources::NetworkSettings->new({
        targetSearchNetwork => "false"
      })
    });

my $campaign_operation =
  Google::Ads::GoogleAds::V19::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

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

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

FieldMasks::all_set_fields_of() היא שיטה נוחה ל-FieldMasks::field_mask(). הפונקציה משווה את האובייקט שהוענק לה לאובייקט ריק מאותו סוג. לכן, בקוד שלמעלה אפשר גם להשתמש ב-

field_mask(Google::Ads::GoogleAds::V19::Resources::Campaign->new({}), $campaign)

במקום all_set_fields_of($campaign).

יצירת מסכה באופן ידני

כדי ליצור מסכת שדה מאפס, קודם יוצרים אובייקט Google::Ads::GoogleAds::Common::FieldMask, לאחר מכן יוצרים הפניה למערך שמאוכלסת בשמות של כל השדות שאתם מתכוונים לשנות, ולבסוף מקצים את ההפניה למערך לשדה paths של מסכת השדה.

my $field_mask = Google::Ads::GoogleAds::Common::FieldMask->new({
    paths => ["status", "name"]
  });

עדכון שדות של אובייקטים ושדות המשנה שלהם

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

שדות של אובייקטים ללא שדות משנה מוגדרים

שדה אובייקט ב-Perl שווה ערך ל-MESSAGE של protobuf בספריות לקוח שפועלות ב-gRPC. כשמעדכנים שדה של אובייקט שלא מוגדר עם שדות משנה, משתמשים בכלי FieldMasks כדי ליצור מסכת שדה, כפי שמתואר למעלה.

שדות אובייקט עם שדות משנה מוגדרים

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

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

במקרה כזה, השימוש בשיטות all_set_fields_of() ו-field_mask() של השירות FieldMasks לא מאפשר להשיג את היעד הרצוי.

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

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

# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign = Google::Ads::GoogleAds::V19::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V19::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V19::Resources::MaximizeConversions->new()
    });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask. The field mask will include 'maximize_conversions',
# which will produce a FieldMaskError.FIELD_HAS_SUBFIELDS error.
my $campaign_operation =
  Google::Ads::GoogleAds::V19::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty object fields cannot
# be included in a field mask.
my $response = $api_client->CampaignService()->mutate({
    customerId => $customer_id,
    operations => [$campaign_operation]
  });

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

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

# Creates a campaign with the proper resource name.
my $campaign = Google::Ads::GoogleAds::V19::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V19::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    )
  });

# 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.
# 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
my $field_mask = all_set_fields_of($campaign);
push @{$field_mask->{paths}}, "maximize_conversions.target_cpa_micros";

# Creates an operation to update the campaign with the specified fields.
my $campaign_operation =
  Google::Ads::GoogleAds::V19::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => $field_mask
  });

ניקוי שדות

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

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

# Creates a campaign with the proper resource name and a MaximizeConversions
# object with target_cpa_micros set to 0.
my $campaign =
  Google::Ads::GoogleAds::V19::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V19::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V19::Resources::MaximizeConversions->new({
      targetCpaMicros => 0
    })
  });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask, which will include 'maximize_conversions.target_cpa_micros'.
my $campaign_operation =
  Google::Ads::GoogleAds::V19::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

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