Komponenty z lokalizacją

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

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

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

Tworzenie zestawu komponentów do synchronizacji lokalizacji

  1. Utwórz nowy AssetSet.
    1. Ustaw type na LOCATION_SYNC.
    2. Ustaw location_set na nowy LocationSet.
  2. W nowej wersji LocationSet

    1. Ustaw location_ownership_type na podstawie przypadku użycia:
      • Jeśli jesteś właścicielem lokalizacji firmy, ustaw wartość BUSINESS_OWNER.
      • Jeśli nie jesteś właścicielem lokalizacji firmy, ale sprzedajesz tam swoje produkty, ustaw wartość AFFILIATE.
    2. Ustaw pole source na podstawie przypadku użycia:

      • Jeśli chcesz synchronizować dane z lokalizacjami na koncie Profilu Firmy w Google, ustaw business_profile_location_set.

        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 stanowi dowód, że upoważniasz Google Ads do dostępu do danych o lokalizacji z określonego profilu firmy w Google.

        Token musi spełniać te wymagania:

        • Musi on zostać wygenerowany dla 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 odczytu lokalizacji firm 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 protokołu OAuth 2.0 na potrzeby dostępu do interfejsów API Google.

      • Ustaw chain_location_set, jeśli chcesz synchronizować z lokalizacjami o określonych identyfikatorach 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 do synchronizacji lokalizacji, podobnie jak w przypadku ręcznego dodawania za pomocą AssetSetAssetService. Nie musisz ich modyfikować, chyba że chcesz je ręcznie dodać do statycznego zestawu komponentów grupy lokalizacji.

Klient może mieć tylko jeden aktywny zestaw komponentów do synchronizacji lokalizacji, w którym parametr status ma wartość ENABLED. Jeśli chcesz utworzyć inny typ zestawu komponentów do synchronizacji lokalizacji, najpierw usuń dotychczasowy.

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

Użyj CustomerAssetSetService.MutateCustomerAssetSets, aby dołączyć do klienta zestaw komponentów do synchronizacji lokalizacji utworzony w poprzedniej sekcji.

(Opcjonalnie) Tworzenie zestawu komponentów z grupą 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ą. Dzieje się tak, ponieważ kampanie i grupy reklam dziedziczą komponenty z lokalizacją z poziomu klienta.

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

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

Dla danego klienta możesz utworzyć wiele zestawów komponentów z dynamicznymi lub statycznymi grupami lokalizacji.

Tworzenie zestawu komponentów z grupą lokalizacji

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

Następnie ustaw niektóre pola w zależności od tego, czy chcesz utworzyć zestaw komponentów z grupą lokalizacji dynamicznych czy statycznych.

Zestawy komponentów dynamicznych

W zależności od pola ustawionego w LocationSet ustaw pola zgodnie z tą regułą:

Jeśli ustawisz to pole Następnie ustaw type na Ustaw to pole jako pole 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

Jeśli podczas tworzenia zestawu komponentów do synchronizacji lokalizacji ustawisz parametr maps_location_set, nie będzie można utworzyć zestawu komponentów z dynamiczną grupą lokalizacji. Dzieje się tak, ponieważ lokalizacje zostały dodane ręcznie za pomocą identyfikatorów miejsc, a w przypadku tego typu lokalizacji nie można używać funkcji filtrowania.

Statyczne zestawy komponentów

Ustaw type na STATIC_LOCATION_GROUP. Możesz tworzyć statyczne zestawy komponentów z grupą lokalizacji dla dowolnych typów zestawów komponentów z synchronizacją lokalizacji, niezależnie od tego, jakie pola (business_profile_location_set, chain_location_set lub maps_location_set) ustawisz w LocationSet.

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

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

Użyj CampaignAssetSetService.MutateCampaignAssetSets, aby dołączyć do kampanii zestaw komponentów z grupą lokalizacji.

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

(Opcjonalnie) Dodaj komponenty z lokalizacją do statycznego zestawu komponentów grupy lokalizacji.

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

  1. Użyj raportu asset_set_asset, aby pobrać nazwy zasobów komponentów wygenerowanych automatycznie dla utworzonego wcześniej zestawu komponentów do synchronizacji lokalizacji. Użyj filtrowania, aby pobrać tylko te zasoby, których potrzebujesz.
  2. Dodaj je do zestawu komponentów ze statyczną grupą lokalizacji za pomocą metody 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 podczas dodawania identyfikatora lokalizacji w profilu firmy do powtarzanego pola listing_id_filters[] kod generuje błąd środowiska wykonawczego, który informuje, że identyfikator jest poza zakresem, 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 < 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;
  }
}