啟用 Logging

這個程式庫提供多種記錄 Google Ads API 互動的方式。你可以擷取:

  • 詳細資訊:傳送至 API 的完整要求和收到的回應。
  • 簡明摘要:互動的概要總覽。

您可以透過兩種方式控管這些記錄設定:

  • 用戶端程式庫設定:使用程式庫的特定設定選項。
  • 透過 Python 以程式輔助方式操作:使用 Python 的內建 logging 架構,直接控管記錄。

初始化 GoogleAdsClient 執行個體時,系統會自動設定記錄功能。舉例來說,當您使用 load_from_storage 方法時,就會發生這個初始化步驟。此時,程式庫會:

當這個程式庫做為已安裝的套件使用時,您需要將其記錄與應用程式的記錄設定整合。具體來說,您必須使用 addHandler 方法,將記錄處理常式新增至程式庫本身的記錄器例項。這個處理常式會決定程式庫的記錄訊息要導向何處 (例如控制台、檔案等)。如要這麼做,請先擷取程式庫的記錄器例項,如下所示:

import logging

logger = logging.getLogger('google.ads.googleads.client')

擷取程式庫的記錄器後,您可以指定記錄訊息的輸出位置。

  • 將記錄檔傳送至控制台:如要在控制台上顯示記錄訊息,請新增基本處理常式。以下說明如何將記錄導向標準輸出 (stdout):

    以下說明如何設定基本處理常式,讓記錄器將內容列印至 stdout

    import sys
    
    # Assuming 'logger' was retrieved as per previous instructions
    logger.addHandler(logging.StreamHandler(sys.stdout))
    

    如要將記錄傳送至標準錯誤 (stderr),這通常用於錯誤訊息和警告:

    import sys
    
    # Assuming 'logger' was retrieved as per previous instructions
    logger.addHandler(logging.StreamHandler(sys.stderr))
    
  • 以程式輔助方式設定其他記錄設定:取得記錄器物件後,您也可以使用 Python 的內建 logging 模組,以程式輔助方式變更其他記錄設定。舉例來說,如要將記錄層級變更為 DEBUG (顯示更詳細的訊息):

    logger.setLevel(logging.DEBUG)
    

記錄層級

用戶端會在幾個不同層級產生記錄,您可以設定要查看部分或全部的下列項目:

等級 要求成功 要求失敗
DEBUG 詳細記錄,其中包含完整的 JSON 格式要求和回應物件。 詳細記錄,其中包含完整的 JSON 格式要求和例外狀況物件。
INFO 簡要摘要,包含特定要求和回應欄位。 詳細記錄,其中包含完整的 JSON 格式要求和例外狀況物件。
WARNING 簡要摘要,內含特定要求資訊、例外狀況狀態和訊息。

由於 Python 記錄架構會忽略嚴重程度低於設定層級的記錄訊息,因此設為 WARNING 表示您只會看到與要求失敗相關的簡要訊息,但設為 DEBUG 表示您會看到上表中的所有可能記錄類型。

記錄到檔案

從指令列執行範例指令碼 (例如 get_campaigns.py) 時,通常會將所有列印至主控台的記錄訊息重新導向 (或「透過管道傳送」) 至檔案。這是作業系統殼層的功能,而非 Python 程式庫本身。步驟如下:

如要將標準輸出內容 (大部分的記錄) 儲存至檔案 (並覆寫檔案),請執行下列操作:

python get_campaigns.py -c $CLIENT_ID > campaign_logs.txt

如要將標準輸出內容附加至檔案:

python get_campaigns.py -c $CLIENT_ID >> campaign_logs.txt

如要將標準輸出和標準錯誤 (適用於錯誤/警告) 儲存至同一個檔案,請按照下列步驟操作:

python get_campaigns.py -c $CLIENT_ID > all_logs.txt 2>&1

(或者,在 Bash 4 以上版本等部分新式殼層中):

python get_campaigns.py -c $CLIENT_ID &> all_logs.txt

記錄攔截器

Python 用戶端程式庫會使用 gRPC 攔截器存取及記錄要求和回應詳細資料。您可以建立具有自訂邏輯的 gRPC 攔截器,設定自己的自訂記錄。如需更多詳細資料和自訂記錄攔截器的範例,請參閱「記錄」指南。