Buat akun

Untuk membuat akun klien baru, kirimkan objek Customer yang telah diisi otomatis menggunakan metode CreateCustomerClient di CustomerService.

Tidak seperti pembuatan entitas standar (seperti membuat kampanye menggunakan panggilan mutate), Anda harus menentukan ID pelanggan akun pengelola dalam permintaan, bukan ID pelanggan yang sedang dibuat.

Kolom permintaan dan pelanggan

Saat memanggil CustomerService.CreateCustomerClient, konfigurasikan CreateCustomerClientRequest dan objek Customer bertingkatnya seperti yang ditunjukkan dalam tabel berikut:

Kolom atau header Persyaratan Kemutabilitasan dan deskripsi
customer_id Wajib ID pelanggan 10 digit (tanpa tanda hubung) dari akun pengelola induk langsung tempat akun klien baru dibuat.
login-customer-id (header) Kondisional Wajib ada di header permintaan jika pengguna yang diautentikasi mengakses akun pengelola induk (customer_id) melalui akun pengelola induk yang lebih tinggi dalam hierarki.
customer_client.descriptive_name Wajib Dapat diubah: Nama tampilan untuk akun baru (misalnya, "Acct Created with CustomerService"). Dapat diperbarui nanti dengan CustomerService.MutateCustomer.
customer_client.currency_code Wajib Tidak dapat diubah setelah dibuat: Kode mata uang penagihan ISO 4217 3 karakter (misalnya, USD atau EUR). Lihat kode mata uang yang didukung.
customer_client.time_zone Wajib Tidak dapat diubah setelah dibuat: ID zona waktu akun (misalnya, America/New_York). Lihat zona waktu yang didukung.
email_address dan access_role Opsional (khusus daftar yang diizinkan) Mengundang pengguna (ADMIN, STANDARD, READ_ONLY, atau EMAIL_ONLY) ke akun yang dibuat selama pembuatan. Akun yang tidak ada dalam daftar yang diizinkan harus mengundang pengguna setelah pembuatan menggunakan CustomerUserAccessInvitationService.
validate_only Opsional Jika true, parameter permintaan dan kelayakan pengelola akan divalidasi tanpa membuat akun.

Contoh kode

Contoh berikut menunjukkan cara membuat akun pelanggan di akun pengelola yang ada:

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

Respons dan langkah berikutnya

Jika berhasil, CreateCustomerClient akan menampilkan CreateCustomerClientResponse yang berisi resource_name (customers/{new_customer_id}) dari akun yang baru dibuat (ditambah invitation_link jika email_address dan access_role disertakan oleh akun pengelola dalam daftar yang diizinkan). Kemudian, Anda dapat menggunakan nama resource atau ID pelanggan ini untuk memverifikasi akun di hierarki, memberikan akses pengguna, mengonfigurasi penagihan, atau mengisi kampanye.

Verifikasi akun yang dibuat dalam hierarki pengelola

Buat kueri resource customer_client terhadap akun pengelola (customer_id) menggunakan GoogleAdsService.SearchStream untuk memeriksa sub-akun yang baru dibuat:

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}

Mengundang pengguna ke akun baru

Jika akun pengelola Anda tidak ada dalam daftar yang diizinkan untuk menetapkan email_address dan access_role langsung di CreateCustomerClientRequest, kirim undangan akses ke new_customer_id yang baru dibuat menggunakan MutateCustomerUserAccessInvitation di CustomerUserAccessInvitationService. Saat melakukan autentikasi melalui akun pengelola induk, sertakan login-customer-id: {manager_customer_id} di header permintaan HTTP:

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

Penanganan error

Panggilan ke CreateCustomerClient dapat menampilkan error berikut:

  • CustomerError: Menunjukkan batasan pembuatan tingkat akun, seperti CREATION_DENIED_INELIGIBLE_MCC (akun pengelola tidak memenuhi syarat untuk membuat akun baru) atau CREATION_DENIED_FOR_POLICY_VIOLATION (pembuatan akun pelanggan ditolak karena pelanggaran kebijakan).
  • ManagerLinkError: Menunjukkan batasan hierarki atau batas akun, seperti TOO_MANY_ACCOUNTS, TOO_MANY_ACCOUNTS_AT_MANAGER, atau MAX_DEPTH_EXCEEDED.
  • AccessInvitationError: Ditampilkan jika email_address opsional (bersama dengan access_role, hanya tersedia untuk akun dalam daftar yang diizinkan) diberikan di CreateCustomerClientRequest untuk mengundang pengguna ke akun baru dan undangan gagal (misalnya, INVALID_EMAIL_ADDRESS, GOOGLE_CONSUMER_ACCOUNT_NOT_ALLOWED, atau EMAIL_DOMAIN_POLICY_VIOLATED). Akun yang tidak ada dalam daftar yang diizinkan harus mengundang pengguna setelah pembuatan akun menggunakan CustomerUserAccessInvitationService.
  • CurrencyCodeError.UNSUPPORTED atau TimeZoneError.INVALID_TIME_ZONE: Ditampilkan jika currency_code atau time_zone yang ditentukan pada objek Customer tidak valid atau tidak didukung.
Sebelumnya
Ringkasan
Berikutnya
Menautkan ke akun pengelola