瞭解 Google Ads 存取模式

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  

登入客戶 ID

使用者可能可以存取多個帳戶階層。在這種情況下發出 API 呼叫時，您需要指定要使用的根帳戶，才能正確判斷授權和帳戶存取層級。方法是在 API 要求中指定 login-customer-id 標頭。

下表使用上一個範例中的帳戶階層，說明可使用的登入客戶 ID，以及可呼叫的對應帳戶清單。

使用者 登入客戶 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 伺服器可以從客戶 ID (A4) 正確判斷存取層級。

如果您使用我們的用戶端程式庫，請使用下列設定指定 login-customer-id 標頭。

Java

在 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 標頭的有效值。

Java

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

C#

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

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

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

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

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

使用者角色

Google Ads API 沒有專屬的存取模式，也不會使用專屬的 OAuth 2.0 範圍來限制功能。舉例來說，Google Ads API 對於唯讀和讀寫作業使用相同的範圍。Google Ads API 支援與 Google Ads 相同的使用者角色。如果是在管理員層級授予帳戶使用者角色，階層中的帳戶就會沿用該角色。如果使用者在特定帳戶中擁有衝突的角色，系統會根據 API 要求中指定的 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 的唯讀存取權
上一頁
總覽
下一頁
服務帳戶工作流程