Nomes dos recursos

Hierarquia de nomes

Os nomes de recursos usados na API Google Ads são hierárquicos, refletindo a organização das entidades no Google Ads. Quase todos os recursos são sub-recursos do Customer recurso, 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 todos 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

Ponto-chave: a API Google Ads usa nomes de recursos relativos (e não nomes de recursos completos como algumas outras APIs do Google).

IDs de recursos

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

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

customers/1234567890/adGroupAds/54321098765~2109876543210

Ele pode ser dividido em IDs de recursos individuais (separados por IDs de coleção) da seguinte maneira:

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"
IDs de coleção	"customers" "adGroupAds"

A análise dos IDs individuais permite derivar novos nomes de recursos para referenciar o cliente do anúncio do grupo de anúncios (customers/1234567890) ou o grupo de anúncios (customers/1234567890/adGroupAds/54321098765).

Importante: os nomes de recursos nos corpos de solicitação e resposta JSON são referenciados pelo campo resourceName, não pelo name campo, como em algumas outras APIs do Google Cloud. Muitas entidades do Google Ads têm atributos de nome (campaign.Name, adGroup.Name etc.), então resourceName é usado para evitar conflitos com nomes de objetos atuais.

Identificadores de objetos compartilhados

A maioria dos objetos na 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, são coisas como listas de palavras-chave negativas ou ações de conversão de várias contas que são geralmente criadas por administradores e compartilhadas com muitas contas de clientes.

Os nomes de recursos de objetos como esses vão variar, dependendo da conta para a qual você está enviando uma chamada de API.

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

Suponha que temos a conta de admin 987-654-3210 que compartilha uma ação de conversão de várias contas com uma de suas relações de cliente 123-456-7890:

Fazer uma chamada de API para a conta de admin para, por exemplo, atualizar a janela de lookback da ação de conversão, referenciaria o objeto compartilhado usando o nome do recurso: customers/9876543210/conversionActions/257733534.

Fazer uma chamada de API para a conta de cliente para ativar o uso da ação de conversão compartilhada a referenciaria usando o nome do recurso: customers/1234567890/conversionActions/257733534.

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