Nomes dos recursos

Hierarquia de nomes

Os nomes dos recursos usados na API Google Ads são hierárquicos, espelhando a organização das entidades no Google Ads. Quase todos os recursos são sub-recursos do Customer, o que reflete o fato de que quase todas as chamadas de API precisam segmentar uma conta específica do Google Ads. Por exemplo, campanhas, grupos de anúncios, anúncios e palavras-chave são sub-recursos de um recurso de cliente raiz.

Recurso	Nome do recurso
Cliente	customers/1234567890
Campaign	customers/1234567890/campaigns/8765432109
AdGroup	customers/1234567890/adGroups/54321098765
AdGroupAd	customers/1234567890/adGroupAds/54321098765~2109876543210

Importante: a API Google Ads usa nomes de recursos relativos e não nomes de recursos completos, como algumas outras APIs do Google.

Códigos de recurso

As entidades do Google Ads (clientes, campanhas etc.) são chamadas pelos nomes de recursos na API. No entanto, é importante observar que os próprios nomes de recursos podem ter IDs de recursos numéricos exclusivos que identificam cada objeto na hierarquia. Nesses casos, pode ser útil analisar o nome do recurso para extrair esses IDs de recursos e criar um novo.

Por exemplo, examine o nome do recurso AdGroupAd da tabela anterior:

customers/1234567890/adGroupAds/54321098765~2109876543210

Isso pode ser dividido nos IDs de recursos individuais, separados por IDs de coleções, da seguinte forma:

Componentes do nome do recurso
IDs de recursos	ID de cliente: "1234567890" ID do grupo de anúncios: "54321098765" ID do anúncio do grupo de anúncios: "2109876543210"
Códigos de coleções	"customers" "adGroupAds"

A análise dos IDs individuais permite que você crie novos nomes de recursos para fazer referência ao cliente do grupo de anúncios (customers/1234567890) ou ao grupo de anúncios (customers/1234567890/adGroupAds/54321098765).

Ponto-chave: os nomes de recursos nos corpos de solicitação e resposta JSON são mencionados no campo resourceName, não no campo name, como em outras APIs do Google Cloud. Muitas entidades do Google Ads têm atributos de nome (campaign.Name, adGroup.Name etc.). Portanto, a resourceName é usada para evitar colisões com nomes de objetos existentes.

Identificadores de objetos compartilhados

A maioria dos objetos da API está associada a um único cliente específico do Google Ads. No entanto, há alguns tipos de objetos que podem ser compartilhados entre várias contas. Na prática, isso inclui itens como listas de palavras-chave negativas ou ações de conversão de várias contas que geralmente são criadas por administradores e compartilhadas com muitas contas de cliente.

Os nomes de recursos desses objetos serão diferentes dependendo da conta à qual você está enviando uma chamada de API.

Exemplo: ações de conversão de várias contas

Suponha que temos a conta de administrador 987-654-3210 que compartilha uma ação de conversão de várias contas com uma das contas de cliente do cliente 123-456-7890:

Uma chamada de API para a conta de administrador, por exemplo, para atualizar a janela de lookback da ação de conversão faria referência ao objeto compartilhado usando o nome do recurso: customers/9876543210/conversionActions/257733534.

Uma chamada de API à conta do cliente para ativar o uso da ação de conversão compartilhada faria referência a ela usando o nome do recurso: customers/1234567890/conversionActions/257733534.

Esta é a mesma ação de conversão subjacente, mas o nome do recurso é relativo à conta usada para acessá-la.