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 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ą wymagane.

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 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. Wymagany typ 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óre 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ślany 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
# 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:

1. 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.
2. Użytkownik uruchamia narzędzie wiersza poleceń, takie jak gcloud CLI, lub GenerateUserCredentials przykładowy kod, aby autoryzować aplikację do zarządzania w jego imieniu wszystkimi kontami Google Ads.

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

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 aplikacja umożliwia użytkownikom logowanie się i autoryzowanie aplikacji do zarządzania w ich imieniu kontami Google Ads. GenerateUserCredentials to przykładowy kod wiersza poleceń , który pokazuje, jak uzyskać uwierzytelnianie użytkownika w czasie działania programu, aby zarządzać w jego imieniu kontami Google Ads. 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

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 za pomocą konta menedżera Google Ads. Biblioteka klienta Java zawiera te przykłady kodu, które pokazują, jak obsługiwać takie przypadki.

1. Przykładowy kod GetAccountHierarchy pokazuje, jak pobrać listę wszystkich kont powiązanych z kontem menedżera Google Ads.
2. 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 credentials.

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.