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 et ensuite gérer le compte annonceur via le compte administrateur. La structure globale associée est un graphe orienté acyclique avec des comptes annonceur au niveau de la feuille.

Vous pouvez accorder à des utilisateurs individuels ou à des comptes de service l'accès à des comptes Google Ads. Il existe deux façons d'accorder l'accès à un compte annonceur :

  • Accorder à l'utilisateur un accès direct au compte annonceur en l'invitant à rejoindre ce compte.
  • Accorder à l'utilisateur un accès indirect au compte 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.

Prenons l'exemple de la hiérarchie de comptes suivante. Supposons que tous les utilisateurs disposent d'un accès standard.

Schéma d'une hiérarchie de comptes

Le tableau suivant récapitule cette structure de compte.

Utilisateur A accès direct à A 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, spécifiez un en-tête login-customer-id dans la requête API.

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

Utilisateur Numéro client utilisé pour la connexion à utiliser Comptes à appeler via l'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 omettre l'en-tête login-customer-id si l'utilisateur a un accès direct au compte Google Ads que vous appelez. Par exemple, vous n'avez pas besoin de spécifier l'en-tête login-customer-id lorsque vous utilisez les identifiants U3 pour appeler A4, car les serveurs Google Ads peuvent déterminer correctement le niveau d'accès à partir du numéro client (A4).

Si vous utilisez l'une de nos bibliothèques clientes, 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

C#

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

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

PHP

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

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

Python

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

login_customer_id: 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 où vous conservez 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: LOGIN_CUSTOMER_ID"

Vous pouvez utiliser la CustomerService.ListAccessibleCustomers méthode 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.V24.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,
#   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}" \

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é un numéro client que vous vous attendiez à voir apparaître dans les résultats, plusieurs explications sont possibles.

  1. Vous avez accès au numéro client, mais l'accès est émis via un compte administrateur parent. Par exemple, si vous appelez la ListAccessibleCustomers méthode avec les identifiants de l'utilisateur U1 dans l'exemple précédent, vous ne recevrez que M1 dans les résultats, même si U1 a accès à davantage de comptes. Pour confirmer cette possibilité, récupérez la hiérarchie de comptes 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 devriez pouvoir 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 de développeur et les identifiants de production, ou à une lecture incorrecte des identifiants d'un autre utilisateur dans la base de données ou le cache local. Pour résoudre ce problème, vous pouvez 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 les instructions pour obtenir l'accès 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 de scopes OAuth 2.0 distincts pour limiter les fonctionnalités. Par exemple, l'API Google Ads utilise les mêmes scopes pour les opérations en lecture seule et en lecture/écriture. Au lieu de cela, l'API Google Ads suit les mêmes rôles utilisateur que ceux compatibles avec 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 a des rôles conflictuels pour un compte donné, le niveau correct est résolu par le login-customer-id compte spécifié dans la requête API.

Le tableau suivant utilise la hiérarchie de comptes 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 à M1, M2, A1, A2, A3
U2 Accès standard à M2
Accès en lecture seule à M3
 M2 Accès standard à M2, A1, A2, A3
U2 Accès standard à M2
Accès en lecture seule à M3
 M3 Accès en lecture seule à M3, A1, A4
Précédent
Aperçu
Suivant
Workflow du compte de service