יצירת חשבון

אזהרה: התכונה הזו זמינה רק למפרסמים שהוציאו יותר מ-1,000 דולר ארה"ב ושמנהלים את החשבון שלהם ב-Google Ads באופן תקין. כדי לפתור בעיות ביצירת חשבונות משנה בחשבון הניהול ב-Google Ads, אפשר לפנות לתמיכה או לקרוא את ההנחיות בנושא חשבונות ניהול.

כדי ליצור חשבון לקוח חדש, שולחים אובייקט Customer עם שדות מאוכלסים מראש באמצעות השיטה CreateCustomerClient ב-CustomerService.

בניגוד ליצירת ישות רגילה (כמו יצירת קמפיינים באמצעות קריאות ל-mutate), צריך לציין בבקשה את מספר הלקוח של חשבון הניהול ולא את המזהה של הלקוח שנוצר.

שדות של בקשה ולקוח

כשמפעילים את CustomerService.CreateCustomerClient, מגדירים את CreateCustomerClientRequest ואת האובייקט המקונן Customer שלו, כמו שמוצג בטבלה הבאה:

שדה או כותרת	דרישה	יכולת שינוי ותיאור
customer_id	חובה	מספר הלקוח בן 10 הספרות (ללא מקפים) של חשבון הניהול הראשי הישיר שבו נוצר חשבון הלקוח החדש.
login-customer-id (כותרת)	משפטי תנאי	חובה ב-request headers אם המשתמש המאומת ניגש לחשבון הניהול הראשי (customer_id) דרך חשבון ניהול קודם שנמצא גבוה יותר בהיררכיה.
customer_client.descriptive_name	חובה	‫Mutable: השם המוצג של החשבון החדש (לדוגמה, "Acct Created with CustomerService"). אפשר לעדכן אותו בהמשך באמצעות CustomerService.MutateCustomer.
customer_client.currency_code	חובה	אי אפשר לשנות אחרי היצירה: קוד מטבע לחיוב בן 3 תווים לפי תקן 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.

קוד לדוגמה

בדוגמה הבאה אפשר לראות איך יוצרים חשבון לקוח במסגרת חשבון ניהול קיים:

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);
  }
}
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
      

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;
}
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 לא תקין או לא נתמך.