Informazioni sul modello di accesso a Google Ads

Esistono due tipi di account Google Ads: account amministratore Google Ads e account inserzionista Google Ads (noti anche come account cliente). 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 aciclico diretto con gli account inserzionista a livello di foglia.

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

  • Concedi all'utente l'accesso diretto all'account inserzionista invitandolo a questo 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 poiché 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 dell'account. Supponi che tutti gli utenti abbiano accesso standard.

Diagramma di una gerarchia di account

La seguente tabella riepiloga 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. Quando effettui una chiamata API in questi casi, devi specificare l'account principale da utilizzare per determinare correttamente i livelli di autorizzazione e accesso all'account. A questo scopo, specifica un'intestazione login-customer-id nell'ambito della richiesta API.

La tabella seguente utilizza la gerarchia dell'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 la fornitura dell'intestazione login-customer-id se l'utente ha accesso diretto all'account Google Ads a cui stai effettuando chiamate. Ad esempio, non devi 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 delle nostre librerie client, 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

C#

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

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

PHP

Aggiungi la seguente impostazione al file google_ads_php.ini.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

Python

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

login_customer_id: 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: LOGIN_CUSTOMER_ID"

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.V22.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

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, nei risultati riceverai solo M1, anche se U1 ha accesso a più account. Per confermare questa possibilità, recupera la gerarchia dell'account per ciascuno degli account restituiti dal metodo ListAccessibleCustomers. Per farlo, imposta ciascuno di questi account come ID cliente di accesso, come descritto nella sezione precedente. Se hai accesso all'account di destinazione, dovresti essere in grado di recuperarlo nell'ambito 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 a un'errata combinazione di credenziali sandbox o sviluppatore con credenziali 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 corrispondono all'indirizzo email che ti aspettavi.

  3. Non hai accesso all'account. Segui le istruzioni per ottenere l'accesso all'account cliente corretto.

Ruoli utente

L'API Google Ads non ha un proprio 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 lettura/scrittura. L'API Google Ads segue 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 in sola lettura su M3
 M2 Accesso standard su M2, A1, A2, A3
U2 Accesso standard su M2
Accesso in sola lettura su M3
 M3 Accesso in sola lettura su M3, A1, A4
Indietro
Panoramica
Avanti
Flusso di lavoro del service account