การกำหนดค่า

คุณสามารถกำหนดค่าไลบรารีของไคลเอ็นต์ Python ได้โดยใช้ไฟล์ YAML, ตัวแปรสภาพแวดล้อม, สตริง YAML หรือ dict

การกำหนดค่าการตรวจสอบสิทธิ์

คุณจัดการข้อมูลเข้าสู่ระบบ OAuth ที่จำเป็นในการเข้าถึง Google Ads API ได้หลายวิธี แนวทางที่คุณเลือกจะส่งผลต่อฟิลด์กำหนดค่าที่คุณใช้ ดูข้อมูลเพิ่มเติมได้ในคู่มือการตรวจสอบสิทธิ์

การกำหนดค่าโดยใช้ไฟล์ YAML

คุณสามารถระบุไฟล์ YAML ที่จะใช้เมื่อเริ่มต้นไคลเอ็นต์ซึ่งมีข้อมูลที่จำเป็นในการส่งคำขอไปยัง Google Ads API ระบบจะเข้าถึงไฟล์นี้เมื่อเริ่มต้นไคลเอ็นต์โดยใช้วิธี load_from_storage วิธีที่ง่ายที่สุดในการสร้างไฟล์นี้คือคัดลอกตัวอย่าง google-ads.yamlจากที่เก็บ GitHub แล้วแก้ไข ให้มีข้อมูลเข้าสู่ระบบของคุณ ซึ่งรวมถึงโทเค็นการรีเฟรช, รหัสไคลเอ็นต์ และ รหัสลับไคลเอ็นต์

หากคุณไม่ระบุเส้นทาง ไลบรารีจะค้นหาไฟล์ในไดเรกทอรี $HOME ดังนี้

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

หากต้องการระบุตำแหน่งที่ไฟล์ google-ads.yaml อยู่ คุณสามารถส่งเส้นทางเป็นสตริงไปยังเมธอดเมื่อเรียกใช้ได้ดังนี้

from google.ads.googleads.client import GoogleAdsClient

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

นอกจากนี้ คุณยังระบุเส้นทางได้โดยกำหนดตัวแปรสภาพแวดล้อมที่เฉพาะเจาะจงดังนี้

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()

หากมีการระบุทั้ง 2 ค่า (ส่งเส้นทางไปยังเมธอดและมีตัวแปรสภาพแวดล้อม) ไลบรารีจะให้ความสำคัญกับเส้นทางที่ส่งไปยังเมธอด

การกำหนดค่าโดยใช้ตัวแปรสภาพแวดล้อม

คุณสามารถจัดเก็บการกำหนดค่าไคลเอ็นต์ทั้งหมดเป็นตัวแปรสภาพแวดล้อม ซึ่งระบบจะอ่านเมื่อใช้เมธอด load_from_env ของไคลเอ็นต์ ตัวแปรสภาพแวดล้อมควรมีชื่อเดียวกับที่กำหนดไว้ในไฟล์ google-ads.yaml แต่ต้องเป็นตัวพิมพ์ใหญ่ทั้งหมดและมีคำนำหน้าเป็นเนมสเปซ GOOGLE_ADS_ เช่น client_id ควรจัดเก็บเป็น GOOGLE_ADS_CLIENT_ID

โดยปกติแล้วตัวแปรสภาพแวดล้อมจะกำหนดไว้ในไฟล์การกำหนดค่า Bash เช่น ไฟล์ .bashrc หรือ .bash_profile ที่อยู่ในไดเรกทอรี $HOME นอกจากนี้ยังกำหนดได้โดยใช้บรรทัดคำสั่ง

ต่อไปนี้เป็นขั้นตอนพื้นฐานในการกำหนดตัวแปรสภาพแวดล้อมโดยใช้ไฟล์ .bashrc ในเทอร์มินัล

# 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

นอกจากนี้ คุณยังตั้งค่าตัวแปรสภาพแวดล้อมในอินสแตนซ์เทอร์มินัลได้โดยตรงจากบรรทัดคำสั่งดังนี้

export GOOGLE_ADS_CLIENT_ID=1234567890
echo $GOOGLE_ADS_CLIENT_ID

เมธอด load_from_env จะโหลดข้อมูลการกำหนดค่าจากแอตทริบิวต์ environ ในโมดูล os ที่มากับระบบของ Python เช่น: os.environ["GOOGLE_ADS_CLIENT_ID"]

ต่อไปนี้เป็นตัวอย่างวิธีเริ่มต้นอินสแตนซ์ไคลเอ็นต์ด้วยการกำหนดค่าจากตัวแปรสภาพแวดล้อม

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

หากต้องการกำหนดค่า logging ผ่านตัวแปรสภาพแวดล้อม ค่าการกำหนดค่า ต้องเป็นออบเจ็กต์ JSON ที่ตรงกับโครงสร้างของคีย์ YAML ใน ไฟล์การกำหนดค่า google-ads.yaml ตัวอย่าง

