Créer un compte

Pour créer un compte client, envoyez un objet Customer prérempli à l'aide de la méthode CreateCustomerClient sur CustomerService.

Contrairement à la création d'entités standards (comme la création de campagnes à l'aide d'appels mutate), vous devez spécifier l'ID client du compte administrateur dans la requête plutôt que l'ID du client en cours de création.

Champs de requête et de client

Lorsque vous appelez CustomerService.CreateCustomerClient, configurez CreateCustomerClientRequest et son objet Customer imbriqué, comme indiqué dans le tableau suivant :

Champ ou en-tête Exigence Mutabilité et description
customer_id Obligatoire Numéro client à 10 chiffres (sans tirets) du compte administrateur parent direct sous lequel le nouveau compte client est créé.
login-customer-id (en-tête) Conditionnel Obligatoire dans les en-têtes de requête si l'utilisateur authentifié accède au compte administrateur parent (customer_id) via un compte administrateur ancêtre plus haut dans la hiérarchie.
customer_client.descriptive_name Obligatoire Mutable : nom à afficher du nouveau compte (par exemple, "Acct Created with CustomerService"). Peut être mis à jour ultérieurement avec CustomerService.MutateCustomer.
customer_client.currency_code Obligatoire Immuable après la création : code de devise de facturation ISO 4217 à trois caractères (par exemple, USD ou EUR). Consultez les codes de devise compatibles.
customer_client.time_zone Obligatoire Immuable après la création : ID du fuseau horaire du compte (par exemple, America/New_York). Consultez les fuseaux horaires compatibles.
email_address et access_role Facultatif (liste d'autorisation uniquement) Invite un utilisateur (ADMIN, STANDARD, READ_ONLY ou EMAIL_ONLY) dans le compte créé lors de la création. Les comptes qui ne figurent pas sur la liste d'autorisation doivent inviter des utilisateurs après la création à l'aide de CustomerUserAccessInvitationService.
validate_only Facultatif Lorsque la valeur est true, valide les paramètres de la requête et l'éligibilité de l'administrateur sans créer le compte.

Exemple de code

L'exemple suivant montre comment créer un compte client sous un compte administrateur existant :

Java

private void runExample(GoogleAdsClient googleAdsClient, Long managerId) {
  // Formats the current date/time to use as a timestamp in the new customer description.
  String dateTime = ZonedDateTime.now().format(DateTimeFormatter.RFC_1123_DATE_TIME);

  // Initializes a Customer object to be created.
  Customer customer =
      Customer.newBuilder()
          .setDescriptiveName("Account created with CustomerService on '" + dateTime + "'")
          .setCurrencyCode("USD")
          .setTimeZone("America/New_York")
          // Optional: Sets additional attributes of the customer.
          .setTrackingUrlTemplate("{lpurl}?device={device}")
          .setFinalUrlSuffix("keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}")
          .build();

  // Sends the request to create the customer.
  try (CustomerServiceClient client =
      googleAdsClient.getLatestVersion().createCustomerServiceClient()) {
    CreateCustomerClientResponse response =
        client.createCustomerClient(managerId.toString(), customer);
    System.out.printf(
        "Created a customer with resource name '%s' under the manager account with"
            + " customer ID '%d'.%n",
        response.getResourceName(), managerId);
  }
}

C#

public void Run(GoogleAdsClient client, long managerCustomerId)
{
    // Get the CustomerService.
    CustomerServiceClient customerService = client.GetService(Services.V26.CustomerService);

    Customer customer = new Customer()
    {
        DescriptiveName = $"Account created with CustomerService on '{DateTime.Now}'",

        // For a list of valid currency codes and time zones see this documentation:
        // https://developers.google.com/google-ads/api/reference/data/codes-formats#codes_formats.
        CurrencyCode = "USD",
        TimeZone = "America/New_York",

        // The below values are optional. For more information about URL
        // options see: https://support.google.com/google-ads/answer/6305348.
        TrackingUrlTemplate = "{lpurl}?device={device}",
        FinalUrlSuffix = "keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}"
    };

    try
    {
        // Create the account.
        CreateCustomerClientResponse response = customerService.CreateCustomerClient(
            managerCustomerId.ToString(), customer);

        // Display the result.
        Console.WriteLine($"Created a customer with resource name " +
            $"'{response.ResourceName}' under the manager account with customer " +
            $"ID '{managerCustomerId}'");
    }
    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, int $managerCustomerId)
{
    $customer = new Customer([
        'descriptive_name' => 'Account created with CustomerService on ' . date('Ymd h:i:s'),
        // For a list of valid currency codes and time zones see this documentation:
        // https://developers.google.com/google-ads/api/reference/data/codes-formats.
        'currency_code' => 'USD',
        'time_zone' => 'America/New_York',
        // The below values are optional. For more information about URL
        // options see: https://support.google.com/google-ads/answer/6305348.
        'tracking_url_template' => '{lpurl}?device={device}',
        'final_url_suffix' => 'keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}'
    ]);

    // Issues a mutate request to create an account
    $customerServiceClient = $googleAdsClient->getCustomerServiceClient();
    $response = $customerServiceClient->createCustomerClient(
        CreateCustomerClientRequest::build($managerCustomerId, $customer)
    );

    printf(
        'Created a customer with resource name "%s" under the manager account with '
        . 'customer ID %d.%s',
        $response->getResourceName(),
        $managerCustomerId,
        PHP_EOL
    );
}

Python

def main(client: GoogleAdsClient, manager_customer_id: str) -> None:
    """The main method that creates all necessary entities for the example.

    Args:
        client: an initialized GoogleAdsClient instance.
        manager_customer_id: a manager client customer ID.
    """
    customer_service: CustomerServiceClient = client.get_service(
        "CustomerService"
    )
    customer: Customer = client.get_type("Customer")
    now: str = datetime.today().strftime("%Y%m%d %H:%M:%S")
    customer.descriptive_name = f"Account created with CustomerService on {now}"
    # For a list of valid currency codes and time zones see this documentation:
    # https://developers.google.com/google-ads/api/reference/data/codes-formats
    customer.currency_code = "USD"
    customer.time_zone = "America/New_York"
    # The below values are optional. For more information about URL
    # options see: https://support.google.com/google-ads/answer/6305348
    customer.tracking_url_template = "{lpurl}?device={device}"
    customer.final_url_suffix = (
        "keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}"
    )

    response: CreateCustomerClientResponse = (
        customer_service.create_customer_client(
            customer_id=manager_customer_id, customer_client=customer
        )
    )
    print(
        f'Customer created with resource name "{response.resource_name}" '
        f'under manager account with ID "{manager_customer_id}".'
    )

Ruby

def create_customer(manager_customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  customer = client.resource.customer do |c|
    c.descriptive_name = "Account created with CustomerService on #{(Time.new.to_f * 1000).to_i}"

    # For a list of valid currency codes and time zones, see this documentation:
    # https://developers.google.com/google-ads/api/reference/data/codes-formats
    c.currency_code = "USD"
    c.time_zone = "America/New_York"

    # The below values are optional. For more information about URL options, see:
    # https://support.google.com/google-ads/answer/6305348
    c.tracking_url_template = "{lpurl}?device={device}"
    c.final_url_suffix = "keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}"
  end

  response = client.service.customer.create_customer_client(
    customer_id: manager_customer_id,
    customer_client: customer
  )

  puts "Created a customer with resource name #{response.resource_name} under" +
      " the manager account with customer ID #{manager_customer_id}."
end

Perl

sub create_customer {
  my ($api_client, $manager_customer_id) = @_;

  # Initialize a customer to be created.
  my $customer = Google::Ads::GoogleAds::V26::Resources::Customer->new({
      descriptiveName => "Account created with CustomerService on #" . uniqid(),

      # For a list of valid currency codes and time zones, see this documentation:
      # https://developers.google.com/google-ads/api/reference/data/codes-formats
      currencyCode => "USD",
      timeZone     => "America/New_York",

      # The below values are optional. For more information about URL options, see:
      # https://support.google.com/google-ads/answer/6305348
      trackingUrlTemplate => "{lpurl}?device={device}",
      finalUrlSuffix      =>
        "keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}"
  });

  # Create the customer client.
  my $create_customer_client_response =
    $api_client->CustomerService()->create_customer_client({
      customerId     => $manager_customer_id,
      customerClient => $customer
    });

  printf
    "Created a customer with resource name '%s' under the manager account " .
    "with customer ID %d.\n", $create_customer_client_response->{resourceName},
    $manager_customer_id;

  return 1;
}

curl

# Creates a customer client.
#
# Variables:
#   API_VERSION,
#   MANAGER_CUSTOMER_ID,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.
#
curl -f --request POST \
"https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data @- <<EOF
{
  "customerClient": {
    "descriptiveName": "Account created with CustomerService #${RANDOM}",
    "currencyCode": "USD",
    "timeZone": "America/New_York"
  }
}
EOF

Réponse et étapes suivantes

En cas de réussite, CreateCustomerClient renvoie une CreateCustomerClientResponse contenant le resource_name (customers/{new_customer_id}) du compte nouvellement créé (ainsi qu'un invitation_link si email_address et access_role ont été inclus par un compte administrateur figurant sur la liste d'autorisation). Vous pouvez ensuite utiliser ce nom de ressource ou ce numéro client pour vérifier le compte dans votre hiérarchie, accorder un accès utilisateur, configurer la facturation ou remplir des campagnes.

Vérifier le compte créé dans la hiérarchie de l'administrateur

Interrogez la ressource customer_client par rapport au compte administrateur (customer_id) à l'aide de GoogleAdsService.SearchStream pour inspecter le sous-compte nouvellement créé :

SELECT
  customer_client.id,
  customer_client.resource_name,
  customer_client.client_customer,
  customer_client.descriptive_name,
  customer_client.currency_code,
  customer_client.time_zone,
  customer_client.manager,
  customer_client.level,
  customer_client.status
FROM customer_client
WHERE customer_client.level = 1
  AND customer_client.id = {new_customer_id}

Inviter des utilisateurs dans le nouveau compte

Si votre compte administrateur ne figure pas sur la liste d'autorisation pour définir email_address et access_role directement sur CreateCustomerClientRequest, envoyez une invitation d'accès au new_customer_id nouvellement créé à l'aide MutateCustomerUserAccessInvitation sur CustomerUserAccessInvitationService. Lors de l'authentification via le compte administrateur parent, incluez login-customer-id: {manager_customer_id} dans les en-têtes de requête HTTP :

POST https://googleads.googleapis.com/v26/customers/{new_customer_id}/customerUserAccessInvitations:mutate
{
  "operation": {
    "create": {
      "emailAddress": "user@example.com",
      "accessRole": "ADMIN"
    }
  }
}

Gestion des exceptions

Les appels à CreateCustomerClient peuvent renvoyer les erreurs suivantes :

  • CustomerError: indique des restrictions de création au niveau du compte, telles que CREATION_DENIED_INELIGIBLE_MCC (le compte administrateur n'est pas éligible pour créer des comptes) ou CREATION_DENIED_FOR_POLICY_VIOLATION (la création de clients est refusée en raison d'un cas de non-respect des règles).
  • ManagerLinkError : indique des contraintes de hiérarchie ou de limite de compte, telles que TOO_MANY_ACCOUNTS, TOO_MANY_ACCOUNTS_AT_MANAGER ou MAX_DEPTH_EXCEEDED.
  • AccessInvitationError : renvoyée si une email_address facultative (ainsi que access_role, disponible uniquement pour les comptes figurant sur la liste d'autorisation) est fournie sur CreateCustomerClientRequest pour inviter un utilisateur dans le nouveau compte et que l'invitation échoue (par exemple, INVALID_EMAIL_ADDRESS, GOOGLE_CONSUMER_ACCOUNT_NOT_ALLOWED ou EMAIL_DOMAIN_POLICY_VIOLATED). Les comptes qui ne figurent pas sur la liste d'autorisation doivent inviter des utilisateurs après la création du compte à l'aide de CustomerUserAccessInvitationService.
  • CurrencyCodeError.UNSUPPORTED ou TimeZoneError.INVALID_TIME_ZONE : renvoyée lorsque le currency_code ou le time_zone spécifié sur l'objet Customer n'est pas valide ou n'est pas compatible.
Précédent
Aperçu
Suivant
Associer des comptes à des comptes administrateur