التعرّف على نموذج الوصول في "إعلانات 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 M3 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
 M3 الإذن بالقراءة فقط في M3 وA1 وA4
السابق
نظرة عامة
التالي
سير عمل حساب الخدمة