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

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

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

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

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

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

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

کاربر	دسترسی مستقیم دارد	دسترسی غیرمستقیم دارد
یو۱، اس‌ای۱	ام۱	M2، A1، A2، A3
U2	ام۲، ام۳	A1، A2، A3، A4
یو۳	A4

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

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

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

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

اگر کاربر دسترسی مستقیم به حساب گوگل ادز که با آن فراخوانی می‌کنید، دارد، می‌توانید از ارائه هدر login-customer-id صرف نظر کنید. برای مثال، هنگام استفاده از اعتبارنامه‌های U3 برای فراخوانی A4 ، نیازی به مشخص کردن هدر login-customer-id ندارید، زیرا سرورهای گوگل ادز می‌توانند سطح دسترسی را از روی شناسه مشتری ( 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);

پی اچ پی

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

پی اچ پی

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
      

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

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

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

کاربر	نقش کاربر اعطا شد	ورود-شناسه-مشتری	سطح دسترسی موثر
SA1	دسترسی استاندارد در حساب M1	ام۱	دسترسی استاندارد به مسیرهای M1، M2، A1، A2، A3
U2	دسترسی استاندارد در M2 دسترسی فقط خواندنی روی M3	ام۲	دسترسی استاندارد در M2، A1، A2، A3
U2	دسترسی استاندارد در M2 دسترسی فقط خواندنی روی M3	ام۳	دسترسی فقط خواندنی روی M3، A1، A4