Entenda o modelo de acesso do Google Ads

Há dois tipos de contas do Google Ads: contas de administrador do Google Ads e contas de anunciante do Google Ads (também conhecidas como contas de cliente). As contas de administrador podem gerenciar outras contas de administrador ou 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 gráfico 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:

  • Conceda ao usuário acesso direto à conta do anunciante convidando-o para ela.
  • Conceda ao usuário acesso indireto à conta do 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.

Você também pode 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.

Diagrama de uma hierarquia de contas

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, é necessário especificar a conta raiz a ser usada para determinar corretamente os níveis de autorização e acesso à conta. Isso é feito especificando um cabeçalho login-customer-id como parte da 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 as 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ê estiver usando uma das nossas bibliotecas de cliente, use as seguintes configurações para especificar o cabeçalho login-customer-id.

Java

Adicione a seguinte configuração ao arquivo ads.properties.

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

C#

Adicione a seguinte configuração ao inicializar o objeto GoogleAdsConfig e use-o para criar um objeto GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    ...
    LoginCustomerId = ******
};
GoogleAdsClient client = new GoogleAdsClient(config);

PHP

Adicione a seguinte configuração ao arquivo google_ads_php.ini.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

Python

Adicione a seguinte configuração ao arquivo google-ads.yaml.

login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

Ruby

Adicione a seguinte configuração ao 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 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: LOGIN_CUSTOMER_ID"

Você pode usar 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);
    }
  }
}
ListAccessibleCustomers.java

C#

public void Run(GoogleAdsClient client)
{
    // Get the CustomerService.
    CustomerServiceClient customerService = client.GetService(Services.V21.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;
    }
}
ListAccessibleCustomers.cs

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);
    }
}
ListAccessibleCustomers.php

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}"')
list_accessible_customers.py

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
list_accessible_customers.rb

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;
}
list_accessible_customers.pl

curl

# Returns the resource names of customers directly accessible by the user
# authenticating the call.
#
# Variables:
#   API_VERSION,
#   DEVELOPER_TOKEN,
#   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 "developer-token: ${DEVELOPER_TOKEN}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
list_accessible_customers.sh

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 funções conflitantes em uma determinada conta, o nível correto será resolvido pela conta login-customer-id especificada na solicitação da 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
Anterior
Visão geral
Avançar
Fluxo de trabalho da conta de serviço