Omówienie modelu dostępu do Google Ads

Istnieją 2 rodzaje kont Google Ads: konta menedżera Google Ads i konta reklamodawcy Google Ads. Szczegółowe wyjaśnienie, jak te i inne terminy (takie jak konto klienta i klient) są ze sobą powiązane, znajdziesz w artykule Rodzaje kont.

Konta menedżera mogą zarządzać innymi kontami menedżera Google Ads lub kontami reklamodawców 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łączeń to skierowany graf acykliczny z kontami reklamodawców na poziomie liścia.

Dostęp do kont Google Ads możesz przyznawać poszczególnym użytkownikom lub kontom usługi. Dostęp do konta reklamodawcy możesz przyznać użytkownikom na 2 sposoby:

  • Przyznaj użytkownikowi bezpośredni dostęp do konta reklamodawcy, zapraszając go na to konto.
  • Przyznaj użytkownikowi dostęp pośredni 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 połączonych z nim kont.

Możesz też przypisywać role użytkowników, gdy zapraszasz użytkownika do zarządzania kontem.

Weź pod uwagę tę hierarchię kont. Załóżmy, że wszyscy użytkownicy mają dostęp standardowy.

Diagram przedstawiający konta menedżera M1, M2 i M3 połączone z kontami reklamodawców A1–A4.

Tabela poniżej zawiera podsumowanie tej struktury konta.

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 używany do 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 zostać użyte do prawidłowego określenia poziomów autoryzacji i poziomów dostępu do konta. Aby to zrobić, dodaj do żądania do interfejsu API 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ć i jakie odpowiadające im listy kont możesz wywoływać.

Użytkownik Identyfikator klienta, którego chcesz użyć do logowania Konta, na których mają być wykonywane 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

Możesz pominąć nagłówek login-customer-id, jeśli użytkownik ma bezpośredni dostęp do konta Google Ads, do którego wysyłasz wywołania. Na przykład nie musisz podawać 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 biblioteki klienta interfejsu Google Ads API, użyj tych ustawień, aby określić nagłówek login-customer-id.

Java

Dodaj do pliku ads.properties to ustawienie.

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

.NET

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    // ...
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);

Python

Dodaj do pliku google-ads.yaml to ustawienie.

login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

PHP

Dodaj do pliku google_ads_php.ini to ustawienie.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

Ruby

Dodaj do pliku google_ads_config.rb to ustawienie.

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 do pliku googleads.properties to ustawienie.

loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

curl

Podczas uruchamiania polecenia curl podaj ten argument wiersza poleceń.

-H "login-customer-id: INSERT_LOGIN_CUSTOMER_ID_HERE"

Aby pobrać listę kont, do których użytkownik ma bezpośredni dostęp, możesz użyć metody CustomerService.ListAccessibleCustomers. Tych kont można używać jako prawidłowych 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.V26.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,
#   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}" \

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

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

  1. Masz dostęp do identyfikatora klienta, ale został on przyznany przez nadrzędne konto menedżera. Jeśli na przykład wywołasz metodę ListAccessibleCustomers z danymi logowania użytkownika U1 z poprzedniego przykładu, metoda zwróci w wynikach tylko M1, mimo że U1 ma dostęp do większej liczby kont. Aby potwierdzić tę możliwość, pobierz hierarchię kont, wykonując zapytania search lub searchStream dotyczące zasobu customer_client dla każdego z kont zwróconych przez metodę ListAccessibleCustomers. Aby to zrobić, ustaw każde z tych kont jako login-customer-id, jak opisano w poprzedniej sekcji. Jeśli masz dostęp do konta docelowego, możesz je pobrać w ramach jednej z hierarchii kont.

  2. Używasz nieprawidłowych danych logowania OAuth. Najczęstszym scenariuszem jest używanie danych logowania innego użytkownika. Może to być na przykład spowodowane przypadkowym pomyleniem danych logowania do piaskownicy lub danych logowania dewelopera z danymi logowania do środowiska produkcyjnego albo nieprawidłowym odczytaniem danych logowania innego użytkownika z bazy danych lub lokalnej pamięci podręcznej. Jednym ze sposobów rozwiązania tego problemu jest użycie interfejsu Google People API do pobrania nazwy i adresu e-mail zalogowanego użytkownika i sprawdzenia, czy jest on zgodny z oczekiwanym adresem e-mail.

  3. Nie masz dostępu do konta. Aby uzyskać dostęp do właściwego konta klienta, postępuj zgodnie z przewodnikiem po dostępie do konta.

Role użytkowników

Interfejs Google Ads API nie ma własnego, oddzielnego modelu dostępu ani nie używa oddzielnych zakresów protokołu OAuth 2.0 do ograniczania funkcjonalności. Na przykład interfejs Google Ads API używa tych samych zakresów w przypadku operacji tylko do odczytu i operacji 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 kontu na poziomie menedżera, jest ona 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 wykorzystano hierarchię kont z poprzedniego przykładu, aby pokazać, jak działa przyznawanie użytkownikom różnych ról.

Użytkownik Przyznano rolę użytkownika login-customer-id Skuteczny poziom dostępu
SA1 Dostęp standardowy na koncie M1 M1 Dostęp standardowy do M1, M2, A1, A2, A3
U2 Dostęp standardowy do M2
Dostęp tylko do odczytu do M3
 M2 Dostęp standardowy na instancjach M2, A1, A2, A3
U2 Dostęp standardowy do M2
Dostęp tylko do odczytu do M3
 M3 Dostęp tylko do odczytu do M3, A1, A4
Wstecz
Przegląd
Dalej
Proces konta usługi