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

هناك نوعان من حسابات "إعلانات 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 M3 M3 وA1 وA4
U3 A4 A4

يمكنك تخطّي تقديم عنوان login-customer-id إذا كان لدى المستخدم إذن وصول مباشر إلى حساب "إعلانات Google" الذي تقدّم طلبات إليه. على سبيل المثال، ليس عليك تحديد عنوان login-customer-id عند استخدام بيانات اعتماد U3 لتقديم طلب إلى A4، لأنّ خوادم "إعلانات Google" يمكنها تحديد مستوى الوصول بشكلٍ صحيح من رقم تعريف العميل (A4).

إذا كنت تستخدِم إحدى مكتبات العملاء، استخدِم الإعدادات التالية لتحديد عنوان login-customer-id.

جافا

أضِف الإعداد التالي إلى ملف 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.

جافا

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.V24.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,
#   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}" \

ماذا لو لم تستردّ طريقة ListAccessibleCustomers رقم تعريف العميل؟

إذا لم تستردّ طريقة CustomerService.ListAccessibleCustomersmethod رقم تعريف عميل كنت تتوقّع ظهوره في النتائج، هناك بعض التفسيرات المحتملة.

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

  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
السابق
نظرة عامة
التالي
سير عمل حساب الخدمة