إنشاء حساب

لإنشاء حساب عميل جديد، أرسِل عنصر Customer مملوءًا مسبقًا باستخدام طريقة CreateCustomerClient على CustomerService.

على عكس عملية إنشاء العناصر العادية (مثل إنشاء الحملات باستخدام mutate المكالمات)، يجب تحديد رقم تعريف العميل للحساب الإداري في الطلب بدلاً من رقم تعريف العميل الذي يتم إنشاؤه.

حقول العملاء المطلوبة

عند ملء عنصر Customer الجديد، يجب تحديد الخصائص التالية:

  • ‫descriptive_name: تصنيف للحساب الجديد
  • ‫currency_code: عملة الفوترة (على سبيل المثال، USD)
  • time_zone: المنطقة الزمنية للحساب (مثلاً، America/New_York)

مثال على الرمز

يوضّح المثال التالي كيفية إنشاء حساب عميل ضِمن حساب إداري حالي:

جافا

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.V25.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::V25::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 للحساب الذي تم إنشاؤه حديثًا. يمكنك بعد ذلك استخدام اسم المورد أو رقم تعريف العميل هذا لإعداد الفوترة أو منح المستخدم إذن الوصول أو ملء الحملات.

معالجة الأخطاء

يمكن أن تعرض طلبات البيانات إلى 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 غير صالح أو غير متوافق.
السابق
نظرة عامة
التالي
الربط بالحسابات الإدارية