آشنایی با مدل دسترسی 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 را در درخواست میانای برنامه‌سازی کاربردی خود اضافه کنید.

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

کاربر شناسه مشتری ورود به سیستم برای استفاده حساب‌هایی که فراخوانی‌های میانای برنامه‌سازی کاربردی به آن‌ها انجام می‌شود
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، آرگومان خط فرمان زیر را مشخص کنید.

-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

پرل

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