ต่อไปนี้เป็นตัวอย่างวิธีตั้งค่านี้โดยใช้ไฟล์ .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"
    }
  }
}'

ประเด็นสำคัญ: หากมีการตั้งค่าตัวแปรสภาพแวดล้อม GOOGLE_ADS_CONFIGURATION_FILE_PATH เมื่อมีการเรียกใช้เมธอด load_from_env ระบบจะดึงค่าการกำหนดค่าจากไฟล์ google-ads.yaml ที่อยู่ในเส้นทางที่ระบุ ไม่ใช่จากตัวแปรสภาพแวดล้อมที่อธิบายไว้ก่อนหน้านี้

การกำหนดค่าโดยใช้สตริง YAML

หากคุณอ่านไฟล์ YAML ลงในหน่วยความจำแล้ว คุณสามารถระบุไฟล์ดังกล่าวให้กับไคลเอ็นต์ได้โดยตรงเมื่อเริ่มต้น โดยใช้เมธอด 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)

การกำหนดค่าโดยใช้ dict

คุณสามารถส่ง dict ไปยังเมธอด load_from_dict ได้โดยตรงดังนี้ เช่น

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)

ฟิลด์กำหนดค่า

การกำหนดค่าไลบรารีของไคลเอ็นต์รองรับช่องต่อไปนี้

การตรวจสอบสิทธิ์

ใช้กลุ่มช่องใดช่องหนึ่งต่อไปนี้เท่านั้น ทั้งนี้ขึ้นอยู่กับแนวทางการตรวจสอบสิทธิ์ที่คุณใช้

  • ผู้ใช้รายเดียวที่มีข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชัน (เอกสารประกอบ)
    • use_application_default_credentials: ระบุว่าไลบรารีควรใช้ข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชัน (ADC) สำหรับการตรวจสอบสิทธิ์หรือไม่ (รองรับใน google-ads v28.3.0 ขึ้นไป)
  • ผู้ใช้รายเดียวที่มีโทเค็น OAuth (เอกสารประกอบ)
    • client_id: รหัสไคลเอ็นต์ OAuth
    • client_secret: รหัสลับไคลเอ็นต์ OAuth
    • refresh_token: โทเค็นการรีเฟรช OAuth ของคุณ
  • บัญชีบริการ (เอกสารประกอบ)
    • json_key_file_path: เส้นทางไปยังไฟล์คีย์ส่วนตัวในเครื่อง ซึ่งใช้สำหรับการตรวจสอบสิทธิ์โดยใช้บัญชีบริการ
    • impersonated_email: อีเมลของบัญชีที่จะนำข้อมูลมาใช้แทน (ไม่บังคับ) เมื่อใช้การมอบสิทธิ์ทั่วทั้งโดเมนของ Google Workspace

ลักษณะการทำงานของไลบรารี

ช่องต่อไปนี้จะกำหนดลักษณะการทำงานของไลบรารี

การกำหนดค่าระดับคำขอ

  • linked_customer_id: ดูเอกสารประกอบเกี่ยวกับ linked-customer-id
  • login_customer_id: ดูเอกสารประกอบเกี่ยวกับ login-customer-id
  • endpoint: ที่อยู่ปลายทาง Google Ads API ทางเลือก (ไม่บังคับ)
  • ads_assistant: ตัวระบุส่วนหัวของ Google Ads API Assistant (ไม่บังคับ)

ตัวแปรสภาพแวดล้อม

หากต้องการกำหนดค่าไลบรารีโดยใช้ตัวแปรสภาพแวดล้อม ให้ใช้ตัวแปรต่อไปนี้

  • 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 (รองรับใน v28.3.0 ขึ้นไป)

การกำหนดค่าบันทึก

ช่องบันทึก ซึ่งเป็นช่องที่อยู่ใต้ช่องการกำหนดค่า logging ได้มาจาก โมดูล logging.config ที่มากับระบบโดยตรง เนื่องจากไลบรารี จะส่งช่องทั้งหมดภายใต้เน0/} ไปยัง logging.config.dictConfig โดยตรงlogging ดูรายละเอียดทั้งหมดได้ใน คู่มือการบันทึก

  • version: ค่าจำนวนเต็มที่แสดงถึงเวอร์ชันสคีมา
  • disable_existing_loggers: ระบุว่าจะปิดใช้ Logger ที่กำหนดค่าไว้ที่อื่นในแอปพลิเคชันหรือไม่
  • formatters: พจนานุกรมที่กำหนดตัวจัดรูปแบบประเภทต่างๆ
  • handlers: พจนานุกรมที่กำหนด Handler ต่างๆ ซึ่งควบคุมตำแหน่งที่จะเขียนบันทึกและตัวจัดรูปแบบที่ควรใช้
  • loggers: พจนานุกรมที่กำหนด Logger ประเภทต่างๆ ซึ่งรวมถึง Handler และระดับบันทึก