Komponenty z lokalizacją

W przeciwieństwie do innych zasobów zasoby z lokalizacją są tworzone automatycznie przez interfejs Google Ads API po utworzeniu zestawu komponentów. Najpierw utwórz zestaw komponentów synchronizacji lokalizacji i dołącz go do klienta. Następnie, jeśli musisz wybrać podzbiór komponentów z lokalizacją w zestawie komponentów na potrzeby kampanii lub grupy reklam, utwórz zestaw komponentów grupy lokalizacji i dołącz go do kampanii lub grupy reklam.

Tworzenie zestawu komponentów synchronizacji lokalizacji i dołączanie go do klienta

  1. Utwórz zestaw komponentów synchronizacji lokalizacji.
  2. Dołącz go do klienta za pomocą CustomerAssetSetService.

Tworzenie zestawu komponentów synchronizacji lokalizacji

  1. Utwórz nowy AssetSet.
    1. Ustaw type na LOCATION_SYNC.
    2. Ustaw location_set na nowy LocationSet.
  2. W nowym LocationSet:

    1. Ustaw location_ownership_type na podstawie swojego przypadku użycia:
      • Ustaw wartość BUSINESS_OWNER , jeśli jesteś właścicielem adresu sklepu.
      • Ustaw wartość AFFILIATE , jeśli nie jesteś właścicielem adresu sklepu, ale sprzedajesz w nim swoje produkty.
    2. Ustaw pole source oneof na podstawie swojego przypadku użycia:

      • Ustaw business_profile_location_set, jeśli chcesz synchronizować lokalizacje z kontem Profilu Firmy w Google.

        Gdy tworzysz BusinessProfileLocationSet, aby połączyć Google Ads z kontem Profilu Firmy w Google, musisz podać token dostępu OAuth 2.0 w polu http_authorization_token. Ten token potwierdza, że autoryzujesz Google Ads do uzyskiwania dostępu do danych o lokalizacji z określonego Profilu Firmy w Google.

        Token musi spełniać te wymagania:

        • Musi być wygenerowany na potrzeby konta Google (użytkownika lub konta usługi), którego adres e-mail jest podany w polu email_address w BusinessProfileLocationSet.
        • To konto musi mieć wystarczające uprawnienia do odczytywania lokalizacji firmy w Profilu Firmy w Google.
        • Token OAuth 2.0 musi zostać uzyskany z zakresem https://www.googleapis.com/auth/business.manage.

        Szczegółowe instrukcje generowania tokena dostępu OAuth 2.0 znajdziesz w artykule Używanie OAuth 2.0 do korzystania z interfejsów API Google.

      • Ustaw chain_location_set, jeśli chcesz synchronizować lokalizacje z określonymi identyfikatorami sieci.

      • Ustaw maps_location_set, jeśli chcesz ręcznie dodawać lokalizacje za pomocą identyfikatorów miejsc.

Po wykonaniu tych czynności interfejs Google Ads API wygeneruje komponenty z lokalizacją i doda je do utworzonego zestawu komponentów synchronizacji lokalizacji, podobnie jak w przypadku ręcznego dodawania za pomocą AssetSetAssetService. Nie musisz ich modyfikować, chyba że chcesz dodać je ręcznie do statycznych zestawów komponentów grupy lokalizacji .

Na koncie klienta może istnieć tylko 1 aktywny zestaw komponentów synchronizacji lokalizacji (status ma wartość ENABLED). Jeśli musisz utworzyć inny typ zestawu komponentów synchronizacji lokalizacji, najpierw usuń dotychczasowy.

Dołączanie zestawu komponentów synchronizacji lokalizacji do klienta

Aby dołączyć zestaw komponentów synchronizacji lokalizacji z poprzedniej sekcji do klienta, użyj CustomerAssetSetService.MutateCustomerAssetSets.

(Opcjonalnie) Tworzenie zestawu komponentów grupy lokalizacji i dołączanie go do kampanii lub grupy reklam

Zestaw komponentów grupy lokalizacji jest potrzebny tylko wtedy, gdy musisz wybrać podzbiór komponentów z lokalizacją. Wynika to z tego, że kampanie i grupy reklam dziedziczą komponenty z lokalizacją z poziomu klienta.

