Чтобы создать новый клиентский аккаунт, отправьте автоматически заполненный объект Customer, используя метод CreateCustomerClient на CustomerService.
В отличие от стандартного создания объектов (например, кампаний с помощью вызовов mutate), в запросе необходимо указать идентификатор клиента управляющего аккаунта, а не идентификатор создаваемого клиента.
Поля запроса и клиента
При вызове CustomerService.CreateCustomerClient настройте CreateCustomerClientRequest и вложенный объект Customer, как показано в таблице ниже.
| Поле или заголовок | Требования | Изменяемость и описание |
|---|---|---|
customer_id |
Обязательно | 10-значный идентификатор клиента (без дефисов) непосредственного родительского управляющего аккаунта, в котором создается новый клиентский аккаунт. |
login-customer-id (заголовок) |
Условное наклонение | Требуется в заголовках запроса, если аутентифицированный пользователь получает доступ к родительскому управляющему аккаунту (customer_id) через управляющий аккаунт более высокого уровня в иерархии. |
customer_client.descriptive_name |
Обязательно | Изменяемое. Отображаемое название нового аккаунта (например, "Acct Created with CustomerService"). Его можно изменить позже с помощью CustomerService.MutateCustomer. |
customer_client.currency_code |
Обязательно | Нельзя изменить после создания: трехбуквенный код валюты платежей по стандарту ISO 4217 (например, USD или EUR). См. поддерживаемые коды валют. |
customer_client.time_zone |
Обязательно | Нельзя изменить после создания: идентификатор часового пояса аккаунта (например, America/New_York). Подробнее о поддерживаемых часовых поясах… |
email_address и access_role |
Необязательно (только для белого списка) | Приглашает пользователя (ADMIN, STANDARD, READ_ONLY или EMAIL_ONLY) в созданный аккаунт во время его создания. Если аккаунт не входит в белый список, то после создания пользователя нужно пригласить его с помощью CustomerUserAccessInvitationService. |
validate_only |
Необязательно | Если задано значение true, проверяются параметры запроса и соответствие менеджера требованиям без создания аккаунта. |
Пример кода
В примере ниже показано, как создать аккаунт клиента в существующем управляющем аккаунте.
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
Ответ и дальнейшие действия
В случае успеха CreateCustomerClient возвращает CreateCustomerClientResponse, содержащий resource_name (customers/{new_customer_id}) нового аккаунта (и invitation_link, если управляющий аккаунт из белого списка включил email_address и access_role). Затем вы можете использовать это название ресурса или идентификатор клиента, чтобы проверить аккаунт в иерархии, предоставить пользователю доступ, настроить оплату или заполнить кампании.
Проверьте созданный аккаунт в иерархии управляющего аккаунта
Запросите ресурс customer_client у управляющего аккаунта (customer_id), используя GoogleAdsService.SearchStream, чтобы проверить созданный подчиненный аккаунт:
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}
Пригласите пользователей в новый аккаунт
Если ваш управляющий аккаунт не включен в белый список для настройки email_address и access_role непосредственно в CreateCustomerClientRequest, отправьте приглашение на доступ к новому аккаунту new_customer_id, используя MutateCustomerUserAccessInvitation в CustomerUserAccessInvitationService. При аутентификации через родительский управляющий аккаунт включите в заголовки HTTP-запросов login-customer-id: {manager_customer_id}:
POST https://googleads.googleapis.com/v26/customers/{new_customer_id}/customerUserAccessInvitations:mutate
{
"operation": {
"create": {
"emailAddress": "user@example.com",
"accessRole": "ADMIN"
}
}
}
Обработка ошибок
При вызове функции CreateCustomerClient могут возникать следующие ошибки:
CustomerError– указывает на ограничения создания на уровне аккаунта, напримерCREATION_DENIED_INELIGIBLE_MCC(управляющий аккаунт не может создавать новые аккаунты) илиCREATION_DENIED_FOR_POLICY_VIOLATION(создание клиента запрещено из-за нарушения правил).ManagerLinkError– ограничения иерархии или аккаунта, напримерTOO_MANY_ACCOUNTS,TOO_MANY_ACCOUNTS_AT_MANAGERилиMAX_DEPTH_EXCEEDED.AccessInvitationError– возвращается, если вCreateCustomerClientRequestуказан необязательный параметрemail_address(вместе сaccess_role, доступным только аккаунтам из белого списка), чтобы пригласить пользователя в новый аккаунт, но приглашение не отправляется (например,INVALID_EMAIL_ADDRESS,GOOGLE_CONSUMER_ACCOUNT_NOT_ALLOWEDилиEMAIL_DOMAIN_POLICY_VIOLATED). Аккаунты, не включенные в белый список, должны приглашать пользователей после создания аккаунта с помощьюCustomerUserAccessInvitationService.CurrencyCodeError.UNSUPPORTEDилиTimeZoneError.INVALID_TIME_ZONE. Возвращается, если указанное значениеcurrency_codeилиtime_zoneв объектеCustomerнедействительно или не поддерживается.