التعرّف على نموذج الوصول إلى "إعلانات Google"

هناك نوعان من حسابات "إعلانات Google": الحسابات الإدارية على "إعلانات Google" و حسابات المعلِنين على "إعلانات Google" (المعروفة أيضًا باسم حسابات العملاء). يمكن للحسابات الإدارية إدارة حسابات إدارية أخرى على "إعلانات Google" أو حسابات معلِنين على "إعلانات Google". يمكنك ربط حساب معلِن بحساب إداري ثم إدارة حساب المعلِن من خلال الحساب الإداري. البنية المرتبطة الإجمالية هي رسم بياني موجّه غير دوري مع حسابات المعلِنين على مستوى الأوراق.

يمكنك منح مستخدمين فرديين أو حسابات خدمة إذن الوصول إلى حسابات "إعلانات Google". هناك طريقتان لمنح المستخدمين إذن الوصول إلى حساب معلِن:

• امنح المستخدم إذن الوصول المباشر إلى حساب المعلِن من خلال دعوة المستخدم إلى هذا الحساب.
• امنح المستخدم إذن وصول غير مباشر إلى حساب المعلِن من خلال دعوته إلى حساب إداري مرتبط بهذا الحساب. يحصل المستخدم على إذن الوصول إلى حساب المعلِن لأنّ الحساب الإداري لديه إذن الوصول إلى جميع الحسابات المرتبطة به.

يمكنك أيضًا إسناد أدوار المستخدمين عند دعوة مستخدم لإدارة حساب.

ضَع في اعتبارك التسلسل الهرمي التالي للحسابات. افترِض أنّ جميع المستخدمين لديهم إذن الوصول العادي.

يلخّص الجدول التالي بنية الحساب هذه.

المستخدم	لديه إذن وصول مباشر إلى	لديه إذن وصول غير مباشر إلى
U1, SA1	التصميم 1	M2 وA1 وA2 وA3
U2	‫M2 وM3	A1 وA2 وA3 وA4
U3	الإكسسوار 4

معرّف تسجيل الدخول للعميل

قد يكون لدى المستخدم إذن الوصول إلى تسلسلات هرمية متعددة للحسابات. عند إجراء طلب بيانات من واجهة برمجة التطبيقات في مثل هذه الحالات، عليك تحديد الحساب الجذر الذي سيتم استخدامه لتحديد مستويات التفويض والوصول إلى الحساب بشكل صحيح. ويتم ذلك من خلال تحديد عنوان login-customer-id كجزء من طلب واجهة برمجة التطبيقات.

يستخدم الجدول التالي التسلسل الهرمي للحسابات من المثال السابق لعرض معرّفات العملاء التي يمكنك استخدامها لتسجيل الدخول، وقائمة الحسابات المقابلة التي يمكنك إجراء طلبات إليها.

المستخدم	معرّف تسجيل الدخول للعميل المطلوب استخدامه	الحسابات التي سيتم إرسال طلبات البيانات إليها من واجهة برمجة التطبيقات
U1, SA1	التصميم 1	M1 وM2 وA1 وA2 وA3
U2	M2	M2 وA1 وA2 وA3
U2	التصميم 3	‫M3 وA1 وA4
U3	الإكسسوار 4	الإكسسوار 4

يمكنك تخطّي توفير العنوان login-customer-id إذا كان لدى المستخدم إذن وصول مباشر إلى حساب "إعلانات Google" الذي تجري عمليات طلب إليه. على سبيل المثال، ليس عليك تحديد عنوان login-customer-id عند استخدام بيانات اعتماد U3 لإجراء طلب إلى A4، لأنّ خوادم "إعلانات Google" يمكنها تحديد مستوى الوصول بشكل صحيح من رقم تعريف العميل (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". عند منح دور مستخدم إلى حساب على مستوى الحساب الإداري، يتم توريث الدور من خلال الحسابات في التسلسل الهرمي. في حال كان لدى المستخدم أدوار متضاربة لحساب معيّن، يتم تحديد المستوى الصحيح من خلال حساب login-customer-id المحدّد في طلب واجهة برمجة التطبيقات.

يستخدم الجدول التالي التسلسل الهرمي للحساب من المثال السابق ويوضّح تأثير منح أدوار مختلفة للمستخدمين.

المستخدم	تم منح دور المستخدم	login-customer-id	مستوى الوصول الفعّال
SA1	إذن وصول عادي إلى الحساب M1	التصميم 1	إذن الوصول العادي إلى M1 وM2 وA1 وA2 وA3
U2	إذن بالوصول العادي على M2 إذن بالاطّلاع على M3	M2	الإذن بالوصول العادي على M2 وA1 وA2 وA3
U2	إذن بالوصول العادي على M2 إذن بالاطّلاع على M3	التصميم 3	إذن بالاطّلاع على M3 وA1 وA4