נכסי מיקום

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

יצירת קבוצת נכסים לסנכרון מיקומים וצירוף שלה ללקוח

  1. יוצרים קבוצת נכסים מסוג סנכרון מיקום.
  2. מצרפים את הרישיון ללקוח באמצעות CustomerAssetSetService.

יצירת קבוצת נכסים שמסונכרנים לפי מיקום

  1. יוצרים AssetSet חדש.
    1. מגדירים את type לערך LOCATION_SYNC.
    2. מגדירים את location_set לערך חדש של LocationSet.

  2. בגרסה החדשה של LocationSet,

    1. מגדירים את location_ownership_type בהתאם לתרחיש לדוגמה:
      • אם מיקום העסק בבעלותכם, הגדירו את הערך BUSINESS_OWNER.
      • אם אתם לא הבעלים של מיקום העסק, אבל אתם מוכרים שם את המוצרים שלכם, הגדירו את הערך AFFILIATE.

    2. מגדירים את השדה source oneof בהתאם לתרחיש לדוגמה:

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

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

        האסימון צריך לעמוד בדרישות הבאות:

        • צריך ליצור אותו לחשבון Google (חשבון משתמש או חשבון שירות) שכתובת האימייל שלו צוינה בשדה email_address של BusinessProfileLocationSet.
        • לחשבון הזה צריכות להיות הרשאות מספיקות כדי לקרוא את מיקומי העסק בפרופיל העסק ב-Google.
        • צריך לקבל את אסימון ה-OAuth 2.0 עם ההיקף https://www.googleapis.com/auth/business.manage.

        הוראות מפורטות ליצירת אסימון גישה מסוג OAuth 2.0 מופיעות במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.

      • מגדירים את chain_location_set אם רוצים לסנכרן עם מיקומים במזהי רשתות ספציפיים.

      • מגדירים את maps_location_set אם רוצים להוסיף מיקומים באופן ידני באמצעות מזהי מקומות.

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

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

צירוף קבוצת הנכסים של סנכרון המיקום ללקוח

משתמשים ב-CustomerAssetSetService.MutateCustomerAssetSets כדי לצרף ללקוח את קבוצת הנכסים לסנכרון מיקומים שהוגדרה בקטע הקודם.

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

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

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

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

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

יצירת קבוצת נכסים של קבוצות לפי מיקום

יוצרים AssetSet חדש ומגדירים את location_group_parent_asset_set_id למזהה של קבוצת נכסי המיקום המסונכרנים שיצרתם קודם.

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

קבוצות נכסים דינמיות

בהתאם לשדה שהגדרתם ב-LocationSet, מגדירים את השדות לפי הכלל הבא:

אם מגדירים את השדה הבא ואז מגדירים את type לערך ומגדירים את השדה הזה בתור השדה oneof של asset_set_source
business_profile_location_set BUSINESS_PROFILE_DYNAMIC_LOCATION_GROUP business_profile_location_group
chain_location_set CHAIN_DYNAMIC_LOCATION_GROUP chain_location_group

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

קבוצות נכסים סטטיות

מגדירים את type לערך STATIC_LOCATION_GROUP. אתם יכולים ליצור קבוצות נכסים סטטיות של קבוצות לפי מיקום לכל סוג של קבוצות נכסים לסנכרון מיקומים, לא משנה אילו שדות (business_profile_location_set, chain_location_set או maps_location_set) הגדרתם ב-LocationSet.

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

מצרפים את קבוצת הנכסים לקמפיין או לקבוצת מודעות

משתמשים ב-CampaignAssetSetService.MutateCampaignAssetSets כדי לצרף את קבוצת הנכסים לפי מיקום לקמפיין.

לחלופין, אפשר להשתמש ב-AdGroupAssetSetService.MutateAdGroupAssetSets אם רוצים לצרף את קבוצת הנכסים לפי מיקום לקבוצת מודעות.

(אופציונלי) מוסיפים את נכסי המיקום לקבוצת הנכסים הסטטית של קבוצות לפי מיקום.

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

  1. משתמשים בדוח asset_set_asset כדי לאחזר את שמות המשאבים של הנכסים שנוצרו באופן אוטומטי בשביל קבוצת הנכסים לסנכרון מיקום שנוצרה קודם. אפשר להשתמש בסינון כדי לאחזר רק את הנכסים שרוצים.
  2. מוסיפים אותם לקבוצת הנכסים הסטטית של קבוצות לפי מיקום באמצעות AssetSetAssetService.MutateAssetSetAssets.

ניהול מזהי המיקומים של פרופיל העסק

כשמשתמשים ב-business_profile_location_set ומסננים לפי listing_id_filters שאוחזרו מהאתר או מה-API של פרופיל העסק, יכול להיות שיהיה צורך להמיר את הערכים המספריים האלה מסוג uint64 ל-int64. אם הקוד שלכם יוצר שגיאת זמן ריצה שמזהה המיקום בפרופיל העסק ב-Google חורג מהטווח כשמוסיפים אותו לשדה החוזר listing_id_filters[], סביר להניח שאתם צריכים להמיר אותו באמצעות אחת מהדוגמאות הבאות:

Java

/**
 * Converts the business profile location ID to the format expected by the
 * DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
 * The business profile location ID is an unsigned 64-bit integer, while the
 * listing_id_filters[] field expects signed 64-bit integers. This means that
 * for business profile location IDs that are out of range, we must perform the
 * two's complement to convert it into a signed int.
 *
 * @param businessProfileLocationId The ID of a Business Profile location ID.
 * @return a Business Profile location ID as a signed 64-bit integer (long).
 */
