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

Omówienie 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 zapoznanie się z przewodnikiem po modelu dostępu do Google Ads.

Przepływy pracy OAuth

Podczas korzystania z interfejsu 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. Biblioteka Pythona jest skonfigurowana w ten sposób:

  • Jeśli używasz pliku google-ads.yaml lub ciągu YAML, dodaj do konfiguracji to polecenie, aby ustawić ścieżkę do pliku JSON klucza prywatnego 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, uwzględnij ten 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 do konfiguracji lub środowiska te wartości: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 w którejkolwiek z tych metod konfiguracji występuje opcja konfiguracji json_key_file_path, a opcja use_application_default_credentials jest ustawiona na 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 na koncie usługi.

Proces uwierzytelniania jednego 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, np. gcloud CLI lub generate_user_credentials przykładowy kod, aby autoryzować aplikację do zarządzania w jego imieniu wszystkimi kontami Google Ads.

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

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

    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, uwzględnij 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 do konfiguracji lub środowiska te wartości: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 pobierz plik JSON zawierający identyfikator klienta i klucz tajny klienta projektu.

  2. Skopiuj bibliotekę klienta Python na 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 potrzeby następnego kroku.

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

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

    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 konfigurowania biblioteki używasz dict, uwzględnij 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 do konfiguracji lub środowiska te wartości: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 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. Aplikacja tworzy dane logowania użytkownika OAuth 2.0 i nimi zarządza. 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 proces autoryzacji lub wczytując je z pamięci danych):

dict to najprostszy mechanizm konfiguracji, który można zastosować podczas uzyskiwania 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 pracy uwierzytelniania wielu użytkowników.

Uwierzytelnianie ręczne

Dane logowania możesz wygenerować dowolną metodą i przekazać je do GoogleAdsClient ręcznie, tworząc bezpośrednio instancję klasy klienta. Załóżmy, że utworzony obiekt danych logowania jest instancją google.auth.credentials.Credentials. Możesz go przekazać 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 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 Python zawiera te przykłady kodu, które pokazują, jak sobie radzić w takich sytuacjach.

  1. W get_account_hierarchyprzykładzie kodu pokazujemy, jak pobrać listę wszystkich kont powiązanych z kontem menedżera Google Ads.
  2. W przykładzie kodu list_accessible_customers pokazujemy, 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 login_customer_id.