מסכות שדה

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

כלי השירות FieldMasks

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

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

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

my $campaign_operation =
  Google::Ads::GoogleAds::V16::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::V16::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 מקביל ל-protobuf MESSAGE בספריות לקוח שפועלות ב-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::V16::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V16::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::V16::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::V16::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V16::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::V16::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::V16::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V16::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V16::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::V16::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

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