疑難排解

影片:觀看 2019 年研討會的錯誤處理講座

錯誤可能是因為環境設定不正確、軟體有錯誤,或是使用者輸入無效資料。無論來源為何,您都需要排解問題,並修正程式碼或新增邏輯來處理使用者錯誤。本指南將說明如何運用一些最佳做法,排解 Google Ads API 的錯誤。

確保連線

  1. 請確認您有權存取 Google Ads API,且設定正確無誤。如果回應傳回任何 HTTP 錯誤,請務必仔細處理這些錯誤,並確認您是從程式碼連線至要使用的服務。

  2. 您的憑證會嵌入要求中,以便服務驗證您的身分。請熟悉 Google Ads API 要求和回應的結構,尤其是要處理不使用用戶端程式庫的呼叫時。每個用戶端程式庫都會附上具體的操作說明,教您如何在設定檔中加入憑證 (請參閱用戶端程式庫的 README)。

  3. 確認您使用的憑證正確無誤。我們的快速入門導覽課程會逐步引導您取得正確的設定。舉例來說,下列回應失敗情形顯示使用者傳送的驗證憑證無效:

    {
      "error": {
        "code": 401,
        "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. Visit https://developers.google.com/identity/sign-in/web/devconsole-project.",
        "status": "UNAUTHENTICATED",
        "details": [
          {
            "@type": "type.googleapis.com/google.rpc.DebugInfo",
            "detail": "Authentication error: 2"
          }
        ]
      }
    }
    

如果按照上述步驟操作後仍無法解決問題,請開始排解 Google Ads API 錯誤。

判斷問題

Google Ads API 通常會以 JSON 失敗物件的形式回報錯誤,其中包含回應中的錯誤清單。這些物件會提供錯誤代碼,以及說明發生錯誤原因的訊息。這些是問題可能出在哪裡的初步信號。

{
  "errors": [
    {
      "errorCode": { "fieldMaskError": "FIELD_NOT_FOUND" },
      "message": "The field mask contained an invalid field: 'keyword/matchtype'.",
      "location": { "operationIndex": "1" }
    }
  ]
}

所有用戶端程式庫都會擲回例外狀況,封裝回應中的錯誤。擷取這些例外狀況,並在記錄或疑難排解畫面中列印訊息,是個不錯的開始。將這項資訊與應用程式中記錄的其他事件整合,即可大致瞭解可能觸發問題的原因。找出記錄中的錯誤後,您需要瞭解錯誤的意義。

研究錯誤

  1. 請參閱「常見錯誤」說明文件,瞭解最常遇到的錯誤。說明錯誤訊息、相關 API 參照,以及如何避免或處理錯誤。

  2. 如果常見錯誤說明文件未提及該錯誤,請參閱參考說明文件,並尋找錯誤字串。

  3. 搜尋我們的支援管道,與其他開發人員交流使用 API 的心得。其他人可能已遇到並解決您遇到的問題。

  4. 如果遇到任何未記錄的錯誤,請在論壇上回報。

  5. 如要排解驗證或帳戶限制問題,請前往 Google Ads 說明中心。Google Ads API 會沿用核心 Google Ads 產品的規則和限制。

  6. 有時,網誌文章會是排解應用程式問題時的實用參考資料。

研究錯誤後,請找出根本原因。

找出原因

查看例外狀況訊息,找出錯誤原因。查看回應後,請檢查要求,找出可能的原因。部分 Google Ads API 錯誤訊息會在 GoogleAdsErrorlocation 欄位中包含 fieldPathElements,指出要求中發生錯誤的位置。例如:

{
  "errors": [
    {
      "errorCode": {"criterionError": "CANNOT_ADD_CRITERIA_TYPE"},
      "message": "Criteria type can not be targeted.",
      "trigger": { "stringValue": "" },
      "location": {
        "operationIndex": "0",
        "fieldPathElements": [ { "fieldName": "keyword" } ]
      }
    }
  ]
}

排解問題時,可能是應用程式提供給 API 的資訊有誤。我們強烈建議使用互動式開發環境 (IDE),例如 Eclipse (免費的開放原始碼 IDE,主要用於開發 Java,但有其他語言的外掛程式),協助您進行偵錯。您可以設定中斷點,並逐行逐步執行程式碼。

請仔細檢查,確認要求與應用程式輸入內容相符 (例如,要求中可能沒有廣告活動名稱)。請務必傳送與要進行的更新相符的欄位遮罩,因為 Google Ads API 支援稀疏更新。在變動要求中從欄位遮罩省略欄位,表示 API 應保留該欄位。如果應用程式擷取物件、進行變更並傳回,您可能會寫入不支援更新的欄位。請參閱參考說明文件中的欄位說明,瞭解更新欄位時是否有任何限制。

如何取得協助

有時您可能無法自行找出並解決問題。 在論壇提問,可讓數千名開發人員看到您的問題,他們可能也曾遇到相同問題。

請盡量在查詢中提供相關資訊。 建議提供的資訊包括:

  • 經過清理的 JSON 要求和回應。請務必移除開發人員權杖或 AuthToken 等機密資訊。
  • 程式碼片段。如果您遇到特定語言的問題,或是需要 API 相關協助,請附上程式碼片段,說明您執行的操作。
  • RequestId。如果要求是針對正式版環境提出,Google 開發人員關係團隊成員就能找到您的要求。建議您在記錄檔中,將 requestId 登錄為封裝回應錯誤的例外狀況屬性,並登錄比 requestId 本身更豐富的內容。
  • 此外,執行階段/解譯器版本和平台等其他資訊,也有助於排解問題。

修正相關問題

您已找出問題並提出解決方案,現在可以進行變更,並針對測試帳戶 (建議) 或正式版 (如果錯誤只適用於特定正式版帳戶中的資料) 測試修正程式。

考慮分享

如果您在論壇中發布了有關先前未出現錯誤的問題,且已找到解決方案,請考慮將解決方案新增至該討論串。下次開發人員遇到相同問題時,就能立即解決。

後續步驟

您已解決這個問題,但您是否發現任何改善程式碼的方法,以避免再次發生這種情況?

建立一組良好的單元測試,有助於大幅提升程式碼品質和可靠性。此外,這項功能還能加快測試新變更的程序,確保新變更不會破壞先前的功能。此外,良好的錯誤處理策略也是找出所有必要資料以利排解問題的關鍵。