آشنایی با مدل دسترسی Google Ads

دو نوع حساب Google Ads وجود دارد: حساب‌های مدیر Google Ads و حساب‌های تبلیغ‌کننده Google Ads. برای توضیح دقیق درباره نحوه ارتباط این اصطلاحات و اصطلاحات دیگر (مانند «حساب مشتری» و «مشتری»)، به انواع حساب مراجعه کنید.

حساب‌های مدیر می‌توانند حساب‌های مدیر Google Ads یا حساب‌های تبلیغ‌کننده Google Ads دیگر را مدیریت کنند. می‌توانید حساب آگهی‌دهنده را به حساب مدیر پیوند دهید و سپس حساب آگهی‌دهنده را ازطریق حساب مدیر مدیریت کنید. ساختار پیوندی کلی یک گراف جهت‌دار غیرمدور با حساب‌های آگهی‌دهنده در سطح برگ است.

می‌توانید به کاربران یا حساب‌های سرویس به‌طور جداگانه اجازه دسترسی به حساب‌های Google Ads بدهید. دو روش برای دادن دسترسی به حساب تبلیغ‌کننده به کاربران وجود دارد:

  • با دعوت کردن کاربر به حساب آگهی‌دهنده، به او دسترسی مستقیم به حساب را اعطا کنید.
  • با دعوت کردن کاربر به حساب مدیر پیوندشده به حساب آگهی‌دهنده، به او دسترسی غیرمستقیم به حساب آگهی‌دهنده بدهید. کاربر به حساب آگهی‌دهنده دسترسی پیدا می‌کند زیرا حساب مدیر به همه حساب‌های پیوندشده تحت آن دسترسی دارد.

همچنین می‌توانید هنگام دعوت از کاربر برای مدیریت حساب، نقش‌های کاربر را اختصاص دهید.

سلسله‌مراتب حساب زیر را درنظر بگیرید. فرض کنید همه کاربران دسترسی «استاندارد» دارند.

نموداری که حساب‌های مدیر M1،‏ M2، و M3 را که به حساب‌های آگهی‌دهنده A1 تا A4 پیوند شده‌اند نشان می‌دهد.

جدول زیر این ساختار حساب را خلاصه می‌کند.

کاربر دسترسی مستقیم دارد به دسترسی غیرمستقیم به این موارد دارد
U1،‏ SA1 M1 M2،‏ A1،‏ A2،‏ A3
U2 M2،‏ M3 A1،‏ A2،‏ A3،‏ A4
U3 A4  

شناسه مشتری ورود به سیستم

کاربر ممکن است به چندین سلسله‌مراتب حساب دسترسی داشته باشد. هنگام برقراری تماس API در چنین مواردی، باید حساب ریشه‌ای را که قرار است برای تعیین صحیح سطوح مجوز و دسترسی به حساب استفاده شود مشخص کنید. برای انجام این کار، سرصفحه login-customer-id را در درخواست میانای برنامه‌سازی کاربردی خود اضافه کنید.

جدول زیر از سلسله‌مراتب حساب از مثال قبلی استفاده می‌کند تا نشان دهد از کدام شناسه‌های مشتری ورود به سیستم می‌توانید استفاده کنید و فهرست حساب‌های متناظری را که می‌توانید با آن‌ها تماس بگیرید نشان می‌دهد.

کاربر شناسه مشتری ورود به سیستم برای استفاده حساب‌هایی که فراخوانی‌های API به آن‌ها انجام می‌شود
U1،‏ SA1 M1 M1،‏ M2،‏ A1،‏ A2،‏ A3
U2 M2 M2،‏ A1،‏ A2،‏ A3
U2 M3 M3،‏ A1،‏ A4
U3 A4 A4

اگر کاربر دسترسی مستقیم به حساب Google Ads که با آن تماس می‌گیرید داشته باشد، می‌توانید از ارائه سرصفحه login-customer-id صرف‌نظر کنید. برای مثال، هنگام استفاده از اطلاعات کاربری U3 برای برقراری تماس با A4، نیازی به مشخص کردن سرصفحه login-customer-id ندارید، زیرا سرورهای Google Ads می‌توانند سطح دسترسی را به‌درستی از شناسه مشتری (A4) تعیین کنند.

اگر از کتابخانه کارخواه Google Ads API استفاده می‌کنید، از تنظیمات زیر برای مشخص کردن سرصفحه login-customer-id استفاده کنید.

جاوا

تنظیمات زیر را به فایل ads.properties خود اضافه کنید.

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

دات نت

هنگام مقداردهی اولیه شیء 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'
)

پرل

تنظیمات زیر را به فایل 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.V26.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

پرل

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 را برای هریک از حساب‌های برگردانده‌شده توسط روش ListAccessibleCustomers در مقابل منبع customer_client اجرا کنید. برای انجام این کار، هریک از این حساب‌ها را به‌عنوان login-customer-id تنظیم کنید، همان‌طور که در بخش قبلی توضیح داده شده است. اگر به حساب هدف دسترسی دارید، می‌توانید آن را به‌عنوان بخشی از یکی از سلسله‌مراتب حساب واکشی کنید.

  2. از اعتبارنامه‌های OAuth نادرست استفاده می‌کنید. رایج‌ترین سناریو این است که از اطلاعات کاربری کاربر دیگری استفاده می‌کنید. برای مثال، ممکن است به‌دلیل اشتباه گرفتن تصادفی اطلاعات کاربری محیط آزمایشی یا توسعه‌دهنده با اطلاعات کاربری تولید یا خواندن نادرست اطلاعات کاربری کاربر دیگری از پایگاه داده یا حافظه نهان محلی باشد. یک راه ممکن برای عیب‌یابی این مشکل استفاده از Google People API برای بازیابی نام و نشانی ایمیل کاربر واردشده به سیستم و تأیید مطابقت آن با نشانی ایمیل موردانتظار شما است.

  3. به حساب دسترسی ندارید. راهنمای دسترسی به حساب را دنبال کنید تا به حساب مشتری درست دسترسی پیدا کنید.

نقش‌های کاربر

Google Ads API مدل دسترسی جداگانه‌ای برای خود ندارد یا از دامنه‌های OAuth 2.0 جداگانه برای محدود کردن عملکرد استفاده نمی‌کند. برای مثال، Google Ads API از همان گستره‌ها برای عملیات فقط خواندنی درمقابل خواندنی-نوشتنی استفاده می‌کند. درعوض، Google Ads API از همان نقش‌های کاربری پیروی می‌کند که Google Ads پشتیبانی می‌کند. وقتی نقش کاربر به حسابی در سطح مدیر اعطا می‌شود، حساب‌های موجود در سلسله‌مراتب آن نقش را به‌ارث می‌برند. اگر کاربری نقش‌های متناقضی در یک حساب مشخص داشته باشد، سطح صحیح توسط حساب login-customer-id مشخص‌شده در درخواست API حل‌وفصل می‌شود.

جدول زیر از سلسله‌مراتب حساب مثال قبلی استفاده می‌کند و تأثیر اعطای نقش‌های کاربری مختلف به کاربران را نشان می‌دهد.

کاربر نقش کاربر اعطا شد 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
قبلی
نمای کلی
بعدی
گردش کار حساب سرویس