Zestawy komponentów grupy lokalizacji zawierają podzbiór komponentów z lokalizacją z zestawu komponentów synchronizacji lokalizacji. Zestaw komponentów grupy lokalizacji możesz utworzyć dynamicznie, korzystając z niektórych funkcji Profilu Firmy w Google (np. filtrowania według etykiet) lub identyfikatorów sieci i lokalizacji sieci. Możesz też utworzyć statyczny zestaw komponentów grupy lokalizacji.

  1. Utwórz zestaw komponentów grupy lokalizacji. Zestaw komponentów grupy lokalizacji może być dynamiczny lub statyczny.
  2. Dołącz zestaw komponentów do kampanii za pomocą lub do grupy reklam, w zależności od potrzeb.
  3. (Opcjonalnie) Dodaj wcześniej wygenerowane komponenty do nowo utworzonego statycznego zestawu komponentów grupy lokalizacji.

W przypadku danego klienta możesz utworzyć kilka dynamicznych lub statycznych zestawów komponentów grupy lokalizacji.

Tworzenie zestawu komponentów grupy lokalizacji

Utwórz nowy AssetSet i ustaw location_group_parent_asset_set_id na identyfikator wcześniej utworzonego zestawu komponentów synchronizacji lokalizacji.

Następnie ustaw niektóre pola w zależności od tego, czy chcesz utworzyć dynamiczny czy statyczny zestaw komponentów grupy lokalizacji.

Zestawy komponentów dynamicznych

W zależności od pola, które ustawisz w LocationSet, ustaw pola zgodnie z tą regułą:

Jeśli ustawisz to pole Ustaw typ na I ustaw to pole jako pole asset_set_source oneof field
business_profile_location_set BUSINESS_PROFILE_DYNAMIC_LOCATION_GROUP business_profile_location_group
chain_location_set CHAIN_DYNAMIC_LOCATION_GROUP chain_location_group

Jeśli podczas tworzenia zestawu komponentów synchronizacji lokalizacji ustawisz maps_location_set, nie będziesz mieć możliwości utworzenia dynamicznego zestawu komponentów grupy lokalizacji . Wynika to z tego, że lokalizacje zostały dodane ręcznie za pomocą identyfikatorów miejsc i nie ma funkcji filtrowania, których można by użyć w przypadku tego typu lokalizacji.

Zestawy komponentów statycznych

Ustaw type na STATIC_LOCATION_GROUP. Statyczne zestawy komponentów grupy lokalizacji możesz tworzyć w przypadku dowolnych typów zestawów komponentów synchronizacji lokalizacji, niezależnie od tego, jakie pola (business_profile_location_set, chain_location_set, or maps_location_set) ustawisz w the LocationSet.

W przypadku statycznych zestawów komponentów grupy lokalizacji musisz ręcznie dodać wygenerowane komponenty z lokalizacją do zestawów komponentów grupy lokalizacji.

Dołączanie zestawu komponentów do kampanii lub grupy reklam

Aby dołączyć zestaw komponentów grupy lokalizacji do kampanii, użyj CampaignAssetSetService.MutateCampaignAssetSets.

Jeśli zamiast tego chcesz dołączyć zestaw komponentów grupy lokalizacji do grupy reklam, użyj AdGroupAssetSetService.MutateAdGroupAssetSets.

(Opcjonalnie) Dodawanie komponentów z lokalizacją do statycznego zestawu komponentów grupy lokalizacji

Ten krok jest wymagany tylko wtedy, gdy wcześniej utworzysz statyczny zestaw komponentów grupy lokalizacji.

  1. Użyj raportu asset_set_asset, aby pobrać nazwy zasobów komponentów wygenerowanych automatycznie na potrzeby wcześniej utworzonego zestawu komponentów synchronizacji lokalizacji. Użyj filtrowania, aby pobrać tylko te komponenty, które Cię interesują.
  2. Dodaj je do statycznego zestawu komponentów grupy lokalizacji za pomocą AssetSetAssetService.MutateAssetSetAssets.

Zarządzanie identyfikatorami lokalizacji w Profilu Firmy

Gdy używasz business_profile_location_set i filtrujesz według listing_id_filters pobranych z witryny lub interfejsu API Profilu Firmy, może być konieczne przekonwertowanie tych wartości liczbowych z typu uint64 na int64. Jeśli Twój kod generuje błąd czasu wykonania informujący, że identyfikator lokalizacji w Profilu Firmy jest poza zakresem podczas dodawania go do powtarzającego się pola listing_id_filters[], prawdopodobnie musisz go przekonwertować, korzystając z jednego z tych przykładów:

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;
  }
}