Standort-Assets

Im Gegensatz zu anderen Assets werden Standort-Assets automatisch von der Google Ads API erstellt, nachdem Sie eine Asset-Sammlung erstellt haben. Erstellen Sie zuerst eine Standort-Asset-Sammlung und verknüpfen Sie sie mit dem Kunden. Wenn Sie dann eine Teilmenge der Standort-Assets in der Asset-Sammlung für eine Kampagne oder Anzeigengruppe auswählen müssen, erstellen Sie eine Standortgruppen-Asset-Sammlung und verknüpfen Sie sie mit der Kampagne oder Anzeigengruppe.

Standort-Asset-Sammlung erstellen und mit dem Kunden verknüpfen

  1. Erstellen Sie eine Standort-Asset-Sammlung.
  2. Verknüpfen Sie sie mit einem Kunden mit CustomerAssetSetService.

Standort-Asset-Sammlung erstellen

  1. Erstellen Sie eine neue AssetSet.
    1. Legen Sie type auf LOCATION_SYNC fest.
    2. Legen Sie location_set auf eine neue LocationSet fest.
  2. In der neuen LocationSet:

    1. Legen Sie location_ownership_type entsprechend Ihrem Anwendungsfall fest:
      • Legen Sie es auf BUSINESS_OWNER fest, wenn Sie der Inhaber des Unternehmensstandorts sind.
      • Legen Sie es auf AFFILIATE fest, wenn Sie nicht der Inhaber des Unternehmensstandorts sind, aber Ihre Produkte dort verkaufen.
    2. Legen Sie das source-Oneof-Feld entsprechend Ihrem Anwendungsfall fest:

      • Legen Sie business_profile_location_set fest, wenn Sie mit Ihren Standorten in Ihrem Google Unternehmensprofil Konto synchronisieren möchten.

        Wenn Sie eine BusinessProfileLocationSet erstellen, um Google Ads mit einem Google Unternehmensprofil-Konto zu verknüpfen, müssen Sie ein OAuth 2.0-Zugriffstoken im Feld http_authorization_token angeben. Dieses Token dient als Nachweis dafür, dass Sie Google Ads autorisieren, auf die Standortdaten aus dem angegebenen Google Unternehmensprofil zuzugreifen.

        Das Token muss die folgenden Anforderungen erfüllen:

        • Es muss für das Google-Konto (Nutzer- oder Dienstkonto) generiert werden, dessen E-Mail-Adresse im Feld email_address der BusinessProfileLocationSet angegeben ist.
        • Dieses Konto muss ausreichende Berechtigungen haben, um die Unternehmensstandorte im Google Unternehmensprofil zu lesen.
        • Das OAuth 2.0-Token muss mit dem Bereich https://www.googleapis.com/auth/business.manage abgerufen werden.

        Eine detaillierte Anleitung zum Generieren eines OAuth 2.0-Zugriffs tokens finden Sie unter Mit OAuth 2.0 auf Google APIs zugreifen.

      • Legen Sie chain_location_set fest, wenn Sie mit Standorten in bestimmten Ketten-IDs synchronisieren möchten.

      • Legen Sie maps_location_set fest, wenn Sie Standorte manuell mithilfe von Orts-IDs hinzufügen möchten.

Nachdem Sie diese Schritte ausgeführt haben, generiert die Google Ads API Standort Assets und fügt sie der erstellten Standort-Asset-Sammlung hinzu. Das ist ähnlich wie beim manuellen Hinzufügen mit AssetSetAssetService. Sie müssen sie nicht bearbeiten, es sei denn, Sie möchten sie manuell zu statischen Standort gruppen-Asset-Sammlungen hinzufügen.

Für einen Kunden kann nur eine aktive Standort-Asset-Sammlung mit (status von ENABLED) vorhanden sein. Wenn Sie eine andere Art von Standort-Asset-Sammlung erstellen müssen, entfernen Sie zuerst die vorhandene.

Standort-Asset-Sammlung mit einem Kunden verknüpfen

Verwenden Sie CustomerAssetSetService.MutateCustomerAssetSets , um die Standort-Asset-Sammlung im vorherigen Abschnitt mit Ihrem Kunden zu verknüpfen.

(Optional) Standortgruppen-Asset-Sammlung erstellen und mit einer Kampagne oder Anzeigengruppe verknüpfen

Eine Standortgruppen-Asset-Sammlung ist nur erforderlich, wenn Sie eine Teilmenge von Standort-Assets auswählen müssen. Das liegt daran, dass Kampagnen und Anzeigengruppen Standort-Assets von der Kundenebene übernehmen.

