הסבר על מודל הגישה ב-Google Ads

יש שני סוגים של חשבונות Google Ads: חשבונות ניהול ב-Google Ads וחשבונות מפרסמים ב-Google Ads. הסבר מפורט על הקשר בין המונחים האלה למונחים אחרים (כמו חשבון לקוח ולקוח) מופיע במאמר סוגי חשבונות.

חשבונות ניהול יכולים לנהל חשבונות ניהול אחרים ב-Google Ads או חשבונות של מפרסמים ב-Google Ads. אתם יכולים לקשר חשבון מפרסם לחשבון ניהול ואז לנהל את חשבון המפרסם דרך חשבון הניהול. המבנה המקושר הכולל הוא גרף אציקלי מכוון עם חשבונות מפרסמים ברמת העלה.

אתם יכולים לתת למשתמשים פרטיים או לחשבונות שירות גישה לחשבונות Google Ads. יש שתי דרכים לתת למשתמשים גישה לחשבון מפרסם:

• מעניקים למשתמש גישה ישירה לחשבון המפרסם על ידי שליחת הזמנה לחשבון הזה.
• להעניק למשתמש גישה עקיפה לחשבון המפרסם על ידי הזמנה שלו לחשבון ניהול שמקושר לחשבון הזה. המשתמש מקבל גישה לחשבון המפרסם כי לחשבון הניהול יש גישה לכל החשבונות שמקושרים אליו.

אתם יכולים גם להקצות תפקידי משתמש כשאתם מזמינים משתמש לנהל חשבון.

נבחן את היררכיית החשבונות הבאה. נניח שלכל המשתמשים יש הרשאת גישה רגילה.

בטבלה הבאה מופיע סיכום של מבנה החשבון הזה.

משתמש	בעל גישה ישירה אל	יש גישה עקיפה אל
U1, SA1	M1	M2, ‏ A1, ‏ A2, ‏ A3
U2	M2, ‏ M3	A1, A2, A3, A4
U3	A4

מספר הלקוח של חשבון ההתחברות

למשתמש יכולה להיות גישה לכמה היררכיות של חשבונות. כשמבצעים קריאה ל-API במקרים כאלה, צריך לציין את חשבון הבסיס שבו רוצים להשתמש כדי לקבוע בצורה נכונה את רמות ההרשאה והגישה לחשבון. כדי לעשות את זה, צריך לכלול את הכותרת login-customer-id בבקשת ה-API.

בטבלה הבאה נעשה שימוש בהיררכיית החשבונות מהדוגמה הקודמת כדי להראות באילו מספרי לקוח להתחברות אפשר להשתמש, ואת רשימת החשבונות המתאימה שאפשר לבצע אליהם קריאות.

משתמש	מספר הלקוח שצריך להתחבר אליו כדי להשתמש בתכונה	חשבונות שאפשר לשלוח אליהם קריאות ל-API
U1, SA1	M1	M1, ‏ M2, ‏ A1, ‏ A2, ‏ A3
U2	M2	M2, ‏ A1, ‏ A2, ‏ A3
U2	M3	M3, ‏ A1, ‏ A4
U3	A4	A4

אפשר לדלג על הכותרת login-customer-id אם למשתמש יש גישה ישירה לחשבון Google Ads שאליו אתם מבצעים קריאות. לדוגמה, לא צריך לציין את הכותרת login-customer-id כשמשתמשים בפרטי הכניסה של U3 כדי לבצע קריאה ל-A4, כי השרתים של Google Ads יכולים לקבוע בצורה נכונה את רמת הגישה לפי מספר הלקוח (A4).

אם אתם משתמשים בספריית לקוח של Google Ads API, השתמשו בהגדרות הבאות כדי לציין את הכותרת login-customer-id.

Java

מוסיפים את ההגדרה הבאה לקובץ ads.properties.

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

‎.NET

מוסיפים את ההגדרה הבאה כשמפעילים את האובייקט GoogleAdsConfig ומשתמשים בה כדי ליצור אובייקט GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    // ...
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);

Python

מוסיפים את ההגדרה הבאה לקובץ google-ads.yaml.

login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

PHP

מוסיפים את ההגדרה הבאה לקובץ google_ads_php.ini.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

Ruby

מוסיפים את ההגדרה הבאה לקובץ google_ads_config.rb.

