ایجاد حساب

هشدار: این ویژگی فقط برای تبلیغ‌کنندگانی دردسترس است که بیش‌از ۱۰۰۰ دلار امریکا هزینه کرده‌اند و ازنظر خط‌مشی‌های Google Ads خوش‌حساب هستند. برای عیب‌یابی کردن مشکلات ایجاد حساب فرعی در حساب «مدیر Google Ads»، با پشتیبانی تماس بگیرید یا رهنمودهای حساب مدیر را بخوانید.

برای ایجاد حساب مشتری جدید، شیء Customer ازپیش تکمیل‌شده‌ای را بااستفاده از روش CreateCustomerClient در CustomerService ارسال کنید.

برخلاف ایجاد نهاد استاندارد (مانند ایجاد کمپین بااستفاده از تماس‌های mutate)، باید شناسه مشتری حساب مدیر را در درخواست مشخص کنید، نه شناسه مشتری‌ای که درحال ایجاد است.

فیلدهای درخواست و مشتری

هنگام فراخوانی CustomerService.CreateCustomerClient، CreateCustomerClientRequest و شیء تودرتوی Customer آن را همان‌طور که در جدول زیر نشان داده شده است پیکربندی کنید:

فیلد یا سرصفحه	الزام	تغییرپذیری و شرح
customer_id	الزامی	شناسه مشتری ۱۰ رقمی (بدون خط تیره) حساب مدیر اصلی مستقیم که حساب مشتری جدید تحت آن ایجاد شده است.
‫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، پارامترهای درخواست و واجدشرایط بودن مدیر را بدون ایجاد حساب اعتبارسنجی می‌کند.

توجه: تنظیمات Customer اضافی مانند tracking_url_template، final_url_suffix، auto_tagging_enabled، و call_reporting_setting را می‌توان در شناسه مشتری جدیداً ایجادشده بااستفاده از CustomerService.MutateCustomer با FieldMask پیکربندی یا به‌روز کرد.

نمونه کد

مثال زیر نشان می‌دهد که چگونه یک حساب مشتری تحت یک حساب مدیر موجود ایجاد کنید:

جاوا

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);
  }
}
CreateCustomer.java
      

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;
    }
}
CreateCustomer.cs
      

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
    );
}
CreateCustomer.php
      

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}".'
    )
create_customer.py
      

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
create_customer.rb
      

پرل

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;
}
create_customer.pl
      

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
create_customer.sh
      

پاسخ و مراحل بعدی

درصورت موفقیت، 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": "[e-mail]",
      "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 نامعتبر یا پشتیبانی‌نشده باشد.