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

Poznawanie modelu dostępu do Google Ads

Aby skutecznie korzystać z interfejsu Google Ads API, musisz zrozumieć, jak działa model dostępu do Google Ads. Zalecamy przeczytanie przewodnika po modelu dostępu do Google Ads.

Przepływy OAuth

Podczas pracy z interfejsem Google Ads API używane są 3 typowe przepływy.

Przepływ konta usługi

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

Oto jak skonfigurować OAuth2 na potrzeby dostępu do interfejsu API za pomocą własnych danych logowania z kontem usługi w bibliotece klienta Perl:

1. Utwórz dane logowania OAuth2:

   Postępuj zgodnie z instrukcjami, aby wygenerować konto usługi i *.JSON plik.

2. Skonfiguruj bibliotekę klienta:

   W konfiguracji ustaw ścieżkę do klucza prywatnego JSON. Jeśli używasz pliku googleads.properties, dodaj te wiersze:

   jsonKeyFilePath=PRIVATE_KEY_FILE_PATH
   

   Jeśli używasz zmiennych środowiskowych, dodaj te wiersze do konfiguracji lub środowiska Bash:

   export GOOGLE_ADS_JSON_KEY_FILE_PATH=PRIVATE_KEY_FILE_PATH
   

   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 może być używany, jeśli nie możesz korzystać z kont usługi. Ten przepływ wymaga wykonania 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 generate_user_credentials.pl przykładowy kod aby autoryzować Twoją aplikację do zarządzania wszystkimi jego kontami Google Ads w jego imieniu.

Poniższe czynności uruchamiają interaktywny przykładowy kod, który wymaga podania danych.

1. W terminalu uruchom przykład w katalogu.generate_user_credentials.plexamples Przed uruchomieniem możesz zmodyfikować wartości INSERT_XXX_HERE w przykładzie lub użyć argumentów wiersza poleceń -client_id dla identyfikatora klienta i -client_secret dla tajnego klucza klienta.

   perl generate_user_credentials.pl -client_id {client_id} -client_secret {client_secret}
   

2. Ten przykładowy kod wyświetli prośbę o odwiedzenie adresu URL, pod którym musisz autoryzować aplikację do uzyskiwania dostępu do Twojego konta Google Ads w Twoim imieniu.

   Paste this url in your browser:
   https://accounts.google.com/o/oauth2/v2/auth?response_type=code&access_type=offline&client_id=...
   

   Otwórz adres URL w sesji przeglądarki w trybie przeglądania prywatnego lub w oknie incognito. Zaloguj się na konto Google, którego używasz do uzyskiwania dostępu do Google Ads. Zwykle jest to konto e-mail, które ma dostęp do konta menedżera Google Ads zawierającego wszystkie konta, którymi chcesz zarządzać w jego hierarchii. Na ekranie zgody OAuth 2.0 kliknij Dalej.

   

   Przekierujemy Cię na stronę z komunikatem informującym o tym, że autoryzacja się powiodła.

   Authorization code was successfully retrieved.
   

3. Wróć do konsoli, w której uruchamiasz przykładowy kod. Zobaczysz, że przykładowy kod został ukończony i wyświetla token odświeżania oraz instrukcje, a także instrukcje, które musisz wykonać, aby skonfigurować bibliotekę klienta:

   Replace the following keys and values in your googleads.properties configuration file:
   
   clientId==***********************apps.googleusercontent.com
   clientSecret=****
   refreshToken=****
   

4. Naciśnij Ctrl + C, aby zakończyć proces. Następnie skopiuj wygenerowany token odświeżania wraz z identyfikatorem klienta i tajnym kluczem klienta do pliku googleads.properties lub zapisz go w innym miejscu, aby użyć go podczas tworzenia instancji biblioteki w czasie działania.

Bibliotekę można zainicjować za pomocą danych logowania OAuth 2.0 użytkownika, ustawiając w pliku googleads.properties te wartości:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
developerToken=DEVELOPER_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

Możesz też użyć zmiennych środowiskowych:

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_DEVELOPER_TOKEN=DEVELOPER_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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, jeśli Twoja aplikacja umożliwia użytkownikom logowanie się i autoryzowanie aplikacji do zarządzania ich kontami Google Ads w ich imieniu. Twoja aplikacja tworzy dane logowania OAuth 2.0 użytkownika i zarządza nimi.

W przypadku Perla zwykle implementujesz przepływ aplikacji internetowej, w którym aplikacja obsługuje przekierowanie OAuth 2.0 i zarządzanie tokenami. Użytkownik uwierzytelnia się w Twojej aplikacji, a Twoja aplikacja przechowuje i używa tokena odświeżania użytkownika do wykonywania wywołań interfejsu API w jego imieniu.

Konfiguracja używania uzyskanych danych logowania jest taka sama jak w przypadku przepływu uwierzytelniania pojedynczego użytkownika:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
developerToken=DEVELOPER_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

Możesz też użyć zmiennych środowiskowych:

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_DEVELOPER_TOKEN=DEVELOPER_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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 – bezpośrednio lub za pomocą konta menedżera Google Ads. Biblioteka klienta Perl zawiera przykłady ilustrujące, jak sobie radzić w takich przypadkach.

1. Przykład get_account_hierarchy.pl pokazuje jak pobrać listę wszystkich kont powiązanych z kontem menedżera Google Ads.
2. Przykład list_accessible_customers.pl pokazuje, jak pobrać listę wszystkich kont, do których użytkownik ma bezpośredni dostęp. Te konta można następnie używać jako prawidłowych wartości ustawienia LoginCustomerId w pliku googleads.properties lub zmiennej środowiskowej GOOGLE_ADS_LOGIN_CUSTOMER_ID.