Google::Ads::GoogleAds::Config.new do |c|
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

יוצרים מופע של GoogleAdsClient על ידי העברת הנתיב למיקום שבו שמרתם את הקובץ הזה.

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

Perl

מוסיפים את ההגדרה הבאה לקובץ googleads.properties.

loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

curl

מציינים את הארגומנט הבא של שורת הפקודה כשמריצים את הפקודה curl.

-H "login-customer-id: INSERT_LOGIN_CUSTOMER_ID_HERE"

אתם יכולים להשתמש ב-method‏ CustomerService.ListAccessibleCustomers כדי לאחזר את רשימת החשבונות שלמשתמש יש גישה ישירה אליהם. אפשר להשתמש בחשבונות האלה כערכים תקינים לכותרת login-customer-id.

Java

private void runExample(GoogleAdsClient client) {
  // Optional: Change credentials to use a different refresh token, to retrieve customers
  //           available for a specific user.
  //
  // UserCredentials credentials =
  //     UserCredentials.newBuilder()
  //         .setClientId("INSERT_OAUTH_CLIENT_ID")
  //         .setClientSecret("INSERT_OAUTH_CLIENT_SECRET")
  //         .setRefreshToken("INSERT_REFRESH_TOKEN")
  //         .build();
  //
  // client = client.toBuilder().setCredentials(credentials).build();

  try (CustomerServiceClient customerService =
      client.getLatestVersion().createCustomerServiceClient()) {
    ListAccessibleCustomersResponse response =
        customerService.listAccessibleCustomers(
            ListAccessibleCustomersRequest.newBuilder().build());

    System.out.printf("Total results: %d%n", response.getResourceNamesCount());

    for (String customerResourceName : response.getResourceNamesList()) {
      System.out.printf("Customer resource name: %s%n", customerResourceName);
    }
  }
}
ListAccessibleCustomers.java
      

C#‎

