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.

Poznaj 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ż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 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, 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, opcja use_application_default_credentials ma wartość False lub nie jest ustawiona, a klucze danych logowania użytkownika protokołu OAuth (client_id, client_secret i refresh_token) są nieustawione lub zmienione w komentarz, biblioteka automatycznie autoryzuje się za pomocą przepływu konta usługi.

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 pracy może być używany, jeśli nie możesz korzystać z kont usług. Ten przepływ pracy wymaga 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 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_credentials przykładowy kod w celu autoryzowania Twojej aplikacji do zarządzania wszystkimi jego 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)

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

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_application_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_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 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 zostanie wyświetlony token odświeżania. Skopiuj go i zapisz na potrzeby następnego kroku.

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 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 użytkownika OAuth 2.0 i zarządza nimi. Bibliotekę można zainicjować za pomocą danych logowania użytkownika w ten sposób. Zakładamy, że Twoja 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, aby dowiedzieć się więcej.

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 przez Ciebie 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,
    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 obsługiwać takie przypadki:

1. Przykład kodu get_account_hierarchy pokazuje, jak pobrać listę wszystkich kont podrzędnych konta 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.