Recursos de local

Ao contrário de outros recursos, os de local são criados automaticamente pela API Google Ads depois que você cria um conjunto de recursos. Primeiro, crie um conjunto de recursos de sincronização de local e vincule-o ao cliente. Em seguida, se você precisar selecionar um subconjunto dos recursos de local no conjunto de recursos de uma campanha ou grupo de anúncios, crie um conjunto de recursos de grupo por locais e anexe-o à campanha ou ao grupo de anúncios.

Criar um conjunto de recursos de sincronização de local e anexá-lo ao cliente

  1. Crie um conjunto de recursos de sincronização de local.
  2. Anexe-o a um cliente usando CustomerAssetSetService.

Criar um conjunto de recursos de sincronização de local

  1. Crie um novo AssetSet.
    1. Defina type como LOCATION_SYNC.
    2. Defina location_set como um novo LocationSet.

  2. No novo LocationSet,

    1. Defina location_ownership_type com base no seu caso de uso:
      • Defina como BUSINESS_OWNER se você for o proprietário do local da empresa.
      • Defina como AFFILIATE se você não for o proprietário do local da empresa, mas vender seus produtos lá.

    2. Defina o campo oneof source com base no seu caso de uso:

      • Defina business_profile_location_set se quiser sincronizar com os locais na sua conta do Perfil da Empresa no Google.

        Ao criar um BusinessProfileLocationSet para vincular o Google Ads a uma conta do Perfil da Empresa no Google, você precisa fornecer um token de acesso do OAuth 2.0 no campo http_authorization_token. Esse token comprova que você está autorizando o Google Ads a acessar os dados de local do Perfil da Empresa no Google especificado.

        O token precisa atender a estes requisitos:

        • Ele precisa ser gerado para a Conta do Google (conta de usuário ou de serviço) com o endereço de e-mail fornecido no campo email_address do BusinessProfileLocationSet.
        • Essa conta precisa ter permissões suficientes para ler os locais da empresa no Perfil da Empresa no Google.
        • O token do OAuth 2.0 precisa ser recebido com o escopo https://www.googleapis.com/auth/business.manage.

        Para instruções detalhadas sobre como gerar um token de acesso do OAuth 2.0, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.

      • Defina chain_location_set se quiser sincronizar com locais em IDs de rede especificados.

      • Defina maps_location_set se quiser adicionar locais manualmente usando IDs de lugar.

Depois que você concluir essas etapas, a API Google Ads vai gerar recursos de local e adicioná-los ao conjunto de recursos de sincronização de local criado para você, de forma semelhante ao que acontece quando você faz isso manualmente usando AssetSetAssetService. Não é necessário manipulá-los, a menos que você queira adicioná-los manualmente a um conjunto de recursos de grupo por locais estático.

Só pode haver um conjunto de recursos de sincronização de local ativo com status definido como ENABLED para um cliente. Se você precisar criar um tipo diferente de conjunto de recursos de sincronização de local, remova o atual primeiro.

Anexar o conjunto de recursos de sincronização de local a um cliente

Use CustomerAssetSetService.MutateCustomerAssetSets para anexar o conjunto de recursos de sincronização de local definido na seção anterior ao seu cliente.

(Opcional) Criar um conjunto de recursos de grupo por locais e anexá-lo a uma campanha ou um grupo de anúncios

Um conjunto de recursos de grupo por locais só é necessário se você precisar selecionar um subconjunto de recursos de local. Isso ocorre porque as campanhas e os grupos de anúncios herdam os recursos de local do nível do cliente.

Os conjuntos de recursos de grupos por locais contêm um subconjunto de recursos de local do conjunto de recursos de sincronização de local. É possível criar dinamicamente um conjunto de recursos de grupo por locais usando alguns recursos do Perfil da Empresa no Google (como filtragem por rótulos) ou IDs e locais de redes. Como alternativa, é possível criar estaticamente um conjunto de recursos de grupo por locais.

  1. Crie um conjunto de recursos de grupo por locais. O conjunto de recursos do grupo por locais pode ser dinâmico ou estático.
  2. Anexe o conjunto de recursos a uma campanha ou a um grupo de anúncios, dependendo da sua necessidade.
  3. (Opcional) Adicione os recursos gerados anteriormente ao conjunto de recursos do grupo por locais estático recém-criado.

Para um determinado cliente, é possível criar vários conjuntos de recursos de grupos por locais dinâmicos ou estáticos.

Criar um conjunto de recursos de grupo por locais

Crie um novo AssetSet e defina location_group_parent_asset_set_id como o ID do conjunto de recursos de sincronização de local criado anteriormente.

Em seguida, defina alguns campos com base no tipo de conjunto de recursos de grupo por locais que você quer criar: dinâmico ou estático.

Conjuntos de recursos dinâmicos

Dependendo do campo definido em LocationSet, defina os campos com base na seguinte regra:

Se você definir o seguinte campo Em seguida, defina type como Defina esse campo como o 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 você definir maps_location_set ao criar o conjunto de recursos de sincronização de local, não será possível criar um conjunto de recursos de grupo por locais dinâmico. Isso ocorre porque você adicionou locais manualmente por IDs de lugar, e não há recursos de filtragem que possam ser usados para esse tipo de local.

Conjuntos de recursos estáticos

Defina type como STATIC_LOCATION_GROUP. É possível criar conjuntos de recursos de grupos por locais estáticos para qualquer tipo de conjunto de recursos de sincronização de local, independentemente dos campos (business_profile_location_set, chain_location_set ou maps_location_set) definidos no LocationSet.

Para conjuntos de recursos de grupos por locais estáticos, é necessário adicionar manualmente os recursos de local gerados aos conjuntos de recursos de grupos por locais.

Anexe o conjunto de recursos a uma campanha ou a um grupo de anúncios.

Use CampaignAssetSetService.MutateCampaignAssetSets para anexar o conjunto de recursos de grupo por locais à sua campanha.

Como alternativa, use AdGroupAssetSetService.MutateAdGroupAssetSets se quiser anexar o conjunto de recursos do grupo por locais a um grupo de anúncios.

(Opcional) Adicione os recursos de local ao conjunto de recursos de grupo por locais estáticos.

Essa etapa só é necessária se você tiver criado um conjunto de recursos de grupo por locais estático anteriormente.

  1. Use o relatório asset_set_asset para buscar os nomes de recursos gerados automaticamente para o conjunto de recursos de sincronização de local criado anteriormente. Use a filtragem para recuperar apenas os recursos que você quer.
  2. Adicione-os ao conjunto de recursos do grupo por locais estático usando AssetSetAssetService.MutateAssetSetAssets.

Gerenciar IDs de local do Perfil da Empresa

Ao usar um business_profile_location_set e filtrar em listing_id_filters que são recuperados do site ou da API do Perfil da Empresa, pode ser necessário converter esses valores numéricos do tipo uint64 para int64. Se o código gerar um erro de tempo de execução informando que o ID do local do Perfil da Empresa está fora do intervalo ao adicioná-lo ao campo repetido listing_id_filters[], provavelmente será necessário convertê-lo usando um dos seguintes exemplos:

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
Criação e utilização
Avançar
Recursos automatizados