Composants Lieu

Contrairement aux autres composants, les composants Lieu sont créés automatiquement par l'API Google Ads après la création d'un ensemble de composants. Commencez par créer un ensemble de composants de synchronisation de lieu et associez-le au client. Ensuite, si vous devez sélectionner un sous-ensemble de composants Lieu dans l'ensemble de composants pour une campagne ou un groupe d'annonces, créez un ensemble de composants de groupe de zones géographiques et associez-le à la campagne ou au groupe d'annonces.

Créer un ensemble de composants de synchronisation de lieux et l'associer au client

  1. Créez un ensemble de composants de synchronisation de l'emplacement.
  2. Associez-le à un client à l'aide de CustomerAssetSetService.

Créer un ensemble de composants de synchronisation des établissements

  1. Créez un AssetSet.
    1. Définissez type sur LOCATION_SYNC.
    2. Définissez location_set sur un nouveau LocationSet.

  2. Dans la nouvelle LocationSet,

    1. Définissez location_ownership_type en fonction de votre cas d'utilisation :
      • Définissez-le sur BUSINESS_OWNER si vous êtes propriétaire de l'établissement.
      • Définissez-le sur AFFILIATE si vous ne possédez pas l'établissement, mais que vous y vendez vos produits.

    2. Définissez le champ oneof source en fonction de votre cas d'utilisation :

      • Définissez business_profile_location_set si vous souhaitez synchroniser vos établissements avec votre compte de fiches d'établissement Google.

        Lorsque vous créez un BusinessProfileLocationSet pour associer Google Ads à un compte de fiche d'établissement Google, vous devez fournir un jeton d'accès OAuth 2.0 dans le champ http_authorization_token. Ce jeton prouve que vous autorisez Google Ads à accéder aux données de localisation de la fiche d'établissement Google spécifiée.

        Le jeton doit répondre aux exigences suivantes :

        • Il doit être généré pour le compte Google (utilisateur ou compte de service) dont l'adresse e-mail est indiquée dans le champ email_address de BusinessProfileLocationSet.
        • Ce compte doit disposer des autorisations suffisantes pour lire les établissements dans la fiche d'établissement Google.
        • Le jeton OAuth 2.0 doit être obtenu avec le champ d'application https://www.googleapis.com/auth/business.manage.

        Pour obtenir des instructions détaillées sur la génération d'un jeton d'accès OAuth 2.0, consultez Utiliser OAuth 2.0 pour accéder aux API Google.

      • Définissez chain_location_set si vous souhaitez synchroniser avec des établissements dans des ID de chaîne spécifiés.

      • Définissez maps_location_set si vous souhaitez ajouter manuellement des établissements à l'aide d'ID de lieu.

Une fois ces étapes terminées, l'API Google Ads génère des composants Lieu et les ajoute à l'ensemble de composants de synchronisation de lieux créé, comme lorsque vous le faites manuellement à l'aide de AssetSetAssetService. Vous n'avez pas besoin de les manipuler, sauf si vous souhaitez les ajouter manuellement à un ensemble de composants de groupe de zones géographiques statique.

Un client ne peut disposer que d'un seul ensemble de composants de synchronisation de lieux actif avec status défini sur ENABLED. Si vous devez créer un autre type d'ensemble de composants de synchronisation des établissements, supprimez d'abord l'ensemble existant.

Associer l'ensemble de composants de synchronisation de l'emplacement à un client

Utilisez CustomerAssetSetService.MutateCustomerAssetSets pour associer à votre client l'ensemble de composants de synchronisation des lieux défini dans la section précédente.

(Facultatif) Créer un ensemble de composants de groupes de zones géographiques et l'associer à une campagne ou à un groupe d'annonces

Un ensemble de composants de groupe de zones géographiques n'est nécessaire que si vous devez sélectionner un sous-ensemble de composants Lieu. En effet, les campagnes et les groupes d'annonces héritent des composants Lieu définis au niveau du client.

