Konfiguracja

Bibliotekę klienta Python możesz skonfigurować za pomocą pliku YAML, zmiennych środowiskowych, ciągu YAML lub słownika 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. Zawiera on informacje niezbędne do wysyłania żądań do interfejsu Google Ads API. Dostęp do tego pliku jest uzyskiwany podczas inicjowania klienta za pomocą metody load_from_storage. Najłatwiej jest wygenerować ten plik, kopiując przykład google-ads.yaml z repozytorium GitHub i modyfikując 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 do metody podczas jej wywoływania:

from google.ads.googleads.client import GoogleAdsClient

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

Ścieżkę możesz też określić, 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 podasz obie wartości – ścieżkę przekazaną do metody i zmienną środowiskową – biblioteka będzie traktować priorytetowo ścieżkę przekazaną do metody.

Konfiguracja za pomocą zmiennych środowiskowych

Całą konfigurację klienta możesz zapisać 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 poprzedzone przestrzenią nazw GOOGLE_ADS_. Na przykład client_id należy zapisać jako GOOGLE_ADS_CLIENT_ID.

Zmienne środowiskowe są zwykle definiowane w pliku konfiguracji bash, np. .bashrc lub .bash_profile, znajdującym 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 w Pythonie. 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 odpowiada strukturze 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 podczas wywoływania metody load_from_env jest ustawiona zmienna środowiskowa GOOGLE_ADS_CONFIGURATION_FILE_PATH, 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.

Konfiguracja 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ą słownika dict

Możesz przekazać dict bezpośrednio do metody load_from_dict. 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

W zależności od używanej metody uwierzytelniania używaj tylko jednej z tych grup pól:

  • Użytkownik pojedynczy z domyślnymi danymi logowania aplikacji (dokumentacja)
    • use_application_default_credentials: czy biblioteka ma używać domyślnych danych logowania aplikacji (ADC) do uwierzytelniania (obsługiwane w google-ads v28.3.0 i nowszej).
  • Użytkownik pojedynczy z tokenami OAuth (dokumentacja)
    • client_id: 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. Służy do uwierzytelniania za pomocą konta usługi.
    • impersonated_email: opcjonalny adres e-mail konta, które ma być używane podczas delegowania 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 tych zmiennych:

  • 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 nowszej)

Konfiguracja logu

Pola logu, które są polami pod polem konfiguracji logging, są wyprowadzane bezpośrednio z wbudowanego modułu logging.config, ponieważ biblioteka przekazuje wszystkie pola w przestrzeni nazw logging bezpośrednio do logging.config.dictConfig metody. Szczegółowe informacje znajdziesz w przewodniku po logowaniu.

  • version: liczba całkowita reprezentująca wersję schematu.
  • disable_existing_loggers: czy wyłączyć rejestratory skonfigurowane w innej części aplikacji.
  • 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órych formatowania należy używać.
  • loggers: słowniki definiujące różne typy rejestratorów, które zawierają moduł obsługi i poziom logowania.