Để tạo tài khoản khách hàng mới, hãy gửi đối tượng Customer được điền sẵn bằng phương thức CreateCustomerClient trên CustomerService.
Không giống như việc tạo thực thể tiêu chuẩn (chẳng hạn như tạo chiến dịch bằng cách sử dụng các lệnh gọi mutate), bạn phải chỉ định mã khách hàng của tài khoản người quản lý trong yêu cầu thay vì mã của khách hàng đang được tạo.
Trường yêu cầu và trường khách hàng
Khi gọi CustomerService.CreateCustomerClient, hãy định cấu hình CreateCustomerClientRequest và đối tượng Customer lồng nhau như trong bảng sau:
| Trường hoặc tiêu đề | Yêu cầu | Khả năng thay đổi và nội dung mô tả |
|---|---|---|
customer_id |
Bắt buộc | Mã khách hàng gồm 10 chữ số (không có dấu gạch nối) của tài khoản người quản lý mẹ trực tiếp mà tài khoản khách hàng mới được tạo trong đó. |
login-customer-id (tiêu đề) |
Câu lệnh có điều kiện | Bắt buộc trong tiêu đề của yêu cầu nếu người dùng đã xác thực truy cập vào tài khoản người quản lý mẹ (customer_id) thông qua một tài khoản người quản lý cấp cao hơn trong hệ phân cấp. |
customer_client.descriptive_name |
Bắt buộc | Có thể thay đổi: Tên hiển thị cho tài khoản mới (ví dụ: "Acct Created with CustomerService"). Bạn có thể cập nhật tên này sau bằng CustomerService.MutateCustomer. |
customer_client.currency_code |
Bắt buộc | Không thể thay đổi sau khi tạo: Mã đơn vị tiền tệ thanh toán gồm 3 ký tự theo tiêu chuẩn ISO 4217 (ví dụ: USD hoặc EUR). Xem mã đơn vị tiền tệ được hỗ trợ. |
customer_client.time_zone |
Bắt buộc | Không thể thay đổi sau khi tạo: Mã múi giờ của tài khoản (ví dụ: America/New_York). Xem các múi giờ được hỗ trợ. |
email_address và access_role |
Không bắt buộc (chỉ dành cho danh sách cho phép) | Mời người dùng (ADMIN, STANDARD, READ_ONLY hoặc EMAIL_ONLY) vào tài khoản đã tạo trong quá trình tạo. Những tài khoản không có trong danh sách cho phép phải mời người dùng sau khi tạo bằng cách sử dụng CustomerUserAccessInvitationService. |
validate_only |
Không bắt buộc | Khi true, xác thực các tham số yêu cầu và điều kiện của người quản lý mà không cần tạo tài khoản. |
Ví dụ về mã
Ví dụ sau đây minh hoạ cách tạo tài khoản khách hàng trong một tài khoản người quản lý hiện có:
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
Phản hồi và các bước tiếp theo
Nếu thành công, CreateCustomerClient sẽ trả về một CreateCustomerClientResponse chứa resource_name (customers/{new_customer_id}) của tài khoản mới tạo (cộng với invitation_link nếu email_address và access_role được tài khoản người quản lý đưa vào danh sách cho phép). Sau đó, bạn có thể sử dụng tên tài nguyên hoặc mã khách hàng này để xác minh tài khoản trong hệ thống phân cấp, cấp quyền truy cập cho người dùng, thiết lập thông tin thanh toán hoặc điền thông tin cho chiến dịch.
Xác minh tài khoản đã tạo trong hệ thống phân cấp người quản lý
Truy vấn tài nguyên customer_client đối với tài khoản người quản lý (customer_id) bằng GoogleAdsService.SearchStream để kiểm tra tài khoản phụ mới tạo:
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}
Mời người dùng vào tài khoản mới
Nếu tài khoản người quản lý của bạn không có trong danh sách cho phép để đặt email_address và access_role trực tiếp trên CreateCustomerClientRequest, hãy gửi lời mời truy cập đến new_customer_id mới tạo bằng MutateCustomerUserAccessInvitation trên CustomerUserAccessInvitationService. Khi xác thực thông qua tài khoản người quản lý cấp cao, hãy thêm login-customer-id: {manager_customer_id} vào tiêu đề của yêu cầu HTTP:
POST https://googleads.googleapis.com/v26/customers/{new_customer_id}/customerUserAccessInvitations:mutate
{
"operation": {
"create": {
"emailAddress": "user@example.com",
"accessRole": "ADMIN"
}
}
}
Xử lý lỗi
Các lệnh gọi đến CreateCustomerClient có thể trả về các lỗi sau:
CustomerError: Cho biết các hạn chế khi tạo tài khoản, chẳng hạn nhưCREATION_DENIED_INELIGIBLE_MCC(tài khoản người quản lý không đủ điều kiện tạo tài khoản mới) hoặcCREATION_DENIED_FOR_POLICY_VIOLATION(không được tạo khách hàng do vi phạm chính sách).ManagerLinkError: Cho biết các quy tắc ràng buộc về hệ thống phân cấp hoặc hạn mức trong tài khoản, chẳng hạn nhưTOO_MANY_ACCOUNTS,TOO_MANY_ACCOUNTS_AT_MANAGERhoặcMAX_DEPTH_EXCEEDED.AccessInvitationError: Được trả về nếuemail_addresskhông bắt buộc (cùng vớiaccess_role, chỉ dành cho các tài khoản trong danh sách cho phép) được cung cấp trênCreateCustomerClientRequestđể mời người dùng tham gia tài khoản mới và lời mời không thành công (ví dụ:INVALID_EMAIL_ADDRESS,GOOGLE_CONSUMER_ACCOUNT_NOT_ALLOWEDhoặcEMAIL_DOMAIN_POLICY_VIOLATED). Những tài khoản không có trong danh sách cho phép nên mời người dùng sau khi tạo tài khoản bằngCustomerUserAccessInvitationService.CurrencyCodeError.UNSUPPORTEDhoặcTimeZoneError.INVALID_TIME_ZONE: Trả về khicurrency_codehoặctime_zoneđược chỉ định trên đối tượngCustomerkhông hợp lệ hoặc không được hỗ trợ.