Les ensembles de composants de groupe de zones géographiques contiennent un sous-ensemble de composants Lieu de l'ensemble de composants de synchronisation des zones géographiques. Vous pouvez créer dynamiquement un ensemble de composants de groupe de zones géographiques en exploitant certaines fonctionnalités de la fiche d'établissement Google (comme le filtrage par libellés) ou les ID et les zones géographiques des chaînes. Vous pouvez également créer un ensemble de composants de groupe de zones géographiques de manière statique.

  1. Créez un ensemble de composants de groupe de zones géographiques. L'ensemble de composants du groupe de zones géographiques peut être dynamique ou statique.
  2. Associez l'ensemble de composants à une campagne ou à un groupe d'annonces, selon vos besoins.
  3. (Facultatif) Ajoutez les composants générés précédemment à l'ensemble de composants de groupe de zones géographiques statique que vous venez de créer.

Pour un client donné, vous pouvez créer plusieurs ensembles de composants de groupes de zones géographiques dynamiques ou statiques.

Créer un ensemble de composants de groupes de zones géographiques

Créez un AssetSet et définissez location_group_parent_asset_set_id sur l'ID de l'ensemble de composants de synchronisation de lieux créé précédemment.

Ensuite, définissez certains champs selon que vous souhaitez créer un ensemble de composants de groupe de zones géographiques dynamique ou statique.

Ensembles de composants dynamiques

En fonction du champ que vous avez défini dans LocationSet, définissez les champs selon la règle suivante :

Si vous définissez le champ suivant Ensuite, définissez type sur Définissez ce champ comme champ 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

Si vous définissez maps_location_set lors de la création de l'ensemble de composants de synchronisation des établissements, vous ne pourrez pas créer d'ensemble de composants de groupe d'établissements dynamique. En effet, vous avez ajouté manuellement des établissements à l'aide d'ID de lieu, et aucune fonctionnalité de filtrage n'est disponible pour ce type d'établissement.

Ensembles de composants statiques

Définissez type sur STATIC_LOCATION_GROUP. Vous pouvez créer des ensembles de composants de groupes de zones géographiques statiques pour tous les types d'ensembles de composants de synchronisation de zones géographiques, quels que soient les champs (business_profile_location_set, chain_location_set ou maps_location_set) que vous définissez dans LocationSet.

Pour les ensembles de composants de groupes de zones géographiques statiques, vous devez ajouter manuellement les composants Lieu générés aux ensembles de composants de groupes de zones géographiques.

Associer l'ensemble de composants à une campagne ou à un groupe d'annonces

Utilisez CampaignAssetSetService.MutateCampaignAssetSets pour associer l'ensemble de composants de groupe de zones géographiques à votre campagne.

Vous pouvez également utiliser AdGroupAssetSetService.MutateAdGroupAssetSets si vous souhaitez associer l'ensemble de composants de groupe de zones géographiques à un groupe d'annonces.

(Facultatif) Ajoutez les composants Lieu à l'ensemble de composants de groupe de zones géographiques statique.

Cette étape n'est requise que si vous avez déjà créé un ensemble de composants de groupe de zones géographiques statique.

  1. Utilisez le rapport asset_set_asset pour récupérer les noms de ressources des composants générés automatiquement pour l'ensemble de composants de synchronisation de lieux créé précédemment. Utilisez le filtrage pour ne récupérer que les éléments souhaités.
  2. Ajoutez-les à l'ensemble de composants de groupe de zones géographiques statiques à l'aide de AssetSetAssetService.MutateAssetSetAssets.

Gérer les ID d'établissement de la fiche d'établissement

Lorsque vous utilisez un business_profile_location_set et que vous filtrez sur des listing_id_filters récupérés à partir du site Web ou de l'API de la fiche d'établissement, il peut être nécessaire de convertir ces valeurs numériques du type uint64 en int64. Si votre code génère une erreur d'exécution indiquant que l'ID de zone géographique de votre fiche d'établissement est hors de la plage autorisée lorsque vous l'ajoutez au champ répété listing_id_filters[], vous devez probablement le convertir à l'aide de l'un des exemples suivants :

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;
  }
}
Précédent
Création et utilisation
Suivant
Composants automatiques