Konfiguracja

Bibliotekę klienta Python możesz skonfigurować za pomocą pliku YAML, zmiennych środowiskowych, ciągu YAML lub dict.

Konfiguracja uwierzytelniania

Istnieje kilka sposobów zarządzania danymi logowania OAuth potrzebnymi do uzyskania dostępu do interfejsu Google Ads API. Wybrana metoda wpływa na to, których pól konfiguracji używasz. Więcej informacji znajdziesz w przewodniku po uwierzytelnianiu.

Konfiguracja za pomocą pliku YAML

Możesz określić plik YAML, który będzie używany podczas inicjowania klienta i który zawiera niezbędne informacje do wysyłania żądań do interfejsu Google Ads API. Dostęp do tego pliku jest uzyskiwany, gdy klient jest inicjowany za pomocą metody load_from_storage. Najprostszym sposobem wygenerowania tego pliku jest skopiowanie przykładu google-ads.yaml z repozytorium GitHub i zmodyfikowanie go tak, aby zawierał Twoje dane logowania, w tym token odświeżania, identyfikator klienta i tajny klucz klienta.

Jeśli nie podasz ścieżki, biblioteka będzie szukać pliku w katalogu $HOME:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

Aby określić lokalizację pliku google-ads.yaml, możesz przekazać ścieżkę jako ciąg tekstowy do metody podczas jej wywoływania:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

Możesz też określić ścieżkę, definiując konkretną zmienną środowiskową:

import os
from google.ads.googleads.client import GoogleAdsClient

os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
client = GoogleAdsClient.load_from_storage()

Jeśli podano obie wartości – do metody przekazano ścieżkę i zmienna środowiskowa jest obecna – biblioteka traktuje priorytetowo ścieżkę przekazaną do metody.

Konfiguracja za pomocą zmiennych środowiskowych

Całą konfigurację klienta możesz przechowywać jako zmienne środowiskowe, które są odczytywane podczas korzystania z metody load_from_env klienta. Zmienne środowiskowe powinny mieć taką samą nazwę jak te zdefiniowane w pliku google-ads.yaml, ale muszą być pisane wielkimi literami i mieć prefiks przestrzeni nazw GOOGLE_ADS_. Na przykład client_id należy przechowywać jako GOOGLE_ADS_CLIENT_ID.

Zmienne środowiskowe są zwykle zdefiniowane w pliku konfiguracyjnym bash, takim jak plik .bashrc lub .bash_profile znajdujący się w katalogu $HOME. Można je też zdefiniować za pomocą wiersza poleceń.

Oto podstawowe kroki definiowania zmiennej środowiskowej za pomocą pliku .bashrc w terminalu:

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

Zmienne środowiskowe można też ustawić w instancji terminala bezpośrednio z wiersza poleceń:

export GOOGLE_ADS_CLIENT_ID=1234567890
echo $GOOGLE_ADS_CLIENT_ID

Metoda load_from_env wczytuje dane konfiguracyjne z atrybutu environ wbudowanego modułu os Pythona. Na przykład:os.environ["GOOGLE_ADS_CLIENT_ID"]

Oto przykład inicjowania instancji klienta z konfiguracją ze zmiennych środowiskowych:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

Aby skonfigurować logging za pomocą zmiennych środowiskowych, wartość konfiguracji musi być obiektem JSON, który pasuje do struktury kluczy YAML w przykładowym pliku konfiguracji google-ads.yaml.

Oto przykład, jak można to ustawić za pomocą pliku .bashrc:

export GOOGLE_ADS_LOGGING='{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "default_fmt": {
      "format": "[%(asctime)s - %(levelname)s] %(message).5000s",
      "datefmt": "%Y-%m-%d %H:%M:%S"
    }
  },
  "handlers": {
    "default_handler": {
      "class": "logging.StreamHandler",
      "formatter": "default_fmt"
    }
  },
  "loggers": {
    "": {
      "handlers": ["default_handler"],
      "level": "INFO"
    }
  }
}'

Ważne: jeśli zmienna środowiskowa GOOGLE_ADS_CONFIGURATION_FILE_PATH jest ustawiona podczas wywoływania metody load_from_env, wartości konfiguracji są pobierane z pliku google-ads.yaml znajdującego się w określonej ścieżce, a nie ze zmiennych środowiskowych opisanych wcześniej.

Konfigurowanie za pomocą ciągu YAML

Jeśli plik YAML został wczytany do pamięci, możesz go przekazać bezpośrednio do klienta podczas inicjowania. Aby to zrobić, użyj metody load_from_string:

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "r", encoding="utf-8") as handle:
    yaml_content = handle.read()

client = GoogleAdsClient.load_from_string(yaml_content)

Konfiguracja za pomocą dict

Możesz przekazać dict bezpośrednio do metody load_from_dict. Na przykład:

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "use_proto_plus": True,
}

client = GoogleAdsClient.load_from_dict(credentials)

Pola konfiguracji

Konfiguracja biblioteki klienta obsługuje te pola.

Uwierzytelnianie

Używaj tylko jednej z tych grup pól w zależności od stosowanego podejścia do uwierzytelniania:

  • Jeden użytkownik z domyślnymi danymi logowania aplikacji (dokumentacja)
    • use_application_default_credentials: czy biblioteka ma używać domyślnego uwierzytelniania aplikacji (ADC) do uwierzytelniania (obsługiwane w google-ads v28.3.0 i nowszych wersjach).
  • Jeden użytkownik z tokenami OAuth (dokumentacja).
    • client_id: Twój identyfikator klienta OAuth.
    • client_secret: tajny klucz klienta OAuth.
    • refresh_token: token odświeżania OAuth.
  • Konto usługi (dokumentacja)
    • json_key_file_path: ścieżka do lokalnego pliku klucza prywatnego. Jest on używany do uwierzytelniania za pomocą konta usługi.
    • impersonated_email: opcjonalny adres e-mail konta, które ma być używane jako tożsamość podczas korzystania z przekazywania uprawnień w całej domenie Google Workspace.

Działanie biblioteki

Te pola określają działanie biblioteki:

Konfiguracja na poziomie żądania

Zmienne środowiskowe

Aby skonfigurować bibliotekę za pomocą zmiennych środowiskowych, użyj tego kodu:

  • GOOGLE_ADS_ADS_ASSISTANT
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_ENDPOINT
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_IMPERSONATED_EMAIL
  • GOOGLE_ADS_JSON_KEY_FILE_PATH
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_USE_PROTO_PLUS
  • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS (obsługiwane w wersji v28.3.0 i nowszych)

Konfiguracja logu

Pola logu, czyli pola znajdujące się pod polem konfiguracji logging, są wyprowadzane bezpośrednio z logging.config wbudowanego modułu, ponieważ biblioteka przekazuje wszystkie pola w przestrzeni nazw logging bezpośrednio do metody logging.config.dictConfig. Szczegółowe informacje znajdziesz w przewodniku po rejestrowaniu.

  • version: liczba całkowita reprezentująca wersję schematu.
  • disable_existing_loggers: określa, czy rejestratory skonfigurowane w innych miejscach aplikacji mają być wyłączone.
  • formatters: słowniki definiujące różne rodzaje formatowania.
  • handlers: słowniki definiujące różne moduły obsługi, które określają, gdzie mają być zapisywane logi i które formaty mają być używane.
  • loggers: słowniki definiujące różne typy rejestratorów, które zawierają moduł obsługi i poziom logowania.