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

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

يمكن للحسابات الإدارية إدارة حسابات إدارية أخرى على "إعلانات Google" أو حسابات معلِنين على "إعلانات Google". يمكنك ربط حساب معلِن بحساب إداري، ثم إدارة حساب المعلِن من خلال الحساب الإداري. البنية المرتبطة الإجمالية هي رسم بياني موجّه غير دوري مع حسابات المعلِنين على مستوى الورقة.

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

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

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

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

مخطّط بياني يعرض حسابات المدير M1 وM2 وM3 المرتبطة بحسابات المعلِنين من A1 إلى A4

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

المستخدم لديه إذن وصول مباشر إلى لديه إذن وصول غير مباشر إلى
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 معرّف عميل كنت تتوقّع ظهوره في النتائج، إليك بعض التفسيرات المحتملة.

  1. يمكنك الوصول إلى رقم تعريف العميل، ولكن يتم منح إذن الوصول من خلال حساب إداري رئيسي. على سبيل المثال، إذا استدعيت الطريقة ListAccessibleCustomers باستخدام بيانات اعتماد المستخدم U1 في المثال السابق، ستعرض الطريقة M1 فقط في النتائج، حتى إذا كان U1 لديه إذن الوصول إلى المزيد من الحسابات. للتأكّد من هذه الإمكانية، استرجِع التدرّج الهرمي للحساب من خلال تنفيذ طلبات البحث search أو searchStream على مورد customer_client لكل حساب من الحسابات التي تعرضها الطريقة ListAccessibleCustomers. لإجراء ذلك، عليك ضبط كل حساب من هذه الحسابات على login-customer-id، كما هو موضّح في القسم السابق. إذا كان لديك إذن الوصول إلى الحساب المستهدَف، يمكنك استرداده كجزء من إحدى التسلسلات الهرمية للحسابات.

  2. أنت تستخدم بيانات اعتماد OAuth غير صحيحة. السيناريو الأكثر شيوعًا هو أنّك تستخدم بيانات اعتماد مستخدم آخر. على سبيل المثال، قد يكون السبب هو الخلط عن طريق الخطأ بين بيانات اعتماد وضع الحماية أو المطوّر وبيانات اعتماد الإصدار العلني، أو قراءة بيانات اعتماد مستخدم آخر بشكل غير صحيح من قاعدة البيانات أو ذاكرة التخزين المؤقت المحلية. إحدى الطرق المحتملة لتحديد المشكلة وحلّها هي استخدام Google People API لاسترداد اسم المستخدم الذي سجّل الدخول وعنوان بريده الإلكتروني والتحقّق مما إذا كانا يتطابقان مع عنوان البريد الإلكتروني الذي كنت تتوقّعه.

  3. ليس لديك إذن بالوصول إلى الحساب. اتّبِع دليل الوصول إلى الحساب للحصول على إذن الوصول إلى حساب العميل الصحيح.

أدوار المستخدمين

لا تتضمّن واجهة 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