Uwierzytelnianie i autoryzacja

Podobnie jak inne interfejsy API Google, interfejs Google Ads API używa protokołu OAuth 2.0 do uwierzytelniania i autoryzacji. OAuth 2.0 umożliwia aplikacji klienckiej interfejsu Google Ads API dostęp do konta Google Ads użytkownika bez konieczności obsługiwania lub przechowywania informacji logowania użytkownika.

Z tego przewodnika dowiesz się, jak skonfigurować bibliotekę klienta Java na potrzeby uwierzytelniania w interfejsie Google Ads API za pomocą 3 najpopularniejszych procesów OAuth 2.0. Wyjaśniamy też, jakie dane logowania są wymagane.

Więcej informacji o modelu dostępu do interfejsu Google Ads API znajdziesz w przewodniku po modelu dostępu do Google Ads.

Dane logowania

Dostęp do interfejsu Google Ads API wymaga danych logowania OAuth 2.0, a w niektórych przypadkach identyfikatora klienta logowania.

Dane logowania OAuth 2.0

Aby autoryzować użytkowników kont Google z dostępem do kont Google Ads, musisz podać zestaw danych logowania OAuth 2.0. Rodzaj wymaganych danych logowania zależy od używanego przepływu OAuth 2.0.

Biblioteka obsługuje 3 rodzaje przepływów:

• Proces konta usługi
• Proces uwierzytelniania jednego użytkownika
• Proces uwierzytelniania wielu użytkowników

Szczegółowe informacje o przepływach OAuth interfejsu Google Ads API znajdziesz w omówieniu OAuth. Postępuj zgodnie z instrukcjami dotyczącymi przepływu, który najlepiej odpowiada Twoim potrzebom, aby uzyskać wymagane dane logowania.

Identyfikator klienta logującego się

Opcjonalnie podaj identyfikator klienta konta menedżera, które ma dostęp do konta wyświetlającego reklamy. Musisz to określić, jeśli masz dostęp do konta klienta za pomocą konta menedżera. Nie musisz podawać wszystkich kont menedżera na ścieżce do identyfikatora klienta, tylko identyfikator menedżera najwyższego poziomu, którego używasz do określania uprawnień dostępu. Więcej informacji znajdziesz w odpowiedniej dokumentacji.

W bibliotece klienta identyfikator klienta logowania jest określony przez klucz api.googleads.loginCustomerId w pliku ads.properties.

Konfiguracja

Bibliotekę klienta możesz skonfigurować za pomocą pliku ads.properties, zmiennych środowiskowych lub programowo. Ten przewodnik dotyczy korzystania z ads.propertiespliku. Szczegółowe informacje o wszystkich opcjach znajdziesz w przewodniku po konfiguracji.

Jeśli używasz pliku ads.properties, umieść go w katalogu głównym:~/ads.properties

Przepływy pracy OAuth

Podczas korzystania z interfejsu Google Ads API stosuje się 3 typy procesów.

Proces konta usługi

Jest to zalecany przepływ pracy, jeśli nie wymaga on interakcji z użytkownikiem. Ten przepływ pracy wymaga konfiguracji, w ramach której użytkownik dodaje konto usługi do swojego konta Google Ads. Aplikacja może wtedy używać danych logowania konta usługi do zarządzania kontem Google Ads użytkownika.

Gdy będziesz mieć plik JSON klucza prywatnego, dodaj do pliku ads.properties te informacje:

api.googleads.serviceAccountSecretsPath=INSERT_PATH_TO_JSON_HERE
# Only add this key if you are using Google Workspace domain-wide delegation
# to impersonate a user who has access to the Google Ads account.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

Więcej informacji znajdziesz w przewodniku po przepływie pracy konta usługi.

Proces uwierzytelniania jednego użytkownika

Ten przepływ pracy może być używany, jeśli nie możesz korzystać z kont usługi. Ten przepływ pracy wymaga 2 etapów konfiguracji:

