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

يلخّص الجدول التالي بنية هذا الحساب.
| المستخدم | لديه إذن وصول مباشر إلى | لديه إذن وصول غير مباشر إلى |
|---|---|---|
| U1, SA1 | M1 | M2 وA1 وA2 وA3 |
| U2 | M2 وM3 | A1 وA2 وA3 وA4 |
| U3 | A4 |
معرّف تسجيل الدخول للعميل
قد يكون لدى المستخدم إذن الوصول إلى تسلسلات هرمية متعددة للحسابات. عند إجراء طلب بيانات من واجهة برمجة التطبيقات في مثل هذه الحالات، عليك تحديد الحساب الرئيسي الذي سيتم استخدامه لتحديد مستويات التفويض والوصول إلى الحساب بشكل صحيح. لإجراء ذلك، عليك تضمين العنوان login-customer-id في طلب البيانات من واجهة برمجة التطبيقات.
يستخدم الجدول التالي التدرّج الهرمي للحساب من المثال السابق لعرض معرّفات العملاء التي يمكنك استخدامها لتسجيل الدخول، وقائمة الحسابات المقابلة التي يمكنك إجراء طلبات إليها.
| المستخدم | معرّف تسجيل الدخول للعميل المطلوب استخدامه | الحسابات التي سيتم إرسال طلبات البيانات إلى واجهة برمجة التطبيقات منها |
|---|---|---|
| U1, SA1 | M1 | M1 وM2 وA1 وA2 وA3 |
| U2 | M2 | M2 وA1 وA2 وA3 |
| U2 | التصميم 3 | M3 وA1 وA4 |
| U3 | A4 | A4 |
يمكنك تخطّي تقديم العنوان login-customer-id إذا كان لدى المستخدم إذن وصول مباشر إلى حساب "إعلانات Google" الذي تجري عمليات طلب إليه. على سبيل المثال، ليس عليك تحديد العنوان login-customer-id عند استخدام بيانات اعتماد U3 لإجراء طلب إلى A4، لأنّ خوادم "إعلانات Google" يمكنها تحديد مستوى الوصول بشكل صحيح من رقم تعريف العميل (A4).
إذا كنت تستخدم مكتبة برامج لعميل Google Ads API، استخدِم الإعدادات التالية لتحديد عنوان login-customer-id.
جافا
أضِف الإعداد التالي إلى ملف 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"يمكنك استخدام طريقة
CustomerService.ListAccessibleCustomers
لاسترداد قائمة الحسابات التي يمكن للمستخدم الوصول إليها مباشرةً.
يمكن استخدام هذه الحسابات كقيم صالحة لعنوان login-customer-id.
جافا
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); } } }
#C
public void Run(GoogleAdsClient client) { // Get the CustomerService. CustomerServiceClient customerService = client.GetService(Services.V25.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; } }
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); } }
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}"')
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
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; }
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}" \
ماذا لو لم تستردّ الطريقة ListAccessibleCustomers معرّف العميل؟
إذا لم تستردّ الطريقة CustomerService.ListAccessibleCustomers معرّف عميل كنت تتوقّع ظهوره في النتائج،
إليك بعض التفسيرات المحتملة.
يمكنك الوصول إلى رقم تعريف العميل، ولكن يتم منح إذن الوصول من خلال حساب إداري رئيسي. على سبيل المثال، إذا استدعيت الطريقة
ListAccessibleCustomersباستخدام بيانات اعتماد المستخدمU1في المثال السابق، ستعرض الطريقةM1فقط في النتائج، حتى إذا كانU1لديه إذن الوصول إلى المزيد من الحسابات. للتأكّد من هذه الإمكانية، استرجِع التدرّج الهرمي للحساب من خلال تنفيذ طلبات البحثsearchأوsearchStreamعلى موردcustomer_clientلكل حساب من الحسابات التي تعرضها الطريقةListAccessibleCustomers. لإجراء ذلك، عليك ضبط كل حساب من هذه الحسابات علىlogin-customer-id، كما هو موضّح في القسم السابق. إذا كان لديك إذن الوصول إلى الحساب المستهدَف، يمكنك استرداده كجزء من إحدى التسلسلات الهرمية للحسابات.أنت تستخدم بيانات اعتماد OAuth غير صحيحة. السيناريو الأكثر شيوعًا هو أنّك تستخدم بيانات اعتماد مستخدم آخر. على سبيل المثال، قد يكون السبب هو الخلط عن طريق الخطأ بين بيانات اعتماد وضع الحماية أو المطوّر وبيانات اعتماد الإصدار العلني، أو قراءة بيانات اعتماد مستخدم آخر بشكل غير صحيح من قاعدة البيانات أو ذاكرة التخزين المؤقت المحلية. إحدى الطرق المحتملة لتحديد المشكلة وحلّها هي استخدام Google People API لاسترداد اسم المستخدم الذي سجّل الدخول وعنوان بريده الإلكتروني والتحقّق مما إذا كانا يتطابقان مع عنوان البريد الإلكتروني الذي كنت تتوقّعه.
ليس لديك إذن بالوصول إلى الحساب. اتّبِع دليل الوصول إلى الحساب للحصول على إذن الوصول إلى حساب العميل الصحيح.
أدوار المستخدمين
لا تتضمّن واجهة Google Ads API نموذج وصول منفصلاً خاصًا بها، ولا تستخدم نطاقات OAuth 2.0 منفصلة للحدّ من الوظائف. على سبيل المثال، تستخدم Google Ads API النطاقات نفسها للعمليات التي تتطلّب إذنًا بالقراءة فقط وتلك التي تتطلّب إذنًا بالقراءة والكتابة. بدلاً من ذلك، تتّبع Google Ads API أدوار المستخدمين نفسها التي تتيحها "إعلانات Google". عند منح دور مستخدم لحساب على مستوى الحساب الإداري، يتم توريث الدور من خلال الحسابات في التدرّج الهرمي. إذا كان لدى المستخدم أدوار متضاربة في حساب معيّن، يتم تحديد المستوى الصحيح من خلال الحساب login-customer-id المحدّد في طلب بيانات من واجهة برمجة التطبيقات.
يستخدم الجدول التالي التسلسل الهرمي للحساب من المثال السابق ويعرض تأثير منح أدوار مختلفة للمستخدمين.
| المستخدم | تم منح دور المستخدم | login-customer-id | مستوى الوصول الفعّال |
|---|---|---|---|
| SA1 | إذن الوصول العادي إلى الحساب M1 | M1 | إذن الوصول العادي على M1 وM2 وA1 وA2 وA3 |
| U2 |
إذن الوصول العادي على M2 إذن بالقراءة فقط على M3 |
M2 | إذن بالوصول العادي على M2 وA1 وA2 وA3 |
| U2 |
إذن الوصول العادي على M2 إذن بالقراءة فقط على M3 |
التصميم 3 | الإذن بالقراءة فقط على أجهزة M3 وA1 وA4 |