public void Run(GoogleAdsClient client)
{
    // Get the CustomerService.
    CustomerServiceClient customerService = client.GetService(Services.V26.CustomerService);

    try
    {
        // Retrieve the list of customer resources.
        string[] customerResourceNames = customerService.ListAccessibleCustomers();

        // Display the result.
        foreach (string customerResourceName in customerResourceNames)
        {
            Console.WriteLine(
                $"Found customer with resource name = '{customerResourceName}'.");
        }
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
ListAccessibleCustomers.cs
      

PHP

public static function runExample(GoogleAdsClient $googleAdsClient)
{
    $customerServiceClient = $googleAdsClient->getCustomerServiceClient();

    // Issues a request for listing all accessible customers.
    $accessibleCustomers =
        $customerServiceClient->listAccessibleCustomers(new ListAccessibleCustomersRequest());
    print 'Total results: ' . count($accessibleCustomers->getResourceNames()) . PHP_EOL;

    // Iterates over all accessible customers' resource names and prints them.
    foreach ($accessibleCustomers->getResourceNames() as $resourceName) {
        /** @var string $resourceName */
        printf("Customer resource name: '%s'%s", $resourceName, PHP_EOL);
    }
}
ListAccessibleCustomers.php
      

Python

def main(client: GoogleAdsClient) -> None:
    customer_service: CustomerServiceClient = client.get_service(
        "CustomerService"
    )

    accessible_customers: ListAccessibleCustomersResponse = (
        customer_service.list_accessible_customers()
    )
    result_total: int = len(accessible_customers.resource_names)
    print(f"Total results: {result_total}")

    resource_names: List[str] = accessible_customers.resource_names
    for resource_name in resource_names:  # resource_name is implicitly str
        print(f'Customer resource name: "{resource_name}"')
list_accessible_customers.py
      

Ruby

def list_accessible_customers()
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  accessible_customers = client.service.customer.list_accessible_customers().resource_names

  accessible_customers.each do |resource_name|
    puts "Customer resource name: #{resource_name}"
  end
end
list_accessible_customers.rb
      

Perl

sub list_accessible_customers {
  my ($api_client) = @_;

  my $list_accessible_customers_response =
    $api_client->CustomerService()->list_accessible_customers();

  printf "Total results: %d.\n",
    scalar @{$list_accessible_customers_response->{resourceNames}};

  foreach
    my $resource_name (@{$list_accessible_customers_response->{resourceNames}})
  {
    printf "Customer resource name: '%s'.\n", $resource_name;
  }

  return 1;
}
list_accessible_customers.pl
      

curl

# Returns the resource names of customers directly accessible by the user
# authenticating the call.
#
# Variables:
#   API_VERSION,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.
#
curl -f --request GET \
"https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
list_accessible_customers.sh
      

מה קורה אם השיטה ListAccessibleCustomers לא מאחזרת את מספר הלקוח שלי?

אם השיטה CustomerService.ListAccessibleCustomers לא אחזרה מספר לקוח שציפיתם שיופיע בתוצאות, יכולות להיות לכך כמה הסברים.

1. יש לכם גישה למספר הלקוח, אבל הגישה ניתנה דרך חשבון ניהול ראשי. לדוגמה, אם קוראים ל-method‏ ListAccessibleCustomers עם פרטי הכניסה של המשתמש U1 בדוגמה הקודמת, ה-method מחזירה רק את M1 בתוצאות, למרות של-U1 יש גישה לחשבונות נוספים. כדי לוודא שזה המצב, אחזרו את היררכיית החשבונות על ידי הפעלת שאילתות search או searchStream במשאב customer_client לכל אחד מהחשבונות שהוחזרו על ידי ה-method‏ ListAccessibleCustomers. כדי לעשות את זה, מגדירים כל אחד מהחשבונות האלה בתור login-customer-id, כמו שמתואר בחלק הקודם. אם יש לכם גישה לחשבון היעד, אתם יכולים לאחזר אותו כחלק מאחת מההיררכיות של החשבונות.

2. פרטי הכניסה של OAuth שגויים. התרחיש הנפוץ ביותר הוא שאתם משתמשים בפרטי כניסה של משתמש אחר. לדוגמה, יכול להיות שזה קרה בגלל ערבוב בטעות של פרטי כניסה של ארגז חול או של מפתח עם פרטי כניסה של סביבת ייצור, או קריאה שגויה של פרטי כניסה של משתמש אחר ממסד הנתונים או מהמטמון המקומי. אחת מהדרכים האפשריות לפתור את הבעיה היא להשתמש ב-Google People API כדי לאחזר את השם וכתובת האימייל של המשתמש שמחובר, ולבדוק אם הם תואמים לכתובת האימייל שציפיתם לקבל.

3. אין לכם גישה לחשבון. כדי לקבל גישה לחשבון הלקוח הנכון, פועלים לפי המדריך בנושא גישה לחשבון.

תפקידי משתמשים

ל-Google Ads API אין מודל גישה נפרד משלו, והוא לא משתמש בהיקפי הרשאות נפרדים של OAuth 2.0 כדי להגביל את הפונקציונליות. לדוגמה, ב-Google Ads API נעשה שימוש באותם היקפי הרשאות לפעולות לקריאה בלבד ולפעולות לקריאה ולכתיבה. במקום זאת, ב-Google Ads API משתמשים באותם תפקידי משתמשים שנתמכים ב-Google Ads. כשמקצים תפקיד משתמש לחשבון ברמת הניהול, התפקיד עובר בירושה לחשבונות בהיררכיה. אם למשתמש יש תפקידים סותרים בחשבון מסוים, רמת הגישה הנכונה נקבעת לפי החשבון ב-login-customer-id שצוין בבקשת ה-API.

בטבלה הבאה מוצגת היררכיית החשבונות מהדוגמה הקודמת, וההשפעה של הקצאת תפקידי משתמשים שונים למשתמשים.

משתמש	תפקיד המשתמש הוענק	login-customer-id	רמת הגישה בפועל
SA1	הרשאת גישה רגילה בחשבון M1	M1	הרשאת גישה רגילה ב-M1, ‏ M2, ‏ A1, ‏ A2, ‏ A3
U2	הרשאת גישה רגילה ב-M2 הרשאת קריאה בלבד ב-M3	M2	הרשאת גישה רגילה ב-M2, ‏ A1, ‏ A2, ‏ A3
U2	הרשאת גישה רגילה ב-M2 הרשאת קריאה בלבד ב-M3	M3	הרשאת קריאה בלבד ב-M3, ‏ A1, ‏ A4