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 jego danych logowania.

Model dostępu do Google Ads

Aby skutecznie korzystać z interfejsu Google Ads API, musisz wiedzieć, jak działa model dostępu do Google Ads. Zapoznaj się z przewodnikiem po modelu dostępu do Google Ads.

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.

Aby skonfigurować protokół OAuth2 na potrzeby dostępu do interfejsu API przy użyciu własnych danych logowania i konta usługi w bibliotece klienta Perl:

  1. Utwórz dane uwierzytelniające OAuth2:

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

  2. Skonfiguruj bibliotekę klienta:

    Ustaw w konfiguracji ścieżkę JSON klucza prywatnego (i opcjonalnie impersonatedEmail, jeśli używasz przekazywania dostępu w całej domenie Google Workspace). Jeśli używasz pliku googleads.properties, dodaj te informacje:

    jsonKeyFilePath=PRIVATE_KEY_FILE_PATH
# Optional unless using Google Workspace domain-wide delegation:
impersonatedEmail=IMPERSONATED_EMAIL
loginCustomerId=LOGIN_CUSTOMER_ID

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

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=\
IMPERSONATED_EMAIL
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

    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:

  1. 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 kont Google Ads z tym kontem menedżera.
  2. Użytkownik uruchamia przykładowy kod generate_user_credentials.pl, aby upoważnić Twoją aplikację do zarządzania wszystkimi jego kontami Google Ads w jego imieniu.

Poniższe kroki uruchamiają interaktywny przykład kodu, który wymaga podania danych wejściowych.

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

    perl generate_user_credentials.pl \
  -client_id OAUTH_CLIENT_ID \
  -client_secret OAUTH_CLIENT_SECRET

  2. Ten przykładowy kod prosi o odwiedzenie adresu URL, pod którym musisz upoważnić aplikację do uzyskiwania dostępu do 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...

    Otwórz adres URL w sesji 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 ramach hierarchii kont. Na ekranie zgody OAuth 2.0 kliknij Dalej.

    Ekran zgody OAuth 2.0

    Nastąpi przekierowanie na stronę z komunikatem o pomyślnej autoryzacji.

    Authorization code was successfully retrieved.

  3. Wróć do konsoli, w której uruchamiasz przykładowy kod. Zobaczysz, że przykładowy kod został wykonany i wyświetla token odświeżania oraz instrukcje, a następnie 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ć przy użyciu danych uwierzytelniających OAuth 2.0 użytkownika, ustawiając te wartości w pliku googleads.properties:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_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_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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. Aplikacja tworzy dane uwierzytelniające użytkownika OAuth 2.0 i nimi zarządza.

W przypadku Perla zwykle implementuje się 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 aplikacja przechowuje i wykorzystuje token odświeżania użytkownika do wywoływania interfejsu API w jego imieniu.

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

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_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_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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ż jednym kontem Google Ads, korzystając z bezpośredniego dostępu do kont lub z konta menedżera Google Ads. Biblioteka klienta Perl zawiera przykłady pokazujące, jak postępować w takich przypadkach:

  1. Przykład get_account_hierarchy.pl pokazuje, jak pobrać listę wszystkich kont na koncie 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 mogą być następnie używane jako prawidłowe wartości ustawienia loginCustomerId w pliku googleads.properties lub zmiennej środowiskowej GOOGLE_ADS_LOGIN_CUSTOMER_ID.