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.

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 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. Biblioteka Python jest skonfigurowana w ten sposób:

  • Jeśli używasz pliku google-ads.yaml lub ciągu YAML, dodaj do konfiguracji te informacje, aby ustawić ścieżkę do pliku JSON z kluczem prywatnym w środowisku lokalnym:

    json_key_file_path: JSON_KEY_FILE_PATH

    Następnie wywołaj metody load_from_storage lub load_from_string:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

  • Jeśli do skonfigurowania biblioteki używasz dict, dodaj tę parę klucz-wartość i wywołaj metodę load_from_dict, przekazując konfigurację dict:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "json_key_file_path": JSON_KEY_FILE_PATH
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

    Następnie wywołaj metodę load_from_env:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()
  ```

Jeśli opcja konfiguracji json_key_file_path jest obecna w którejkolwiek z tych metod konfiguracji, a opcja use_application_default_credentials ma wartość False lub nie jest ustawiona, biblioteka automatycznie autoryzuje się za pomocą przepływu konta usługi.

Więcej informacji znajdziesz w przewodniku po przepływie pracy konta usługi.

Przepływ 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 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 narzędzie, takie jak gcloud CLI lub generate_user_credentialsprzykładowy kod aby autoryzować aplikację do zarządzania wszystkimi swoimi kontami Google Ads w jego imieniu.

Bibliotekę można zainicjować za pomocą danych logowania OAuth 2.0 użytkownika w ten sposób:

Jeśli używasz narzędzia gcloud CLI (zalecane)

  1. Aby skonfigurować domyślne dane logowania aplikacji (ADC) w środowisku lokalnym, postępuj zgodnie z instrukcjami w dokumentacji dotyczącej generowania danych logowania.

  2. Dodaj tę konfigurację do pliku google-ads.yaml lub ciągu YAML:

    use_application_default_credentials: true

    Następnie wywołaj metodę load_from_storage lub load_from_string:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    Jeśli do skonfigurowania biblioteki używasz dict, dodaj tę parę klucz-wartość i wywołaj metodę load_from_dict:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "use_account_default_credentials": True
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

    export GOOGLE_ADS_USE_ACCOUNT_DEFAULT_CREDENTIALS=true

    Następnie wywołaj metodę load_from_env:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

Jeśli obsługujesz tokeny OAuth bezpośrednio

  1. Wykonaj czynności, aby skonfigurować projekt w konsoli i pobrać plik JSON zawierający identyfikator klienta i tajny klucz klienta projektu.

  2. Sklonuj bibliotekę klienta Python na swój komputer i przejdź do jej katalogu:

    $ git clone https://github.com/googleads/google-ads-python.git
$ cd google-ads-python

  3. Uruchom przykład, podając ścieżkę bezwzględną do pliku JSON pobranego w kroku 1:

    $ python examples/authentication/generate_user_credentials.py -c PATH_TO_CREDENTIALS_JSON

    Po zakończeniu w konsoli pojawi się token odświeżania. Skopiuj go i zapisz na następny krok.

  4. Skonfiguruj bibliotekę, dodając te ustawienia do wybranej konfiguracji:

    Dodaj tę konfigurację do pliku google-ads.yaml lub ciągu YAML:

    client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE

    Następnie wywołaj metodę load_from_storage lub load_from_string:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    Jeśli do skonfigurowania biblioteki używasz dict, dodaj te pary klucz-wartość i wywołaj metodę load_from_dict:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": INSERT_OAUTH2_CLIENT_ID_HERE
  "client_secret": INSERT_OAUTH2_CLIENT_SECRET_HERE
  "refresh_token": INSERT_REFRESH_TOKEN_HERE
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

    export GOOGLE_ADS_CLIENT_ID=INSERT_OAUTH2_CLIENT_ID_HERE
export GOOGLE_ADS_CLIENT_SECRET=INSERT_OAUTH2_CLIENT_SECRET_HERE
export GOOGLE_ADS_REFRESH_TOKEN=INSERT_REFRESH_TOKEN_HERE

    Następnie wywołaj metodę load_from_env:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

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 ich kontami Google Ads w ich imieniu. Aplikacja tworzy dane logowania OAuth 2.0 użytkownika i zarządza nimi. Bibliotekę można zainicjować za pomocą danych logowania użytkownika w ten sposób. Zakładamy, że aplikacja uzyskuje dane logowania w czasie działania, wykonując przepływ autoryzacji lub wczytując je z magazynu danych:

dict to najprostszy mechanizm konfiguracji, którego można użyć do uzyskania danych logowania w czasie działania:

from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": client_id
  "client_secret": client_secret
  "refresh_token": refresh_token
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

Więcej informacji znajdziesz w przewodniku po przepływie uwierzytelniania wielu użytkowników.

Uwierzytelnianie ręczne

Dane logowania możesz wygenerować dowolną metodą i ręcznie przekazać je do GoogleAdsClient, bezpośrednio tworząc instancję klasy klienta. Zakładając, że utworzony obiekt danych logowania jest instancją google.auth.credentials.Credentials, możesz przekazać go w ten sposób:

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`
credentials = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
  credentials=credentials,
  # ... insert remaining parameters
)

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

  1. Przykład kodu get_account_hierarchy pokazuje jak pobrać listę wszystkich kont powiązanych z kontem menedżera Google Ads.
  2. Przykład kodu list_accessible_customers 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 login_customer_id.