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.

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 korzystania z interfejsu Google Ads API stosuje się 3 typy 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 te elementy, aby ustawić ścieżkę do pliku JSON klucza prywatnego w środowisku lokalnym (wraz z opcjonalnym parametrem impersonated_email, jeśli używasz delegowania w całej domenie):

  json_key_file_path: JSON_KEY_FILE_PATH
  # Optional: only set if using Google Workspace domain-wide delegation:
  # impersonated_email: IMPERSONATED_EMAIL
  

  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 klucz i tę wartość oraz 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 opcja konfiguracji json_key_file_path jest obecna w którejkolwiek z tych metod konfiguracji, opcja use_application_default_credentials ma wartość False lub nie jest ustawiona, a klucze danych logowania użytkownika OAuth (client_id, client_secret i refresh_token) nie są ustawione lub są zakomentowane, 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ługi. Ten przepływ pracy wymaga 2 etapów konfiguracji:

1. Udzielić jednemu użytkownikowi dostępu do wszystkich kont, którymi ma zarządzać za pomocą interfejsu Google Ads API. Często stosowanym 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, np. gcloud CLI lub generate_user_credentials przykładowy kod, aby autoryzować Twoją 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)

Uwaga: uwierzytelnianie za pomocą use_application_default_credentials wymaga google-ads v28.3.0 lub nowszej wersji.

1. Aby skonfigurować domyślne uwierzytelnianie 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_application_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_APPLICATION_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 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 te ustawienia do wybranej konfiguracji:

   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 skonfigurowania 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ć przy użyciu 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 umożliwia uzyskiwanie danych logowania w czasie działania programu:

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, bezpośrednio tworząc 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,
    use_proto_plus=True,
)

Zarządzanie wieloma kontami

Użytkownik może zarządzać 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 przypadkach:

1. get_account_hierarchy Przykład kodu pokazuje, jak pobrać listę wszystkich kont na koncie 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. Konta te mogą być następnie używane jako prawidłowe wartości ustawienia login_customer_id.