Recursos de ubicación

A diferencia de otros recursos, la API de Google Ads crea automáticamente los recursos de ubicación después de que creas un conjunto de recursos. Primero, crea un conjunto de recursos de sincronización de ubicación y conéctalo al cliente. Luego, si necesitas seleccionar un subconjunto de los recursos de ubicación en el conjunto de recursos para una campaña o un grupo de anuncios, crea un conjunto de recursos de grupo por ubicación y conéctalo a la campaña o al grupo de anuncios.

Crea un conjunto de recursos de sincronización de ubicación y conéctalo al cliente

  1. Crea un conjunto de recursos de sincronización de ubicación.
  2. Conéctalo a un cliente con CustomerAssetSetService.

Crea un conjunto de recursos de sincronización de ubicación

  1. Crea un AssetSet nuevo.
    1. Establece type en LOCATION_SYNC.
    2. Establece location_set en un LocationSet nuevo.

  2. En el nuevo LocationSet, haz lo siguiente:

    1. Establece location_ownership_type según tu caso de uso:
      • Establécelo en BUSINESS_OWNER si eres propietario de la ubicación de la empresa.
      • Establécelo en AFFILIATE si no eres propietario de la ubicación de la empresa, pero vendes tus productos allí.

    2. Establece el campo oneof source según tu caso de uso:

      • Establece business_profile_location_set si deseas sincronizarte con tus ubicaciones en tu cuenta del Perfil de Negocio de Google.

        Cuando creas un BusinessProfileLocationSet para vincular Google Ads con una cuenta del Perfil de Negocio de Google, debes proporcionar un token de acceso de OAuth 2.0 en el campo http_authorization_token. Este token actúa como prueba de que autorizas a Google Ads a acceder a los datos de ubicación del Perfil de Negocio de Google especificado.

        El token debe cumplir con los siguientes requisitos:

        • Se debe generar para la Cuenta de Google (usuario o cuenta de servicio) cuya dirección de correo electrónico se proporciona en el campo email_address de BusinessProfileLocationSet.
        • Esta cuenta debe tener permisos suficientes para leer las ubicaciones de la empresa en el Perfil de Negocio de Google.
        • El token de OAuth 2.0 se debe obtener con el alcance https://www.googleapis.com/auth/business.manage.

        Para obtener instrucciones detalladas sobre cómo generar un token de acceso de OAuth 2.0, consulta Usa OAuth 2.0 para acceder a las APIs de Google.

      • Establece chain_location_set si deseas sincronizarte con las ubicaciones en los IDs de cadena especificados.

      • Establece maps_location_set si deseas agregar ubicaciones manualmente con IDs de lugar.

Después de completar estos pasos, la API de Google Ads genera recursos de ubicación y los agrega al conjunto de recursos de sincronización de ubicación creado, de manera similar a cuando lo haces manualmente con AssetSetAssetService. No es necesario que los manipules, a menos que desees agregarlos manualmente a conjuntos de recursos de grupo por ubicación estáticos.

Solo puede existir un conjunto de recursos de sincronización de ubicación activo (status de ENABLED) para un cliente. Si necesitas crear un tipo diferente de conjunto de recursos de sincronización de ubicación, primero quita el existente.

Conecta el conjunto de recursos de sincronización de ubicación a un cliente

Usa CustomerAssetSetService.MutateCustomerAssetSets para conectar el conjunto de recursos de sincronización de ubicación de la sección anterior a tu cliente.

(Opcional) Crea un conjunto de recursos de grupo por ubicación y conéctalo a una campaña o a un grupo de anuncios

Un conjunto de recursos de grupo por ubicación solo es necesario si necesitas seleccionar un subconjunto de recursos de ubicación. Esto se debe a que las campañas y los grupos de anuncios heredan los recursos de ubicación del nivel del cliente.

Los conjuntos de recursos de grupo por ubicación contienen un subconjunto de recursos de ubicación del conjunto de recursos de sincronización de ubicación. Puedes crear dinámicamente un conjunto de recursos de grupo por ubicación aprovechando algunas funciones del Perfil de Negocio de Google (como el filtrado por etiquetas) o los IDs y las ubicaciones de cadena. Como alternativa, puedes crear un conjunto de recursos de grupo por ubicación de forma estática.

  1. Crea un conjunto de recursos de grupo por ubicación. El conjunto de recursos de grupo por ubicación puede ser dinámico o estático.
  2. Conecta el conjunto de recursos a una campaña con o a un grupo de anuncios, según tus necesidades.
  3. (Opcional) Agrega los recursos generados anteriormente al conjunto de recursos de grupo por ubicación estático recién creado.

Para un cliente determinado, puedes crear varios conjuntos de recursos de grupo por ubicación dinámicos o estáticos.

Crea un conjunto de recursos de grupo por ubicación

Crea un AssetSet nuevo y establece location_group_parent_asset_set_id en el ID del conjunto de recursos de sincronización de ubicación creado anteriormente.

Luego, establece algunos campos según si deseas crear un conjunto de recursos de grupo por ubicación dinámico o estático.

Conjuntos de recursos dinámicos

Según el campo que establezcas en LocationSet, establece los campos según la siguiente regla:

Si estableces el siguiente campo Luego, establece el tipo en Y establece este campo como el 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

Si estableces maps_location_set cuando creas el conjunto de recursos de sincronización de ubicación set, no podrás crear un conjunto de recursos de grupo por ubicación dinámico. Esto se debe a que agregaste ubicaciones manualmente por IDs de lugar y no hay funciones de filtrado que puedas usar para este tipo de ubicaciones.

Conjuntos de recursos estáticos

Establece type en STATIC_LOCATION_GROUP. Puedes crear conjuntos de recursos de grupo por ubicación estáticos para cualquier tipo de conjunto de recursos de sincronización de ubicación, sin importar qué campos (business_profile_location_set, chain_location_set, o maps_location_set) establezcas en el LocationSet.

Para los conjuntos de recursos de grupo por ubicación estáticos, debes agregar manualmente los recursos de ubicación generados a los conjuntos de recursos de grupo por ubicación sets.

Conecta el conjunto de recursos a una campaña o a un grupo de anuncios

Usa CampaignAssetSetService.MutateCampaignAssetSets para conectar el conjunto de recursos de grupo por ubicación a tu campaña.

Como alternativa, usa AdGroupAssetSetService.MutateAdGroupAssetSets si deseas conectar el conjunto de recursos de grupo por ubicación a un grupo de anuncios.

(Opcional) Agrega los recursos de ubicación al conjunto de recursos de grupo por ubicación estático

Este paso solo es obligatorio si creaste un conjunto de recursos de grupo por ubicación estático anteriormente.

  1. Usa el informe asset_set_asset para recuperar los nombres de recursos de los recursos generados automáticamente para el conjunto de recursos de sincronización de ubicación creado anteriormente. Usa el filtrado para recuperar solo los recursos que deseas.
  2. Agrégalos al conjunto de recursos de grupo por ubicación estático con AssetSetAssetService.MutateAssetSetAssets.

Administra los IDs de ubicación del Perfil de Negocio

Cuando usas un business_profile_location_set y filtras en listing_id_filters que se recuperan del sitio web o la API del Perfil de Negocio, puede ser necesario convertir estos valores numéricos del tipo uint64 a int64. Si tu código genera un error de tiempo de ejecución que indica que el ID de ubicación del Perfil de Negocio está fuera del rango cuando lo agregas al campo repetido listing_id_filters[], es probable que debas convertirlo con cualquiera de los siguientes ejemplos:

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;
  }
}
Anterior
Creación y uso
Siguiente
Recursos automáticos