הסבר על מודל הגישה של 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).

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

Java

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

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

C#‎

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    ...
    LoginCustomerId = ******
};
GoogleAdsClient client = new GoogleAdsClient(config);

PHP

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

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

Python

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

login_customer_id: 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: LOGIN_CUSTOMER_ID"

אפשר להשתמש בשיטה 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.V21.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,
#   DEVELOPER_TOKEN,
#   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 "developer-token: ${DEVELOPER_TOKEN}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
list_accessible_customers.sh
      

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

ל-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