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 i przechowywania jego danych logowania.
Z tego przewodnika dowiesz się, jak skonfigurować bibliotekę klienta Java na potrzeby uwierzytelniania w interfejsie Google Ads API za pomocą 3 najczęstszych przepływów OAuth 2.0. Znajdziesz tu też wyjaśnienie wymaganych danych uwierzytelniających.
Więcej informacji o modelu dostępu do interfejsu Google Ads API znajdziesz w szczegółowym omówieniu 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 uwierzytelniających OAuth 2.0. Typ wymaganych danych uwierzytelniających zależy od używanego przepływu OAuth 2.0.
Biblioteka obsługuje 3 procesy:
- Przepływ konta usługi
- Proces uwierzytelniania jednego użytkownika
- Proces uwierzytelniania wielu użytkowników
Szczegółowe informacje o procesach OAuth w interfejsie Google Ads API znajdziesz w omówieniu protokołu OAuth. Aby uzyskać wymagane dane logowania, postępuj zgodnie z instrukcjami dotyczącymi procesu, który najlepiej odpowiada Twoim potrzebom.
Identyfikator klienta używany do logowania
Opcjonalnie możesz podać identyfikator klienta konta menedżera, które ma dostęp do konta wyświetlania reklam. Musisz go podać, jeśli masz dostęp do konta klienta przez konto menedżera. Nie musisz podawać wszystkich kont menedżera na ścieżce do identyfikatora klienta, tylko identyfikator najwyższego menedżera, którego używasz do uprawnień dostępu. Więcej informacji znajdziesz w powiązanej dokumentacji.
W bibliotece klienta identyfikator klienta, który się loguje, 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. W tym przewodniku skupiamy się na użyciu 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żywa się 3 typowych procesów.
Przepływ konta usługi
Jest to zalecany przepływ pracy, jeśli nie wymaga on interakcji z człowiekiem. Ten proces 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 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
Możesz użyć tego przepływu pracy, jeśli nie możesz korzystać z kont usługi. Ten przepływ pracy wymaga 2 czynności konfiguracyjnych:
- Przyznaj jednemu użytkownikowi dostęp do wszystkich kont, którymi chcesz zarządzać za pomocą interfejsu Google Ads API. Często stosowanym podejściem 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.
- Użytkownik uruchamia narzędzie wiersza poleceń, takie jak
gcloudCLI lub przykładowy kodGenerateUserCredentials, aby upoważnić Twoją aplikację do zarządzania w jego imieniu wszystkimi jego kontami Google Ads.
Gdy będziesz mieć 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 procesie 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 aplikacji do zarządzania 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, aby zarządzać jego kontami Google Ads w jego imieniu. Możesz użyć tego przykładowego kodu jako odniesienia do tworzenia aplikacji komputerowych lub internetowych, które wymagają uwierzytelniania użytkownika.
W przypadku aplikacji dla wielu użytkowników przechowuj identyfikator klienta OAuth 2.0 i tajny klucz klienta w pliku ads.properties (lub innym magazynie konfiguracji), a token odświeżania każdego użytkownika przechowuj bezpiecznie w bazie danych aplikacji i przekazuj go automatycznie w czasie działania podczas tworzenia obiektów 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żytkownicy często zarządzają więcej niż jednym 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 obsługiwać takie przypadki:
- Przykładowy kod
GetAccountHierarchypokazuje, jak pobrać listę wszystkich kont na koncie menedżera Google Ads. - Przykładowy kod
ListAccessibleCustomerspokazuje, jak pobrać listę wszystkich kont, do których użytkownik ma bezpośredni dostęp. Tych kont można następnie używać jako prawidłowych wartości ustawienialoginCustomerId.
Domyślne uwierzytelnianie aplikacji
Biblioteka klienta Java obsługuje też uwierzytelnianie za pomocą domyślnego uwierzytelniania aplikacji.
Jest to szczególnie przydatne w przypadku programowania lokalnego lub programowania z użyciem różnych interfejsów API Google, ponieważ możesz ponownie używać 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 zakresu OAuth 2.0 https://www.googleapis.com/auth/adwords.
Aby używać domyślnego uwierzytelniania aplikacji, ustaw opcję api.googleads.useApplicationDefaultCredentials na true w pliku ads.properties (lub wywołaj .enableApplicationDefaultCredentials() na GoogleAdsClient.newBuilder()). Jeśli używasz domyślnego uwierzytelniania aplikacji, nie ustawiaj identyfikatora klienta, klucza klienta ani tokena odświeżania.