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 Google Ads API dostęp do konta Google Ads użytkownika bez konieczności obsługiwania i 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 przepływów OAuth 2.0 oraz jakie dane logowania są do tego potrzebne.
Aby dowiedzieć się więcej o modelu dostępu do interfejsu Google Ads API, przeczytaj przewodnik po modelu dostępu do Google Ads.
Dane logowania
Dostęp do interfejsu Google Ads API wymaga tokena programisty, danych logowania OAuth 2.0 oraz w niektórych przypadkach identyfikatora klienta logowania.
Token programisty
Token programisty jest powiązany z kontem menedżera i można go znaleźć w interfejsie internetowym Google Ads.
Chociaż token programisty jest powiązany z kontem menedżera, nie zapewnia dostępu do tego konta. Zamiast tego token programisty przyznaje dostęp do interfejsu API w ogóle, a dostęp na poziomie konta jest konfigurowany za pomocą OAuth 2.0.
W bibliotece klienta token programisty jest określony przez klucz api.googleads.developerToken w pliku ads.properties.
Dane logowania OAuth 2.0
Aby autoryzować użytkowników kont Google, którzy mają dostęp 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 przepływy:
- Przepływ konta usługi
- Przepływ uwierzytelniania pojedynczego użytkownika
- Przepływ uwierzytelniania wielu użytkowników
Szczegółowe informacje o przepływach OAuth w interfejsie Google Ads API znajdziesz w omówieniu OAuth. Aby uzyskać wymagane dane logowania, postępuj zgodnie z instrukcjami dotyczącymi przepływu, który najlepiej odpowiada Twoim potrzebom.
Identyfikator klienta logowania
Opcjonalnie możesz podać identyfikator klienta konta menedżera, który zapewnia dostęp do konta wyświetlania reklam. Musisz to zrobić, jeśli dostęp do konta klienta uzyskujesz 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 uzyskiwania uprawnień dostępu. Więcej informacji znajdziesz w powiązanej 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 koncentruje się na używaniu pliku ads.properties. 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 pracy z interfejsem Google Ads API używane są 3 typowe przepływy pracy.
Przepływ konta usługi
Jest to zalecany przepływ pracy, jeśli nie wymaga on interakcji z użytkownikiem. Ten przepływ pracy wymaga wykonania kroku konfiguracji, w którym 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 masz już plik JSON z kluczem prywatnym, dodaj do pliku ads.properties te informacje:
api.googleads.serviceAccountSecretsPath=PRIVATE_KEY_JSON_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
# Only add this key if you are using impersonation to access an account
# other than the service account itself.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE
Więcej informacji znajdziesz w przewodniku po przepływie konta usługi, aby dowiedzieć się więcej.
Przepływ uwierzytelniania pojedynczego 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 kroków konfiguracji:
- Przyznaj jednemu użytkownikowi dostęp do wszystkich kont, którymi chcesz zarządzać za pomocą interfejsu Google Ads API. Powszechnym rozwiązaniem jest przyznanie użytkownikowi dostępu do konta menedżera interfejsu Google Ads API i połączenie wszystkich kont Google Ads z tym kontem menedżera.
- Użytkownik uruchamia narzędzie wiersza poleceń, takie jak gcloud lub
GenerateUserCredentialsprzykładowy kod, aby autoryzować aplikację do zarządzania wszystkimi jego kontami Google Ads w jego imieniu.
Gdy masz już 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
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
Więcej informacji znajdziesz w przewodniku po przepływie uwierzytelniania pojedynczego użytkownika.
Przepływ uwierzytelniania wielu użytkowników
Jest to zalecany przepływ pracy, jeśli Twoja aplikacja umożliwia użytkownikom logowanie się i autoryzowanie aplikacji do zarządzania ich kontami Google Ads w ich imieniu. GenerateUserCredentials Możesz użyć tego przykładowego kodu jako odniesienia do tworzenia aplikacji na komputery, które wymagają uwierzytelniania użytkownika.
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
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
Więcej informacji znajdziesz w przewodniku po przepływie uwierzytelniania wielu użytkowników, aby dowiedzieć się więcej.
Co zrobić, jeśli użytkownik zarządza kilkoma 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 radzić sobie w takich przypadkach.
- Przykładowy kod GetAccountHierarchy pokazuje, jak pobrać listę wszystkich kont powiązanych z kontem menedżera Google Ads.
- Przykładowy kod ListAccessibleCustomers pokazuje
jak pobrać listę wszystkich kont, do których użytkownik ma bezpośredni dostęp.
Te konta mogą być 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 programowania lub programowania w różnych interfejsach API Google, ponieważ możesz ponownie użyć tych samych danych logowania, o ile mają one dostęp do odpowiednich zakresów OAuth 2.0.
W przypadku interfejsu Google Ads API upewnij się, że domyślne uwierzytelnianie aplikacji ma dostęp do zakresu OAuth 2.0 https://www.googleapis.com/auth/adwords.
Aby używać domyślnego uwierzytelniania aplikacji, ustaw w pliku ads.properties opcję api.googleads.useApplicationDefaultCredentials na true. Gdy używasz domyślnego uwierzytelniania aplikacji, nie należy ustawiać identyfikatora klienta, tajnego klucza klienta ani tokena odświeżania.