สร้างบัญชี

หากต้องการสร้างบัญชีลูกค้าใหม่ ให้ส่งออบเจ็กต์ 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 ที่เป็นตัวอักษร 3 ตัว (เช่น 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 เมื่อตรวจสอบสิทธิ์ผ่านบัญชีดูแลจัดการระดับบนสุด ให้ใส่ login-customer-id: {manager_customer_id} ในส่วนหัวของคำขอ HTTP

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: แสดงผลหากมีการระบุ email_address ที่ไม่บังคับ (พร้อมกับ access_role ซึ่งใช้ได้เฉพาะกับบัญชีในรายการที่อนุญาต) ใน CreateCustomerClientRequest เพื่อเชิญผู้ใช้ไปยังบัญชีใหม่ และคำเชิญล้มเหลว (เช่น INVALID_EMAIL_ADDRESS, GOOGLE_CONSUMER_ACCOUNT_NOT_ALLOWED หรือ EMAIL_DOMAIN_POLICY_VIOLATED) บัญชีที่ไม่ได้อยู่ในรายการที่อนุญาตควรเชิญผู้ใช้หลังจากสร้างบัญชีโดยใช้ CustomerUserAccessInvitationService
  • CurrencyCodeError.UNSUPPORTED หรือ TimeZoneError.INVALID_TIME_ZONE: แสดงผลเมื่อ currency_code หรือ time_zone ที่ระบุในออบเจ็กต์ Customer ไม่ถูกต้องหรือไม่ รองรับ