Asset posizione

A differenza di altri asset, gli asset posizione vengono creati automaticamente dall'API Google Ads dopo la creazione di un set di asset. Per prima cosa, crea un insieme di asset di sincronizzazione delle sedi e collegalo al cliente. Poi, se devi selezionare un sottoinsieme degli asset posizione nel set di asset per una campagna o un gruppo di annunci, crea un set di asset del gruppo di sedi e collegalo alla campagna o al gruppo di annunci.

Creare un insieme di asset di sincronizzazione delle sedi e collegarlo al cliente

  1. Crea un insieme di asset di sincronizzazione delle sedi.
  2. Collegalo a un cliente utilizzando CustomerAssetSetService.

Creare un insieme di asset di sincronizzazione delle sedi

  1. Crea un nuovo AssetSet.
    1. Imposta type su LOCATION_SYNC.
    2. Imposta location_set su un nuovo LocationSet.

  2. Nel nuovo LocationSet:

    1. Imposta location_ownership_type in base al tuo caso d'uso:
      • Imposta su BUSINESS_OWNER se possiedi la sede dell'attività commerciale.
      • Imposta su AFFILIATE se non possiedi la sede dell'attività commerciale, ma vendi i tuoi prodotti lì.

    2. Imposta il campo oneof source in base al tuo caso d'uso:

      • Imposta business_profile_location_set se vuoi eseguire la sincronizzazione con le sedi nel tuo account Profilo dell'attività su Google.

        Quando crei un BusinessProfileLocationSet per collegare Google Ads a un account Profilo dell'attività su Google, devi fornire un token di accesso OAuth 2.0 nel campo http_authorization_token. Questo token funge da prova che stai autorizzando Google Ads ad accedere ai dati sulla sede dal Profilo dell'attività su Google specificato.

        Il token deve soddisfare questi requisiti:

        • Deve essere generato per l'Account Google (account utente o di servizio) il cui indirizzo email è fornito nel campo email_address di BusinessProfileLocationSet.
        • Questo account deve disporre di autorizzazioni sufficienti per leggere le sedi delle attività all'interno del Profilo dell'attività su Google.
        • Il token OAuth 2.0 deve essere ottenuto con l'ambito https://www.googleapis.com/auth/business.manage.

        Per istruzioni dettagliate su come generare un token di accesso OAuth 2.0, consulta Utilizzare OAuth 2.0 per accedere alle API di Google.

      • Imposta chain_location_set se vuoi eseguire la sincronizzazione con le sedi negli ID catena specificati.

      • Imposta maps_location_set se vuoi aggiungere manualmente le sedi utilizzando gli ID luogo.

Una volta completati questi passaggi, l'API Google Ads genera asset posizione e li aggiunge all'insieme di asset di sincronizzazione delle sedi creato, in modo simile a quando lo fai manualmente utilizzando AssetSetAssetService. Non devi manipolarli, a meno che tu non voglia aggiungere manualmente a un set di asset del gruppo di sedi statico.

Per un cliente può esistere un solo insieme di asset di sincronizzazione delle sedi attivo con (status di ENABLED). Se devi creare un altro tipo di set di asset di sincronizzazione delle sedi, rimuovi prima quello esistente.

Collegare l'insieme di asset di sincronizzazione delle sedi a un cliente

Utilizza CustomerAssetSetService.MutateCustomerAssetSets per collegare l'insieme di asset di sincronizzazione delle sedi nella sezione precedente al tuo cliente.

(Facoltativo) Creare un insieme di asset del gruppo di località e collegarlo a una campagna o a un gruppo di annunci

Un set di asset del gruppo di sedi è necessario solo se devi selezionare un sottoinsieme di asset posizione. Questo perché le campagne e i gruppi di annunci ereditano gli asset posizione a livello di cliente.

I set di asset del gruppo di sedi contengono un sottoinsieme di asset posizione del set di asset di sincronizzazione delle sedi. Puoi creare dinamicamente un insieme di asset del gruppo di località sfruttando alcune funzionalità di Profilo dell'attività su Google (ad esempio il filtro per etichette) o gli ID catena e le sedi della catena. In alternativa, puoi creare staticamente un insieme di asset del gruppo di località.

  1. Crea un insieme di asset del gruppo di località. L'insieme di asset del gruppo di località può essere dinamico o statico.
  2. Collega l'insieme di asset a una campagna utilizzando o a un gruppo di annunci, a seconda delle tue esigenze.
  3. (Facoltativo) Aggiungi gli asset generati in precedenza all'insieme di asset del gruppo di sedi statico appena creato.

Per un determinato cliente, puoi creare più set di asset del gruppo di sedi dinamici o statici.

Creare un insieme di asset del gruppo di località

Crea un nuovo AssetSet e imposta location_group_parent_asset_set_id sull'ID dell'insieme di asset di sincronizzazione delle sedi creato in precedenza.

Poi, imposta alcuni campi a seconda che tu voglia creare un insieme di asset del gruppo di località dinamico o statico.

Set di asset dinamici

A seconda del campo che hai impostato in LocationSet, imposta i campi in base alla seguente regola:

Se imposti il seguente campo Poi imposta tipo su E imposta questo campo come campo 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

Se imposti maps_location_set durante la creazione dell'insieme di asset di sincronizzazione delle sedi, non potrai creare un insieme di asset del gruppo di sedi dinamico. Questo perché hai aggiunto manualmente le sedi tramite gli ID luogo e non esistono funzionalità di filtro che puoi utilizzare per questo tipo di sedi.

Set di asset statici

Imposta type su STATIC_LOCATION_GROUP. Puoi creare set di asset del gruppo di sedi statici per qualsiasi tipo di set di asset di sincronizzazione delle sedi, indipendentemente dai campi (business_profile_location_set, chain_location_set, o maps_location_set) impostati in LocationSet.

Per i set di asset del gruppo di sedi statici, devi aggiungere manualmente gli asset posizione generati ai set di asset del gruppo di sedi.

Collegare l'insieme di asset a una campagna o a un gruppo di annunci

Utilizza CampaignAssetSetService.MutateCampaignAssetSets per collegare l'insieme di asset del gruppo di sedi alla tua campagna.

In alternativa, utilizza AdGroupAssetSetService.MutateAdGroupAssetSets se vuoi collegare l'insieme di asset del gruppo di sedi a un gruppo di annunci.

(Facoltativo) Aggiungere gli asset posizione al set di asset del gruppo di sedi statico

Questo passaggio è obbligatorio solo se hai creato in precedenza un insieme di asset del gruppo di sedi statico.

  1. Utilizza il report asset_set_asset per recuperare i nomi delle risorse degli asset generati automaticamente per l'insieme di asset di sincronizzazione delle sedi creato in precedenza. Utilizza il filtro per recuperare solo gli asset che ti interessano.
  2. Aggiungili all'insieme di asset del gruppo di località statico utilizzando AssetSetAssetService.MutateAssetSetAssets.

Gestire gli ID sede di Profilo dell'attività

Quando utilizzi un business_profile_location_set e filtri in base a listing_id_filters recuperati dal sito web o dall'API Profilo dell'attività, potrebbe essere necessario convertire questi valori numerici dal tipo uint64 a int64. Se il tuo codice genera un errore di runtime che indica che l'ID località di Profilo dell'attività è fuori intervallo quando lo aggiungi al campo ripetuto listing_id_filters[], probabilmente devi convertirlo utilizzando uno dei seguenti esempi:

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;
  }
}
Indietro
Creazione e utilizzo
Avanti
Asset automatici