Omówienie modelu dostępu do Google Ads

Istnieją 2 rodzaje kont Google Ads: konta menedżera Google Ads i konta reklamodawcy Google Ads (znane też jako konta klienta). Konta menedżera mogą zarządzać innymi kontami menedżera Google Ads lub kontami reklamodawcy Google Ads. Możesz połączyć konto reklamodawcy z kontem menedżera, a następnie zarządzać kontem reklamodawcy za pomocą konta menedżera. Ogólna struktura połączonych kont to skierowany graf acykliczny, w którym konta reklamodawcy znajdują się na poziomie liści.

Możesz przyznać poszczególnym użytkownikom lub kontom usługi dostęp do kont Google Ads. Istnieją 2 sposoby przyznawania użytkownikom dostępu do konta reklamodawcy:

  • Przyznaj użytkownikowi bezpośredni dostęp do konta reklamodawcy, zapraszając go na to konto.
  • Przyznaj użytkownikowi pośredni dostęp do konta reklamodawcy, zapraszając go na konto menedżera połączone z tym kontem. Użytkownik uzyskuje dostęp do konta reklamodawcy, ponieważ konto menedżera ma dostęp do wszystkich kont połączonych z nim.

Gdy zapraszasz użytkownika do zarządzania kontem, możesz też przypisać mu rolę użytkownika.

Przyjrzyj się tej hierarchii kont. Załóżmy, że wszyscy użytkownicy mają dostęp standardowy.

Diagram hierarchii konta

W tabeli poniżej znajdziesz podsumowanie tej struktury kont.

Użytkownik Ma bezpośredni dostęp do Ma pośredni dostęp do
U1, SA1 M1 M2, A1, A2, A3
U2 M2, M3 A1, A2, A3, A4
U3 A4  

Identyfikator klienta logowania

Użytkownik może mieć dostęp do wielu hierarchii kont. W takich przypadkach podczas wywoływania interfejsu API musisz określić konto główne, które ma być używane, aby prawidłowo określić poziom autoryzacji i dostępu do konta. W tym celu w żądaniu do interfejsu API należy podać nagłówek login-customer-id.

W tabeli poniżej użyto hierarchii kont z poprzedniego przykładu, aby pokazać, jakich identyfikatorów klienta logowania możesz używać, oraz odpowiadającą im listę kont, do których możesz wykonywać wywołania.

Użytkownik Identyfikator klienta logowania do użycia Konta, do których można wykonywać wywołania interfejsu API
U1, SA1 M1 M1, M2, A1, A2, A3
U2 M2 M2, A1, A2, A3
U2 M3 M3, A1, A4
U3 A4 A4

Jeśli użytkownik ma bezpośredni dostęp do konta Google Ads, do którego wykonujesz wywołania, możesz pominąć podanie nagłówka login-customer-id. Na przykład nie musisz określać nagłówka login-customer-id, gdy używasz danych logowania U3 do wywołania A4, ponieważ serwery Google Ads mogą prawidłowo określić poziom dostępu na podstawie identyfikatora klienta (A4).

Jeśli używasz jednej z naszych bibliotek klienta, użyj tych ustawień, aby określić nagłówek login-customer-id.

Java

Dodaj to ustawienie do pliku ads.properties.

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

C#

Dodaj to ustawienie podczas inicjowania obiektu GoogleAdsConfig i użyj go do utworzenia obiektu GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    ...
    LoginCustomerId = ******
};
GoogleAdsClient client = new GoogleAdsClient(config);

PHP

Dodaj to ustawienie do pliku google_ads_php.ini.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

Python

Dodaj to ustawienie do pliku google-ads.yaml.

login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

Ruby

Dodaj to ustawienie do pliku google_ads_config.rb.

Google::Ads::GoogleAds::Config.new do |c|
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

Utwórz instancję GoogleAdsClient, przekazując ścieżkę do miejsca, w którym przechowujesz ten plik.

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

