Há dois tipos de contas do Google Ads: contas de administrador do Google Ads e contas de anunciante do Google Ads. Para uma explicação detalhada de como esses termos e outros (como "Conta de cliente" e "Cliente") se relacionam, consulte Tipos de conta.
As contas de administrador podem gerenciar outras contas de administrador do Google Ads ou contas de anunciante do Google Ads. Você pode vincular uma conta de anunciante a uma conta de administrador e gerenciar a conta de anunciante pela conta de administrador. A estrutura vinculada geral é um grafo acíclico direcionado com contas de anunciante no nível da folha.
É possível conceder acesso a contas do Google Ads para usuários individuais ou contas de serviço. Há duas maneiras de dar acesso a uma conta de anunciante:
- Convide o usuário para a conta de anunciante para conceder acesso direto.
- Conceda ao usuário acesso indireto à conta de anunciante convidando-o para uma conta de administrador vinculada a ela. O usuário ganha acesso à conta de anunciante porque a conta de administrador tem acesso a todas as contas vinculadas a ela.
Também é possível atribuir funções de usuário ao convidar alguém para gerenciar uma conta.
Considere a seguinte hierarquia de contas. Suponha que todos os usuários tenham acesso padrão.

A tabela a seguir resume essa estrutura de conta.
| Usuário | Tem acesso direto a | Tem acesso indireto a |
|---|---|---|
| U1, SA1 | M1 | M2, A1, A2, A3 |
| U2 | M2, M3 | A1, A2, A3, A4 |
| U3 | A4 |
ID de cliente de login
Um usuário pode ter acesso a várias hierarquias de contas. Ao fazer uma chamada de API
nesses casos, especifique a conta raiz a ser usada para determinar corretamente
os níveis de autorização e acesso à conta. Para isso, inclua o cabeçalho
login-customer-id na sua solicitação de API.
A tabela a seguir usa a hierarquia de contas do exemplo anterior para mostrar quais IDs de cliente de login podem ser usados e a lista correspondente de contas que podem ser chamadas.
| Usuário | ID de cliente de login para usar | Contas para fazer chamadas de API |
|---|---|---|
| U1, SA1 | M1 | M1, M2, A1, A2, A3 |
| U2 | M2 | M2, A1, A2, A3 |
| U2 | M3 | M3, A1, A4 |
| U3 | A4 | A4 |
Você pode pular o fornecimento do cabeçalho login-customer-id se o usuário tiver acesso direto à conta do Google Ads para a qual você está fazendo chamadas. Por exemplo, não é necessário especificar o cabeçalho login-customer-id ao usar credenciais U3 para fazer uma chamada para A4, já que os servidores do Google Ads podem determinar corretamente o nível de acesso do ID do cliente (A4).
Se você usar uma biblioteca de cliente da API Google Ads, use as seguintes
configurações para especificar o cabeçalho login-customer-id.
Java
Adicione a seguinte configuração ao seu arquivo ads.properties.
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
.NET
Adicione a seguinte configuração ao inicializar o objeto GoogleAdsConfig
e use-o para criar um objeto GoogleAdsClient.
GoogleAdsConfig config = new GoogleAdsConfig()
{
// ...
LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);
Python
Adicione a seguinte configuração ao seu arquivo google-ads.yaml.
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
PHP
Adicione a seguinte configuração ao seu arquivo google_ads_php.ini.
[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
Ruby
Adicione a seguinte configuração ao seu arquivo google_ads_config.rb.
Google::Ads::GoogleAds::Config.new do |c|
c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end
Crie uma instância GoogleAdsClient transmitindo o caminho para onde você mantém
esse arquivo.
client = Google::Ads::GoogleAds::GoogleAdsClient.new(
'path/to/google_ads_config.rb'
)
Perl
Adicione a seguinte configuração ao seu arquivo googleads.properties.
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
curl
Especifique o seguinte argumento de linha de comando ao executar o comando curl.
-H "login-customer-id: INSERT_LOGIN_CUSTOMER_ID_HERE"Use o método
CustomerService.ListAccessibleCustomers
para recuperar a lista de contas a que um usuário tem acesso direto.
Essas contas podem ser usadas como valores válidos para o cabeçalho login-customer-id.
Java
private void runExample(GoogleAdsClient client) { // Optional: Change credentials to use a different refresh token, to retrieve customers // available for a specific user. // // UserCredentials credentials = // UserCredentials.newBuilder() // .setClientId("INSERT_OAUTH_CLIENT_ID") // .setClientSecret("INSERT_OAUTH_CLIENT_SECRET") // .setRefreshToken("INSERT_REFRESH_TOKEN") // .build(); // // client = client.toBuilder().setCredentials(credentials).build(); try (CustomerServiceClient customerService = client.getLatestVersion().createCustomerServiceClient()) { ListAccessibleCustomersResponse response = customerService.listAccessibleCustomers( ListAccessibleCustomersRequest.newBuilder().build()); System.out.printf("Total results: %d%n", response.getResourceNamesCount()); for (String customerResourceName : response.getResourceNamesList()) { System.out.printf("Customer resource name: %s%n", customerResourceName); } } }
C#
public void Run(GoogleAdsClient client) { // Get the CustomerService. CustomerServiceClient customerService = client.GetService(Services.V25.CustomerService); try { // Retrieve the list of customer resources. string[] customerResourceNames = customerService.ListAccessibleCustomers(); // Display the result. foreach (string customerResourceName in customerResourceNames) { Console.WriteLine( $"Found customer with resource name = '{customerResourceName}'."); } } catch (GoogleAdsException e) { Console.WriteLine("Failure:"); Console.WriteLine($"Message: {e.Message}"); Console.WriteLine($"Failure: {e.Failure}"); Console.WriteLine($"Request ID: {e.RequestId}"); throw; } }
PHP
public static function runExample(GoogleAdsClient $googleAdsClient) { $customerServiceClient = $googleAdsClient->getCustomerServiceClient(); // Issues a request for listing all accessible customers. $accessibleCustomers = $customerServiceClient->listAccessibleCustomers(new ListAccessibleCustomersRequest()); print 'Total results: ' . count($accessibleCustomers->getResourceNames()) . PHP_EOL; // Iterates over all accessible customers' resource names and prints them. foreach ($accessibleCustomers->getResourceNames() as $resourceName) { /** @var string $resourceName */ printf("Customer resource name: '%s'%s", $resourceName, PHP_EOL); } }
Python
def main(client: GoogleAdsClient) -> None: customer_service: CustomerServiceClient = client.get_service( "CustomerService" ) accessible_customers: ListAccessibleCustomersResponse = ( customer_service.list_accessible_customers() ) result_total: int = len(accessible_customers.resource_names) print(f"Total results: {result_total}") resource_names: List[str] = accessible_customers.resource_names for resource_name in resource_names: # resource_name is implicitly str print(f'Customer resource name: "{resource_name}"')
Ruby
def list_accessible_customers() # GoogleAdsClient will read a config file from # ENV['HOME']/google_ads_config.rb when called without parameters client = Google::Ads::GoogleAds::GoogleAdsClient.new accessible_customers = client.service.customer.list_accessible_customers().resource_names accessible_customers.each do |resource_name| puts "Customer resource name: #{resource_name}" end end
Perl
sub list_accessible_customers { my ($api_client) = @_; my $list_accessible_customers_response = $api_client->CustomerService()->list_accessible_customers(); printf "Total results: %d.\n", scalar @{$list_accessible_customers_response->{resourceNames}}; foreach my $resource_name (@{$list_accessible_customers_response->{resourceNames}}) { printf "Customer resource name: '%s'.\n", $resource_name; } return 1; }
curl
# Returns the resource names of customers directly accessible by the user # authenticating the call. # # Variables: # API_VERSION, # OAUTH2_ACCESS_TOKEN: # See https://developers.google.com/google-ads/api/rest/auth#request_headers # for details. # curl -f --request GET \ "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
E se o método ListAccessibleCustomers não recuperar meu ID de cliente?
Se o método CustomerService.ListAccessibleCustomers
não recuperou um ID de cliente que você esperava ver nos resultados,
confira algumas explicações possíveis.
Você tem acesso ao ID de cliente, mas ele foi emitido por uma conta de administrador principal. Por exemplo, se você chamar o método
ListAccessibleCustomerscom as credenciais do usuárioU1no exemplo anterior, o método vai retornar apenasM1nos resultados, mesmo queU1tenha acesso a mais contas. Para confirmar essa possibilidade, recupere a hierarquia da conta executando consultassearchousearchStreamno recursocustomer_clientpara cada uma das contas retornadas pelo métodoListAccessibleCustomers. Para fazer isso, defina cada uma dessas contas comologin-customer-id, conforme descrito na seção anterior. Se você tiver acesso à conta de destino, poderá buscá-la como parte de uma das hierarquias de contas.Você está usando credenciais OAuth incorretas. O cenário mais comum é que você esteja usando as credenciais de outro usuário. Por exemplo, isso pode acontecer devido à mistura acidental de credenciais de sandbox ou de desenvolvedor com credenciais de produção ou à leitura incorreta das credenciais de outro usuário no banco de dados ou no cache local. Uma maneira possível de resolver esse problema é usar a API Google People para recuperar o nome e o endereço de e-mail do usuário conectado e verificar se eles correspondem ao endereço de e-mail esperado.
Você não tem acesso à conta. Siga o guia de acesso à conta para acessar a conta de cliente correta.
Papéis do usuário
A API Google Ads não tem um modelo de acesso separado nem usa escopos do OAuth 2.0 separados para limitar a funcionalidade. Por exemplo, a API Google Ads usa os mesmos
escopos para operações somente leitura e leitura/gravação. Em vez disso, a API Google Ads segue as mesmas funções de usuário compatíveis com o Google Ads. Quando uma função de usuário é concedida a uma conta no nível do administrador, ela é herdada pelas contas na hierarquia. Se um usuário tiver papéis conflitantes em uma determinada conta, o nível correto será resolvido pela conta login-customer-id especificada na solicitação de API.
A tabela a seguir usa a hierarquia de contas do exemplo anterior e mostra o efeito da concessão de várias funções de usuário.
| Usuário | Função do usuário concedida | login-customer-id | Nível de acesso efetivo |
|---|---|---|---|
| SA1 | Acesso padrão na conta M1 | M1 | Acesso padrão em M1, M2, A1, A2 e A3 |
| U2 |
Acesso padrão no M2 Acesso somente leitura no M3 |
M2 | Acesso padrão em M2, A1, A2 e A3 |
| U2 |
Acesso padrão no M2 Acesso somente leitura no M3 |
M3 | Acesso somente leitura no M3, A1 e A4 |