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 ubicaciones y adjúntalo 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 adjúntalo a la campaña o al grupo de anuncios.

Crea un conjunto de recursos de sincronización de ubicaciones y adjúntalo al cliente

  1. Crea un conjunto de recursos de sincronización de ubicaciones.
  2. Adjúntalo a un cliente con CustomerAssetSetService.

Crea un conjunto de recursos de sincronización de ubicaciones

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

  2. En la nueva LocationSet,

    1. Establece location_ownership_type según tu caso de uso:
      • Establécelo en BUSINESS_OWNER si eres el propietario de la ubicación de la empresa.
      • Establécelo en AFFILIATE si no eres el 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 sincronizar con tus ubicaciones en tu cuenta del Perfil de Negocio de Google.

        Cuando creas un BusinessProfileLocationSet para vincular Google Ads con una cuenta de 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 (cuenta de usuario o de servicio) cuya dirección de correo electrónico se proporciona en el campo email_address del 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 permiso 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 sincronizar con ubicaciones en los IDs de cadena especificados.

      • Establece maps_location_set si deseas agregar ubicaciones de forma manual con los 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 ubicaciones creado, de forma similar a cuando lo haces manualmente con AssetSetAssetService. No necesitas manipularlos, a menos que quieras agregarlos manualmente a un conjunto de recursos de grupo por ubicación estático.

Solo puede existir un conjunto de recursos de sincronización de ubicaciones activo con status establecido en ENABLED para un cliente. Si necesitas crear un tipo diferente de conjunto de recursos de sincronización de ubicaciones, primero quita el existente.

Cómo adjuntar el conjunto de recursos de sincronización de ubicaciones a un cliente

Usa CustomerAssetSetService.MutateCustomerAssetSets para adjuntar el conjunto de recursos de sincronización de ubicaciones que creaste en la sección anterior a tu cliente.

Opcional: Crea un conjunto de recursos de grupo por ubicación y adjúntalo a una campaña o un grupo de anuncios

Solo se necesita un conjunto de recursos de grupo por ubicación 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 de cliente.

Los conjuntos de recursos de grupos por ubicación contienen un subconjunto de recursos de ubicación del conjunto de recursos de sincronización de ubicaciones. Puedes crear de forma dinámica 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 cadenas. Como alternativa, puedes crear de forma estática un conjunto de recursos de grupos por ubicación.

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

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

Crea un conjunto de recursos de grupos por ubicación

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

Luego, configura algunos campos en función de si deseas crear un conjunto de recursos de grupos por ubicación dinámico o estático.

Conjuntos de recursos dinámicos

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

Si configuras 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 ubicaciones, no podrás crear un conjunto de recursos de grupo por ubicación dinámico. Esto se debe a que agregaste ubicaciones de forma manual por ID de lugar y no hay funciones de filtrado que puedas usar para este tipo de ubicaciones.

Conjuntos de recursos estáticos

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

En el caso de los conjuntos de recursos de grupos por ubicación estáticos, debes agregar manualmente los recursos de ubicación generados a los conjuntos de recursos de grupos por ubicación.

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

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

Como alternativa, usa AdGroupAssetSetService.MutateAdGroupAssetSets si, en cambio, quieres adjuntar 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 del 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 los recursos generados automáticamente para el conjunto de recursos de sincronización de ubicaciones creado anteriormente. Usa el filtrado para recuperar solo los recursos que deseas.
  2. Agrégalos al conjunto de recursos de grupos por ubicación estáticos con AssetSetAssetService.MutateAssetSetAssets.

Cómo administrar los IDs de ubicación del Perfil de Negocio

Cuando usas un business_profile_location_set y filtras por 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 de tu Perfil de Negocio está fuera de 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 < 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;
  }
}
Anterior
Creación y uso
Siguiente
Recursos automatizados