1. Udzielić jednemu użytkownikowi dostępu do wszystkich kont, którymi ma zarządzać za pomocą interfejsu Google Ads API. Często stosowanym rozwiązaniem jest przyznanie użytkownikowi dostępu do konta menedżera interfejsu Google Ads API i połączenie wszystkich docelowych kont Google Ads z tym kontem menedżera.
2. Użytkownik uruchamia narzędzie wiersza poleceń, np. gcloud CLI lub GenerateUserCredentialsprzykład kodu, aby autoryzować aplikację do zarządzania w jego imieniu wszystkimi kontami Google Ads.

Gdy uzyskasz te dane logowania, dodaj do pliku ads.properties te informacje:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE

Więcej informacji znajdziesz w przewodniku po przepływie pracy uwierzytelniania pojedynczego użytkownika.

Proces uwierzytelniania wielu użytkowników

Jest to zalecany proces, jeśli aplikacja umożliwia użytkownikom logowanie się i autoryzowanie jej do zarządzania ich kontami Google Ads w ich imieniu. Przykładowy kod GenerateUserCredentials to narzędzie wiersza poleceń, które pokazuje, jak uzyskać uwierzytelnianie użytkownika w czasie działania programu, aby zarządzać jego kontami Google Ads w jego imieniu. Ten przykładowy kod może posłużyć jako punkt odniesienia do tworzenia aplikacji na komputery lub aplikacji internetowych, które wymagają uwierzytelniania użytkownika.

W przypadku aplikacji wielu użytkowników przechowuj identyfikator klienta protokołu OAuth 2.0 i tajny klucz klienta w ads.properties (lub w innym magazynie konfiguracji), a token odświeżania każdego użytkownika końcowego bezpiecznie przechowuj w bazie danych aplikacji i przekazuj go programowo w czasie działania aplikacji podczas tworzenia UserCredentials i GoogleAdsClient:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE

Więcej informacji znajdziesz w przewodniku po przepływie pracy uwierzytelniania wielu użytkowników.

Zarządzanie wieloma kontami

Użytkownik może zarządzać więcej niż 1 kontem Google Ads, korzystając z bezpośredniego dostępu do kont lub z konta menedżera Google Ads. Biblioteka klienta Java zawiera te przykłady kodu, które pokazują, jak sobie radzić z takimi przypadkami:

1. W GetAccountHierarchy przykładzie kodu pokazujemy, jak pobrać listę wszystkich kont na koncie menedżera Google Ads.
2. W ListAccessibleCustomers przykładzie kodu pokazujemy, jak pobrać listę wszystkich kont, do których użytkownik ma bezpośredni dostęp. Konta te mogą być następnie używane jako prawidłowe wartości ustawienia loginCustomerId.

Domyślne uwierzytelnianie aplikacji

Biblioteka klienta Java obsługuje też uwierzytelnianie za pomocą domyślnego uwierzytelniania aplikacji.

Jest to szczególnie przydatne w przypadku lokalnego tworzenia aplikacji lub tworzenia aplikacji korzystających z różnych interfejsów API Google, ponieważ możesz ponownie użyć tych samych danych logowania, o ile mają one dostęp do wymaganych zakresów OAuth 2.0.

W przypadku interfejsu Google Ads API upewnij się, że domyślne uwierzytelnianie aplikacji ma dostęp do https://www.googleapis.com/auth/adwordszakresu protokołu OAuth 2.0.

Aby użyć domyślnego uwierzytelniania aplikacji, ustaw opcję api.googleads.useApplicationDefaultCredentials w pliku ads.properties na true (lub wywołaj .enableApplicationDefaultCredentials() w GoogleAdsClient.newBuilder()). Jeśli używasz domyślnego uwierzytelniania aplikacji, nie należy ustawiać identyfikatora klienta, tajnego klucza klienta ani tokena odświeżania.