Standortgruppen-Asset-Sammlungen enthalten eine Teilmenge der Standort-Assets der Standort-Asset-Sammlung. Sie können eine Standortgruppen-Asset-Sammlung dynamisch erstellen, indem Sie einige Funktionen von Google Unternehmensprofil nutzen, z. B. das Filtern nach Labels, Ketten-IDs und Kettenstandorten. Alternativ können Sie eine Standortgruppen-Asset-Sammlung statisch erstellen.

  1. Erstellen Sie eine Standortgruppen-Asset-Sammlung. Die Standortgruppen-Asset-Sammlung kann dynamisch oder statisch sein.
  2. Verknüpfen Sie die Asset-Sammlung mit `CampaignAssetSetService.MutateCampaignAssetSets` mit einer Kampagne oder mit `AdGroupAssetSetService.MutateAdGroupAssetSets` mit einer Anzeigengruppe, je nach Bedarf.
  3. (Optional) Fügen Sie die zuvor generierten Assets der neu erstellten statischen Standortgruppen-Asset-Sammlung hinzu.

Für einen bestimmten Kunden können Sie mehrere dynamische oder statische Standortgruppen-Asset-Sammlungen erstellen.

Standortgruppen-Asset-Sammlung erstellen

Erstellen Sie eine neue AssetSet und legen Sie location_group_parent_asset_set_id auf die ID der zuvor erstellten Standort-Asset-Sammlung fest.

Legen Sie dann einige Felder fest, je nachdem, ob Sie eine dynamische oder statische Standortgruppen-Asset-Sammlung erstellen möchten.

Dynamische Asset-Sammlungen

Legen Sie die Felder entsprechend dem in LocationSet festgelegten Feld nach der folgenden Regel fest:

Wenn Sie das folgende Feld festlegen Legen Sie dann Typ auf Folgendes fest Und legen Sie dieses Feld als das asset_set_source-Oneof -Feld fest
business_profile_location_set BUSINESS_PROFILE_DYNAMIC_LOCATION_GROUP business_profile_location_group
chain_location_set CHAIN_DYNAMIC_LOCATION_GROUP chain_location_group

Wenn Sie maps_location_set festlegen, wenn Sie die Standort-Asset-Sammlung erstellen, können Sie keine dynamische Standortgruppen-Asset-Sammlung erstellen. Das liegt daran, dass Sie Standorte manuell anhand von Orts-IDs hinzugefügt haben und für diese Art von Standorten keine Filterfunktionen verfügbar sind.

Statische Asset-Sammlungen

Legen Sie type auf STATIC_LOCATION_GROUP fest. Sie können statische Standortgruppen-Asset-Sammlungen für alle Arten von Standort Asset-Sammlungen erstellen, unabhängig davon, welche Felder (business_profile_location_set, chain_location_set, oder maps_location_set) Sie in der LocationSet festgelegt haben.

Bei statischen Standortgruppen-Asset-Sammlungen müssen Sie die generierten Standort-Assets manuell den Standortgruppen-Asset Sammlungen hinzufügen.

Asset-Sammlung mit einer Kampagne oder Anzeigengruppe verknüpfen

Verwenden Sie CampaignAssetSetService.MutateCampaignAssetSets , um die Standortgruppen-Asset-Sammlung mit Ihrer Kampagne zu verknüpfen.

Alternativ können Sie AdGroupAssetSetService.MutateAdGroupAssetSets verwenden, wenn Sie die Standortgruppen-Asset-Sammlung stattdessen mit einer Anzeigengruppe verknüpfen möchten.

(Optional) Standort-Assets der statischen Standortgruppen-Asset-Sammlung hinzufügen

Dieser Schritt ist nur erforderlich, wenn Sie zuvor eine statische Standortgruppen-Asset-Sammlung erstellt haben.

  1. Verwenden Sie den asset_set_asset-Bericht, um die Ressourcennamen der Assets abzurufen, die automatisch für die zuvor erstellte Standort-Asset-Sammlung generiert wurden. Verwenden Sie Filter, um nur die gewünschten Assets abzurufen.
  2. Fügen Sie sie mit AssetSetAssetService.MutateAssetSetAssets der statischen Standortgruppen-Asset-Sammlung hinzu.

Unternehmensprofil-Standort-IDs verwalten

Wenn Sie eine business_profile_location_set verwenden und nach listing_id_filters filtern, die von der Unternehmensprofil-Website oder API abgerufen werden, müssen Sie diese numerischen Werte möglicherweise vom Typ uint64 in int64 konvertieren. Wenn Ihr Code einen Laufzeitfehler generiert, dass die Google Unternehmensprofil-Zielgebiets-ID außerhalb des zulässigen Bereichs liegt, wenn Sie sie dem wiederkehrenden Feld `listing_id_filters[] ` hinzufügen, müssen Sie sie wahrscheinlich mit einem der folgenden Beispiele konvertieren:

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 >= 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 >= 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.
  elseif 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 >= 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.
  } elseif ($business_profile_location_id >= 2**63) {
    return -1 * (2**64 - $business_profile_location_id);
  } else {
    return $business_profile_location_id;
  }
}