Informazioni sul modello di accesso a Google Ads

Esistono due tipi di account Google Ads: account amministratore Google Ads e account inserzionista Google Ads. Per una spiegazione dettagliata della relazione tra questi termini e altri (come Account cliente e Cliente), consulta Tipi di account.

Gli account amministratore possono gestire altri account amministratore Google Ads o account inserzionista Google Ads. Puoi collegare un account inserzionista a un account amministratore e poi gestire l'account inserzionista tramite l'account amministratore. La struttura collegata complessiva è un grafo diretto aciclico con account inserzionista a livello di foglia.

Puoi concedere l'accesso agli account Google Ads a singoli utenti o service account. Esistono due modi per concedere agli utenti l'accesso a un account inserzionista:

• Concedi all'utente l'accesso diretto all'account inserzionista invitandolo a quell'account.
• Concedi all'utente l'accesso indiretto all'account inserzionista invitandolo a un account amministratore collegato a quell'account. L'utente ottiene l'accesso all'account inserzionista perché l'account amministratore ha accesso a tutti gli account collegati.

Puoi anche assegnare ruoli utente quando inviti un utente a gestire un account.

Considera la seguente gerarchia di account. Supponiamo che tutti gli utenti abbiano l'accesso standard.

La seguente tabella riassume questa struttura dell'account.

Utente	Ha accesso diretto a	Ha accesso indiretto a
U1, SA1	M1	M2, A1, A2, A3
U2	M2, M3	A1, A2, A3, A4
U3	A4

ID cliente di accesso

Un utente può avere accesso a più gerarchie di account. In questi casi, quando effettui una chiamata API, devi specificare l'account principale da utilizzare per determinare correttamente i livelli di autorizzazione e i livelli di accesso all'account. Per farlo, includi l'intestazione login-customer-id nella richiesta API.

La tabella seguente utilizza la gerarchia degli account dell'esempio precedente per mostrare gli ID cliente di accesso che puoi utilizzare e l'elenco corrispondente di account a cui puoi effettuare chiamate.

Utente	ID cliente di accesso da utilizzare	Account per effettuare chiamate API
U1, SA1	M1	M1, M2, A1, A2, A3
U2	M2	M2, A1, A2, A3
U2	M3	M3, A1, A4
U3	A4	A4

Puoi saltare l'inserimento dell'intestazione login-customer-id se l'utente ha accesso diretto all'account Google Ads a cui stai effettuando le chiamate. Ad esempio, non è necessario specificare l'intestazione login-customer-id quando utilizzi le credenziali U3 per effettuare una chiamata a A4, poiché i server Google Ads possono determinare correttamente il livello di accesso dall'ID cliente (A4).

Se utilizzi una libreria client dell'API Google Ads, utilizza le seguenti impostazioni per specificare l'intestazione login-customer-id.

Java

Aggiungi la seguente impostazione al file ads.properties.

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

.NET

Aggiungi la seguente impostazione quando inizializzi l'oggetto GoogleAdsConfig e utilizzala per creare un oggetto GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    // ...
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);

Python

Aggiungi la seguente impostazione al file google-ads.yaml.

login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

PHP

Aggiungi la seguente impostazione al file google_ads_php.ini.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

Ruby

Aggiungi la seguente impostazione al file google_ads_config.rb.

Google::Ads::GoogleAds::Config.new do |c|
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

Crea un'istanza GoogleAdsClient passando il percorso in cui conservi questo file.

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

Perl

Aggiungi la seguente impostazione al file googleads.properties.

loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

curl

Specifica il seguente argomento della riga di comando quando esegui il comando curl.

-H "login-customer-id: INSERT_LOGIN_CUSTOMER_ID_HERE"

Puoi utilizzare il metodo CustomerService.ListAccessibleCustomers per recuperare l'elenco degli account a cui un utente ha accesso diretto. Questi account possono essere utilizzati come valori validi per l'intestazione 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.V26.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,
#   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}" \
list_accessible_customers.sh
      

Che cosa succede se il metodo ListAccessibleCustomers non recupera il mio ID cliente?

Se il metodo CustomerService.ListAccessibleCustomers non ha recuperato un ID cliente che ti aspettavi di visualizzare nei risultati, esistono alcune possibili spiegazioni.

1. Hai accesso all'ID cliente, ma l'accesso viene concesso tramite un account amministratore principale. Ad esempio, se chiami il metodo ListAccessibleCustomers con le credenziali dell'utente U1 nell'esempio precedente, il metodo restituisce solo M1 nei risultati, anche se U1 ha accesso ad altri account. Per confermare questa possibilità, recupera la gerarchia degli account eseguendo query search o searchStream sulla risorsa customer_client per ciascuno degli account restituiti dal metodo ListAccessibleCustomers. Per farlo, imposta ciascuno di questi account come login-customer-id, come descritto nella sezione precedente. Se hai accesso all'account di destinazione, puoi recuperarlo come parte di una delle gerarchie di account.

2. Stai utilizzando credenziali OAuth errate. Lo scenario più comune è che stai utilizzando le credenziali di un altro utente. Ad esempio, potrebbe essere dovuto alla confusione accidentale delle credenziali della sandbox o dello sviluppatore con quelle di produzione o alla lettura errata delle credenziali di un altro utente dal database o dalla cache locale. Un modo possibile per risolvere questo problema è utilizzare l'API Google People per recuperare il nome e l'indirizzo email dell'utente che ha eseguito l'accesso e verificare se corrisponde all'indirizzo email previsto.

3. Non hai accesso all'account. Segui la guida all'accesso all'account per ottenere l'accesso all'account cliente corretto.

Ruoli utente

L'API Google Ads non ha un modello di accesso separato né utilizza ambiti OAuth 2.0 separati per limitare la funzionalità. Ad esempio, l'API Google Ads utilizza gli stessi ambiti per le operazioni di sola lettura e di lettura/scrittura. L'API Google Ads segue invece gli stessi ruoli utente supportati da Google Ads. Quando un ruolo utente viene concesso a un account a livello di amministratore, il ruolo viene ereditato dagli account nella gerarchia. Se un utente ha ruoli in conflitto per un determinato account, il livello corretto viene risolto dall'account login-customer-id specificato nella richiesta API.

La tabella seguente utilizza la gerarchia degli account dell'esempio precedente e mostra l'effetto della concessione di vari ruoli utente agli utenti.

Utente	Ruolo utente concesso	login-customer-id	Livello di accesso effettivo
SA1	Accesso standard all'account M1	M1	Accesso standard su M1, M2, A1, A2, A3
U2	Accesso standard su M2 Accesso di sola lettura su M3	M2	Accesso standard su M2, A1, A2, A3
U2	Accesso standard su M2 Accesso di sola lettura su M3	M3	Accesso di sola lettura su M3, A1, A4