מסכות שדה

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

כלי FieldMasks

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

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

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

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

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

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

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

field_mask(Google::Ads::GoogleAds::V21::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::V21::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V21::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V21::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::V21::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::V21::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V21::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::V21::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::V21::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V21::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V21::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::V21::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

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