Uwierzytelnianie i autoryzacja

Podobnie jak inne interfejsy API Google, interfejs Google Ads API używa protokołu OAuth 2.0 do uwierzytelniania i autoryzacji. Protokół 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 do swojego konta Google Ads konto usługi. Aplikacja może następnie 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 (oraz opcjonalny element impersonated_email, jeśli używasz przekazywania dostępu 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 obiektu dict, dodaj tę parę klucz-wartość i wywołaj metodę load_from_dict, przekazując obiekt konfiguracji 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 bash te informacje:

    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 jest nieustawiona, a klucze danych logowania użytkownika OAuth (client_id, client_secret i refresh_token) są nieustawione lub zmienione w komentarz, biblioteka automatycznie autoryzuje za pomocą przepływu konta usługi.

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 narzędzie, takie jak gcloud CLI lub przykładowy kod generate_user_credentials, aby upoważnić Twoją aplikację do zarządzania wszystkimi jego kontami Google Ads w jego imieniu.

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

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

  1. Postępuj zgodnie z dokumentacją Generowanie danych uwierzytelniających, aby skonfigurować domyślne uwierzytelnianie aplikacji (ADC) w środowisku lokalnym.

  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 pliku 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 do konfiguracji lub środowiska bash te informacje:

    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 bezpośrednio obsługujesz tokeny OAuth

  1. Wykonaj czynności opisane w sekcji Konfigurowanie projektu konsoli i pobierz plik JSON zawierający identyfikator klienta i tajny klucz klienta projektu.

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

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

  3. Wykonaj 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 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 bash te informacje:

    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 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. Bibliotekę można zainicjować przy użyciu danych logowania użytkownika w następujący sposób, który zakłada, że aplikacja uzyskuje dane logowania w czasie działania, wykonując proces 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 pracy uwierzytelniania wielu użytkowników.

Uwierzytelnianie ręczne

Możesz wygenerować dane uwierzytelniające w dowolny sposób i przekazać je do GoogleAdsClient ręcznie, tworząc bezpośrednio instancję klasy klienta. Zakładając, ż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ż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 Python zawiera te przykłady kodu, które pokazują, jak obsługiwać takie przypadki:

  1. Przykładowy kod get_account_hierarchy pokazuje, jak pobrać listę wszystkich kont na koncie menedżera Google Ads.
  2. Przykładowy kod w języku list_accessible_customers pokazuje, jak pobrać listę wszystkich kont, do których użytkownik ma bezpośredni dostęp. Tych kont można następnie używać jako prawidłowych wartości ustawienia login_customer_id.