public static long convertBusinessProfileLocationId(String businessProfileLocationId) {
    return Long.parseUnsignedLong(businessProfileLocationId);
}

C#‎

/// <summary>
/// Converts the business profile location ID to the format expected by the
/// DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
/// The business profile location ID is an unsigned 64-bit integer, while the
/// listing_id_filters[] field expects signed 64-bit integers. This means that
/// for business profile location IDs that are out of range, we must perform the
/// two's complement to convert it into a signed int.
/// </summary>
/// <param name="businessProfileLocationId">The ID of a Business Profile location.</param>
/// <returns>The converted business location ID in signed 64 bit.</returns>
public long ConvertBusinessProfileLocationId(ulong businessProfileLocationId)
{
  return unchecked((long)businessProfileLocationId);
}

PHP

/**
* Converts a business profile location ID to a signed 64 bit integer.
*
* Converts the business profile location ID to the format expected by the
* DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
* The business profile location ID is an unsigned 64-bit integer, while the
* listing_id_filters[] field expects signed 64-bit integers. This means that
* for business profile location IDs that are out of range, we must perform the
* two's complement to convert it into a signed int.
*
* @param string $businessProfileLocationId the ID of a Business Profile location
* @return int the converted business location ID in signed 64 bit
*/
public static function convertBusinessProfileLocationId(string $businessProfileLocationId): int
{
    $unsignedMax = '18446744073709551615'; // 2^64 - 1
    $signedMax = '9223372036854775807'; // 2^63 - 1

    // Check if the business profile location ID is within 64 bit range.
    // If not, throw an error.
    if (bccomp($businessProfileLocationId, '0') < 0 || bccomp($businessProfileLocationId, $unsignedMax) > 0) {
        throw new InvalidArgumentException(
            'The given business profile location id is outside of the range for a 64 bit integer.'
        );
    }

    // Check if the business profile location ID is in signed 64 bit range.
    // If it's not, convert it to its two's complement.
    if (bccomp($businessProfileLocationId, $signedMax) > 0) {
        // Two's complement: ID - 2^64
        return (int) bcsub($businessProfileLocationId, '18446744073709551616');
    }

    return (int) $businessProfileLocationId;
}

Python

import ctypes

def convert_business_profile_location_id(business_profile_location_id):
    """Converts a business profile location ID to a signed 64 bit integer.

    Converts the business profile location ID to the format expected by the
    DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
    The business profile location ID is an unsigned 64-bit integer, while the
    listing_id_filters[] field expects signed 64-bit integers. This means that
    for business profile location IDs that are out of range, we must perform the
    two's complement to convert it into a signed int.

    Args:
        business_profile_location_id: the ID of a Business Profile location ID.

    Returns:
        a Business Profile location ID as a signed 64 bit integer.
    """
    # Check if the business profile location ID is within 64 bit range.
    # If not, throw an error.
    if business_profile_location_id < 0 or business_profile_location_id >= 2 ** 64:
        raise ValueError(
            "The given business profile location id is outside of the range for a 64 bit integer."
        )
    # Check if the business profile location ID is in signed 64 bit range.
    # If it's not, convert it to its two's complement.
    elif business_profile_location_id >= 2 ** 63:
        return ctypes.c_int64(business_profile_location_id).value
    else:
        return business_profile_location_id

Ruby

# Converts the business profile location ID to the format expected by the
# DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
# The business profile location ID is an unsigned 64-bit integer, while the
# listing_id_filters[] field expects signed 64-bit integers. This means that
# for business profile location IDs that are out of range, we must perform the
# two's complement to convert it into a signed int.
# Since Ruby supports arbitrary precision numbers, we have to calculate it
# manually.
LONG_MAX = 2 ** 63
ULONG_MAX = LONG_MAX * 2
def convert_business_profile_location_id(business_profile_location_id)
  # Check if the business profile location ID is within 64 bit range.
  # If not, throw an error.
  if business_profile_location_id < 0 || business_profile_location_id >= 2 ** 64
    raise "The given business profile location id is outside of the range for a 64 bit integer."
  # Check if the business profile location ID is in signed 64 bit range.
  # If it's not, convert it to its two's complement.
  elsif business_profile_location_id >= 2**63
    -1 * (ULONG_MAX - business_profile_location_id)
  else
    business_profile_location_id
  end
end

Perl

use bigint;

# Converts the business profile location ID to the format expected by the
# DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
# The business profile location ID is an unsigned 64-bit integer, while the
# listing_id_filters[] field expects signed 64-bit integers. This means that
# for business profile location IDs that are out of range, we must perform the
# two's complement to convert it into a signed int.
sub convert_business_profile_location_id {
  my ($business_profile_location_id) = @_;

  # Check if the business profile location ID is within 64 bit range.
  # If not, throw an error.
  if ($business_profile_location_id < 0 || $business_profile_location_id >= 2**64) {
    die "The given business profile location id is outside of the range for a 64 bit integer";
  # Check if the business profile location ID is in signed 64 bit range.
  # If it's not, convert it to its two's complement.
  } elsif ($business_profile_location_id >= 2**63) {
    return -1 * (2**64 - $business_profile_location_id);
  } else {
    return $business_profile_location_id;
  }
}
הקודם
יצירה ושימוש
הבא
נכסים דיגיטליים אוטומטיים