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 ani przechowywania informacji logowania użytkownika.

Ten przewodnik zawiera informacje o konfigurowaniu biblioteki klienta Java na potrzeby uwierzytelniania w Google Ads API za pomocą 3 najpopularniejszych procesów OAuth 2.0 oraz wyjaśnienie, jakie dane logowania są potrzebne.

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 tokena programisty, danych logowania OAuth 2.0 i w niektórych przypadkach identyfikatora klienta logowania.

Token programisty

Token programisty jest połączony z kontem menedżera i można go znaleźć w interfejsie internetowym Google Ads.

Token programisty jest powiązany z kontem menedżera, ale nie zapewnia dostępu do tego konta. 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ślany przez klucz api.googleads.developerToken w pliku ads.properties.

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 pojedynczego użytkownika
• Proces uwierzytelniania wielu użytkowników

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

Identyfikator klienta logowania

Opcjonalnie podaj identyfikator klienta konta menedżera, które ma dostęp do konta wyświetlania reklam. 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 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ą ads.properties pliku, zmiennych środowiskowych lub programowo. W tym przewodniku skupimy się na korzystaniu z 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 stosuje się 3 typy typowych procesów.

Proces konta usługi

Jest to zalecany przepływ pracy, jeśli nie wymaga on interakcji z użytkownikiem. Ten proces 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=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 pracy na koncie usługi.

Proces uwierzytelniania pojedynczego użytkownika

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

1. Przyznaj jednemu użytkownikowi dostęp do wszystkich kont, którymi chcesz zarządzać za pomocą interfejsu Google Ads API. Często stosowanym rozwiązaniem jest przyznanie użytkownikowi dostępu do konta menedżera Google Ads API i połączenie wszystkich kont Google Ads z tym kontem menedżera.
2. Użytkownik uruchamia narzędzie wiersza poleceń, np. gcloud lub GenerateUserCredentials przykładowy kod, 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
api.googleads.developerToken=INSERT_DEVELOPER_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. GenerateUserCredentials to przykład kodu wiersza poleceń, który 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żesz wykorzystać jako punkt odniesienia do tworzenia aplikacji na komputery, które wymagają uwierzytelnienia 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 pracy uwierzytelniania wielu użytkowników.

Co zrobić, jeśli użytkownik zarządza wieloma kontami?

Użytkownicy często zarządzają 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ć w takich sytuacjach.

1. Przykład kodu GetAccountHierarchy pokazuje, jak pobrać listę wszystkich kont powiązanych z kontem menedżera Google Ads.
2. Przykład kodu ListAccessibleCustomers pokazuje, jak pobrać listę wszystkich kont, do których użytkownik ma bezpośredni dostęp. Te konta mogą być następnie używane jako prawidłowe wartości ustawienia LoginCustomerId.

Domyślne dane logowania aplikacji

Biblioteka klienta Java obsługuje też uwierzytelnianie za pomocą domyślnych danych logowania 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 odpowiednich zakresów OAuth 2.0.

W przypadku interfejsu Google Ads API upewnij się, że domyślne dane logowania aplikacji mają dostęp do zakresu OAuth 2.0https://www.googleapis.com/auth/adwords.

Aby używać domyślnego uwierzytelniania aplikacji, ustaw opcję api.googleads.useApplicationDefaultCredentials na true w pliku ads.properties. Jeśli używasz domyślnych danych logowania aplikacji, nie należy ustawiać identyfikatora klienta, tajnego klucza klienta ani tokena odświeżania.