Comprendre le modèle d'accès Google Ads

Il existe deux types de comptes Google Ads : les comptes administrateur Google Ads et les comptes annonceur Google Ads. Pour obtenir une explication détaillée de la relation entre ces termes et d'autres (comme "compte client" et "client"), consultez Types de comptes.

Les comptes administrateur peuvent gérer d'autres comptes administrateur Google Ads ou des comptes annonceur Google Ads. Vous pouvez associer un compte annonceur à un compte administrateur, puis gérer le compte annonceur depuis le compte administrateur. La structure associée globale est un graphe acyclique orienté avec des comptes d'annonceur au niveau des feuilles.

Vous pouvez accorder à des utilisateurs ou comptes de service individuels l'accès à des comptes Google Ads. Vous pouvez accorder l'accès à un compte d'annonceur de deux manières :

  • Accordez à l'utilisateur un accès direct au compte de l'annonceur en l'invitant à rejoindre ce compte.
  • Accordez à l'utilisateur un accès indirect au compte d'annonceur en l'invitant à rejoindre un compte administrateur associé à ce compte. L'utilisateur obtient l'accès au compte annonceur, car le compte administrateur a accès à tous les comptes qui y sont associés.

Vous pouvez également attribuer des rôles utilisateur lorsque vous invitez un utilisateur à gérer un compte.

Considérez la hiérarchie de compte suivante. Supposons que tous les utilisateurs disposent d'un accès standard.

Diagramme montrant les comptes administrateur M1, M2 et M3 associés aux comptes annonceur A1 à A4.

Le tableau suivant récapitule cette structure de compte.

Utilisateur a directement accès à A un accès indirect à
U1, SA1 M1 M2, A1, A2, A3
U2 M2, M3 A1, A2, A3, A4
U3 A4  

Numéro client utilisé pour la connexion

Un utilisateur peut avoir accès à plusieurs hiérarchies de comptes. Dans ce cas, lorsque vous effectuez un appel d'API, vous devez spécifier le compte racine à utiliser pour déterminer correctement les niveaux d'autorisation et d'accès au compte. Pour ce faire, incluez l'en-tête login-customer-id dans votre requête API.

Le tableau suivant utilise la hiérarchie de comptes de l'exemple précédent pour indiquer les ID client de connexion que vous pouvez utiliser, ainsi que la liste correspondante des comptes que vous pouvez appeler.

Utilisateur Numéro client utilisé pour la connexion Comptes pour effectuer des appels d'API
U1, SA1 M1 M1, M2, A1, A2, A3
U2 M2 M2, A1, A2, A3
U2 M3 M3, A1, A4
U3 A4 A4

Vous pouvez ignorer l'en-tête login-customer-id si l'utilisateur a un accès direct au compte Google Ads auquel vous envoyez des appels. Par exemple, vous n'avez pas besoin de spécifier l'en-tête login-customer-id lorsque vous utilisez des identifiants U3 pour appeler A4, car les serveurs Google Ads peuvent déterminer correctement le niveau d'accès à partir de l'ID client (A4).

Si vous utilisez une bibliothèque cliente de l'API Google Ads, utilisez les paramètres suivants pour spécifier l'en-tête login-customer-id.

Java

Ajoutez le paramètre suivant à votre fichier ads.properties.

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

.NET

Ajoutez le paramètre suivant lorsque vous initialisez l'objet GoogleAdsConfig et utilisez-le pour créer un objet GoogleAdsClient.

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

Python

Ajoutez le paramètre suivant à votre fichier google-ads.yaml.

login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

PHP

Ajoutez le paramètre suivant à votre fichier google_ads_php.ini.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

Ruby

Ajoutez le paramètre suivant à votre fichier google_ads_config.rb.

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

Créez une instance GoogleAdsClient en transmettant le chemin d'accès à l'emplacement de ce fichier.

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

Perl

Ajoutez le paramètre suivant à votre fichier googleads.properties.

loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

curl

Spécifiez l'argument de ligne de commande suivant lorsque vous exécutez la commande curl.

-H "login-customer-id: INSERT_LOGIN_CUSTOMER_ID_HERE"

Vous pouvez utiliser la méthode CustomerService.ListAccessibleCustomers pour récupérer la liste des comptes auxquels un utilisateur a un accès direct. Ces comptes peuvent être utilisés comme valeurs valides pour l'en-tête 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}" \
      

Que faire si la méthode ListAccessibleCustomers ne récupère pas mon numéro client ?

Si la méthode CustomerService.ListAccessibleCustomers n'a pas récupéré l'ID client que vous attendiez dans les résultats, plusieurs explications sont possibles.

  1. Vous avez accès au numéro client, mais cet accès est accordé par un compte administrateur parent. Par exemple, si vous appelez la méthode ListAccessibleCustomers avec les identifiants de l'utilisateur U1 dans l'exemple précédent, la méthode ne renvoie que M1 dans les résultats, même si U1 a accès à d'autres comptes. Pour confirmer cette possibilité, récupérez la hiérarchie des comptes en exécutant des requêtes search ou searchStream sur la ressource customer_client pour chacun des comptes renvoyés par la méthode ListAccessibleCustomers. Pour ce faire, définissez chacun de ces comptes comme login-customer-id, comme décrit dans la section précédente. Si vous avez accès au compte cible, vous pouvez le récupérer dans l'une des hiérarchies de comptes.

  2. Vous utilisez des identifiants OAuth incorrects. Le scénario le plus courant est que vous utilisez les identifiants d'un autre utilisateur. Par exemple, cela peut être dû à une confusion accidentelle entre les identifiants du bac à sable ou du développeur et les identifiants de production, ou à la lecture incorrecte des identifiants d'un autre utilisateur à partir de la base de données ou du cache local. Pour résoudre ce problème, vous pouvez par exemple utiliser l'API Google People afin de récupérer le nom et l'adresse e-mail de l'utilisateur connecté, et vérifier s'ils correspondent à l'adresse e-mail attendue.

  3. Vous n'avez pas accès au compte. Suivez le guide d'accès au compte pour accéder au bon compte client.

Rôles utilisateur

L'API Google Ads ne dispose pas de son propre modèle d'accès ni n'utilise d'habilitations OAuth 2.0 distinctes pour limiter les fonctionnalités. Par exemple, l'API Google Ads utilise les mêmes niveaux d'accès pour les opérations en lecture seule et en lecture/écriture. L'API Google Ads suit plutôt les mêmes rôles utilisateur que Google Ads. Lorsqu'un rôle utilisateur est accordé à un compte au niveau administrateur, il est hérité par les comptes de la hiérarchie. Si un utilisateur dispose de rôles conflictuels pour un compte donné, le niveau approprié est déterminé par le compte login-customer-id spécifié dans la requête API.

Le tableau suivant utilise la hiérarchie de compte de l'exemple précédent et montre l'effet de l'attribution de différents rôles utilisateur aux utilisateurs.

Utilisateur Rôle utilisateur accordé login-customer-id Niveau d'accès effectif
SA1 Accès standard au compte M1 M1 Accès standard sur M1, M2, A1, A2, A3
U2 Accès standard sur M2
Accès en lecture seule sur M3
M2 Accès standard sur M2, A1, A2, A3
U2 Accès standard sur M2
Accès en lecture seule sur M3
M3 Accès en lecture seule à M3, A1 et A4