مدل دسترسی به تبلیغات گوگل را درک کنید

دو نوع حساب Google Ads وجود دارد: حساب‌های مدیر Google Ads و حساب‌های تبلیغ‌کننده Google Ads (همچنین به عنوان حساب‌های مشتری یا مشتری شناخته می‌شوند). حساب‌های مدیر می‌توانند سایر حساب‌های مدیر Google Ads یا حساب‌های تبلیغ‌کننده Google Ads را مدیریت کنند. می‌توانید یک حساب تبلیغ‌کننده را به یک حساب مدیر پیوند دهید و سپس حساب تبلیغ‌کننده را از طریق حساب مدیر مدیریت کنید. ساختار کلی پیوند شده یک نمودار غیر چرخه ای جهت دار با حساب های تبلیغ کننده در سطح برگ است.

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

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

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

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

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

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

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

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

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

کاربر	ورود به سیستم شناسه مشتری برای استفاده	حساب‌هایی برای برقراری تماس 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 ) تعیین کنند.

اگر از یکی از کتابخانه های سرویس گیرنده ما استفاده می کنید، از تنظیمات زیر برای تعیین هدر login-customer-id استفاده کنید.

جاوا

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

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

سی شارپ

هنگام تنظیم اولیه شیء 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"

پایتون

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

login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

روبی

تنظیمات زیر را به فایل 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: 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);
    }
  }
}
ListAccessibleCustomers.java
      

سی شارپ

public void Run(GoogleAdsClient client)
{
    // Get the CustomerService.
    CustomerServiceClient customerService = client.GetService(Services.V21.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;
    }
}
ListAccessibleCustomers.cs
      

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);
    }
}
ListAccessibleCustomers.php
      

پایتون

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}"')
list_accessible_customers.py
      

روبی

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
list_accessible_customers.rb
      

پرل

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;
}
list_accessible_customers.pl
      

حلقه کردن

# 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}" \
list_accessible_customers.sh
      

نقش های کاربر

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