Perl

Dodaj to ustawienie do pliku googleads.properties.

loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

curl

Podczas uruchamiania polecenia curl określ ten argument wiersza poleceń.

-H "login-customer-id: LOGIN_CUSTOMER_ID"

Aby pobrać listę kont, do których użytkownik ma bezpośredni dostęp, możesz użyć metody CustomerService.ListAccessibleCustomers. Te konta mogą być używane jako prawidłowe wartości nagłówka 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);
    }
  }
}
      

C#

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

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;
}
      

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}" \
      

Co zrobić, jeśli metoda ListAccessibleCustomers nie pobierze mojego identyfikatora klienta?

Jeśli CustomerService.ListAccessibleCustomers metoda nie pobrała identyfikatora klienta, który powinien się pojawić w wynikach, może to być spowodowane kilkoma przyczynami.

  1. Masz dostęp do identyfikatora klienta, ale dostęp ten został przyznany przez nadrzędne konto menedżera. Jeśli na przykład wywołasz ListAccessibleCustomers metodę z danymi logowania użytkownika U1 w poprzednim przykładzie, w wynikach otrzymasz tylko M1, mimo że U1 ma dostęp do większej liczby kont. Aby potwierdzić tę możliwość, pobierz hierarchię kont dla każdego konta zwróconego przez metodę ListAccessibleCustomers. Aby to zrobić, ustaw każde z tych kont jako identyfikator klienta logowania zgodnie z opisem w poprzedniej sekcji. Jeśli masz dostęp do konta docelowego, powinno ono być dostępne w ramach jednej z hierarchii kont.

  2. Używasz nieprawidłowych danych uwierzytelniających OAuth. Najczęstszy scenariusz to używanie danych logowania innego użytkownika. Może to być spowodowane np. przypadkowym pomieszaniem danych logowania do piaskownicy lub konta dewelopera z danymi logowania do konta produkcyjnego albo nieprawidłowym odczytaniem danych logowania innego użytkownika z bazy danych lub pamięci podręcznej. Jednym ze sposobów rozwiązania tego problemu jest użycie interfejsu Google People API do pobrania imienia i nazwiska oraz adresu e-mail zalogowanego użytkownika i sprawdzenia, czy pasuje on do oczekiwanego adresu e-mail.

  3. Nie masz dostępu do konta. Postępuj zgodnie z instrukcjami, aby uzyskać dostęp do właściwego konta klienta.

Role użytkowników

Interfejs Google Ads API nie ma własnego modelu dostępu ani nie używa oddzielnych zakresów OAuth 2.0 do ograniczania funkcjonalności. Na przykład interfejs Google Ads API używa tych samych zakresów do operacji tylko do odczytu i do odczytu i zapisu. Zamiast tego interfejs Google Ads API korzysta z tych samych ról użytkowników, które są obsługiwane przez Google Ads. Gdy rola użytkownika zostanie przyznana na poziomie menedżera, jest dziedziczona przez konta w hierarchii. Jeśli użytkownik ma sprzeczne role na danym koncie, prawidłowy poziom jest określany przez konto login-customer-id podane w żądaniu do interfejsu API.

W tabeli poniżej użyto hierarchii kont z poprzedniego przykładu i pokazano, jak przyznawanie użytkownikom różnych ról użytkownika wpływa na dostęp.

Użytkownik Przyznana rola użytkownika login-customer-id Efektywny poziom dostępu
SA1 Dostęp standardowy do konta M1 M1 Dostęp standardowy do kont M1, M2, A1, A2, A3
U2 Dostęp standardowy do konta M2
Dostęp tylko do odczytu do konta M3
M2 Dostęp standardowy do kont M2, A1, A2, A3
U2 Dostęp standardowy do konta M2
Dostęp tylko do odczytu do konta M3
M3 Dostęp tylko do odczytu do kont M3, A1, A4