ทำความเข้าใจข้อผิดพลาดของ API

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

Google Ads API เป็นไปตามโมเดลข้อผิดพลาดของ Google API มาตรฐาน ซึ่งอิงตามรหัสสถานะ gRPC การตอบกลับจาก API แต่ละรายการที่ทำให้เกิดข้อผิดพลาดจะมีออบเจ็กต์ Status ซึ่งประกอบด้วยข้อมูลต่อไปนี้

• รหัสข้อผิดพลาดที่เป็นตัวเลข
• ข้อความแสดงข้อผิดพลาด
• รายละเอียดข้อผิดพลาดเพิ่มเติม (ไม่บังคับ)

รหัสข้อผิดพลาด Canonical

Google Ads API ใช้ชุดรหัสข้อผิดพลาด Canonical ที่กำหนดโดย gRPC และ HTTP รหัสเหล่านี้จะระบุประเภทข้อผิดพลาดในระดับสูง คุณควรตรวจสอบรหัสตัวเลขนี้ก่อนเสมอเพื่อทำความเข้าใจลักษณะพื้นฐานของปัญหา

ตารางต่อไปนี้สรุปรหัสที่พบบ่อยที่สุดที่คุณอาจพบเมื่อใช้ Google Ads API

ดูรายละเอียดเพิ่มเติมเกี่ยวกับรหัสเหล่านี้ได้ที่คู่มือการออกแบบ API - รหัสข้อผิดพลาด

ทำความเข้าใจรายละเอียดข้อผิดพลาด

นอกเหนือจากรหัสระดับบนสุดแล้ว Google Ads API ยังให้ข้อมูลข้อผิดพลาดที่เฉพาะเจาะจงมากขึ้นภายในช่อง details ของออบเจ็กต์ Status ช่องนี้มักจะมีโปรโต GoogleAdsFailure ซึ่งรวมถึงรายการออบเจ็กต์ GoogleAdsError แต่ละรายการ

ออบเจ็กต์ GoogleAdsFailure แต่ละรายการประกอบด้วยข้อมูลต่อไปนี้

• errors: รายการออบเจ็กต์ GoogleAdsError ซึ่งแต่ละรายการจะให้รายละเอียดข้อผิดพลาดที่เฉพาะเจาะจงที่เกิดขึ้น
• request_id: รหัสที่ไม่ซ้ำกันสำหรับคำขอ ซึ่งมีประโยชน์สำหรับการแก้ไขข้อบกพร่องและการสนับสนุน

ออบเจ็กต์ GoogleAdsError แต่ละรายการจะมีข้อมูลต่อไปนี้

• error_code: ข้อผิดพลาดที่เจาะจงสำหรับ Google Ads APIErrorCode (ข้อผิดพลาดที่พบบ่อย) ซึ่งมีความละเอียดมากขึ้น เช่น AuthenticationError.NOT_ADS_USER
• message: คำอธิบายข้อผิดพลาดที่เฉพาะเจาะจงซึ่งมนุษย์อ่านได้
• trigger: Value ที่ทำให้เกิดข้อผิดพลาด (หากมี)
• location: ErrorLocation ที่อธิบายตำแหน่งที่เกิดข้อผิดพลาดในคำขอ รวมถึงเส้นทางของช่อง
• details: ErrorDetails เพิ่มเติม เช่น สาเหตุของข้อผิดพลาดที่ไม่ได้เผยแพร่

ตัวอย่างรายละเอียดข้อผิดพลาด

เมื่อได้รับข้อผิดพลาด ไลบรารีของไคลเอ็นต์จะช่วยให้คุณเข้าถึงรายละเอียดเหล่านี้ได้ ตัวอย่างเช่น INVALID_ARGUMENT (รหัส 3) อาจมีรายละเอียด GoogleAdsFailure ดังนี้

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v26.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ],
      "requestId": "AbCdEfGhIjKlMnOpQrStUv"
    }
  ]
}

ในตัวอย่างนี้ แม้ว่าจะมี INVALID_ARGUMENT ระดับบนสุด แต่รายละเอียด GoogleAdsFailure จะบอกคุณว่าช่อง name และ description เป็นสาเหตุของปัญหาและสาเหตุ (REQUIRED และ TOO_SHORT ตามลำดับ)

ค้นหารายละเอียดข้อผิดพลาด

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

การเรียก API มาตรฐานและการสตรีม

เมื่อการเรียก API ล้มเหลวโดยไม่ใช้ความล้มเหลวบางส่วน ซึ่งรวมถึงการเรียกสตรีมมิง ระบบจะแสดงผลออบเจ็กต์ GoogleAdsFailure เป็นส่วนหนึ่งของข้อมูลเมตาต่อท้ายในส่วนหัวการตอบกลับ gRPC หากคุณใช้ REST สำหรับการเรียกมาตรฐาน ระบบจะแสดงผล GoogleAdsFailure ในการตอบกลับ HTTP ไลบรารีของไคลเอ็นต์มักจะแสดงข้อผิดพลาดนี้เป็นข้อยกเว้นที่มีแอตทริบิวต์ GoogleAdsFailure

ไม่สำเร็จบางส่วน

หากคุณใช้การดำเนินการไม่สำเร็จบางส่วน ข้อผิดพลาดสำหรับการดำเนินการที่ไม่สำเร็จจะแสดงในช่อง partial_failure_error ของการตอบกลับ ไม่ใช่ในส่วนหัวการตอบกลับ ในกรณีนี้ GoogleAdsFailure จะฝังอยู่ภายในออบเจ็กต์ google.rpc.Status ในการตอบกลับ

งานแบบกลุ่ม

สำหรับการประมวลผลแบบกลุ่ม คุณจะดูข้อผิดพลาดสำหรับการดำเนินการแต่ละรายการได้โดยเรียกใช้ BatchJobService.ListBatchJobResults หลังจากงานเสร็จสมบูรณ์ ผลลัพธ์การดำเนินการแต่ละรายการจะมีช่อง status ซึ่งมีรายละเอียดข้อผิดพลาดหากการดำเนินการล้มเหลว

รหัสคำขอ

request-id คือสตริงที่ไม่ซ้ำกันซึ่งระบุคำขอ API ของคุณและจำเป็นสำหรับการแก้ปัญหา

คุณดู request-id ได้ในหลายตำแหน่ง ดังนี้

• GoogleAdsFailure: หากการเรียก API ไม่สำเร็จและระบบแสดงผล GoogleAdsFailure ผลลัพธ์ดังกล่าวจะมี request_id
• ข้อมูลเมตาต่อท้าย: สำหรับทั้งคำขอที่สำเร็จและไม่สำเร็จ request-id จะอยู่ในข้อมูลเมตาต่อท้ายของการตอบกลับ gRPC
• ส่วนหัวการตอบกลับ: สำหรับทั้งคำขอที่สำเร็จและไม่สำเร็จ request-id ยังมีอยู่ในส่วนหัวการตอบกลับ gRPC และการตอบกลับ HTTP ด้วย ยกเว้นคำขอสตรีมมิงที่สำเร็จ
• SearchGoogleAdsStreamResponse: สำหรับคำขอสตรีมมิง ข้อความ SearchGoogleAdsStreamResponse แต่ละรายการจะมีช่อง request_id

เมื่อบันทึกข้อผิดพลาดหรือติดต่อทีมสนับสนุน โปรดระบุ request-id เพื่อช่วยในการวิเคราะห์ปัญหา

แนวทางปฏิบัติแนะนำสำหรับการจัดการข้อผิดพลาด

หากต้องการสร้างแอปพลิเคชันที่ยืดหยุ่น ให้ใช้แนวทางปฏิบัติแนะนำต่อไปนี้

1. ตรวจสอบรายละเอียดข้อผิดพลาด: แยกวิเคราะห์ช่อง details ของออบเจ็กต์ Status เสมอ โดยเฉพาะการมองหา GoogleAdsFailure error_code, message และ location แบบละเอียดภายใน GoogleAdsError จะให้ข้อมูลที่นำไปใช้ได้จริงมากที่สุดสำหรับการแก้ไขข้อบกพร่องและความคิดเห็นของผู้ใช้

2. แยกความแตกต่างระหว่างข้อผิดพลาดของไคลเอ็นต์กับข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์:

   • ข้อผิดพลาดของไคลเอ็นต์: รหัส เช่น INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED ข้อผิดพลาดเหล่านี้จำเป็นต้องมีการเปลี่ยนแปลงคำขอหรือสถานะ/ข้อมูลเข้าสู่ระบบของแอปพลิเคชัน อย่าลองส่งคำขออีกครั้งโดยไม่แก้ไขปัญหา
   • ข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์: รหัส เช่น UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN ซึ่งบ่งชี้ว่าบริการ API มีปัญหาชั่วคราว

3. ใช้กลยุทธ์การลองใหม่:

   • กรณีที่ควรลองอีกครั้ง: ลองอีกครั้งเฉพาะเมื่อเกิดข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ชั่วคราว เช่น UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN และ ABORTED
   • Exponential Backoff: ใช้อัลกอริทึม Exponential Backoff เพื่อรอเป็นระยะเวลาที่เพิ่มขึ้นระหว่างการลองใหม่แต่ละครั้ง ซึ่งจะช่วยหลีกเลี่ยงการสร้างภาระมากเกินไปให้กับบริการที่ทำงานหนักอยู่แล้ว เช่น รอ 1 วินาที จากนั้นรอ 2 วินาที แล้วรอ 4 วินาที โดยเพิ่มระยะเวลารอไปเรื่อยๆ จนกว่าจะถึงจำนวนครั้งสูงสุดที่ลองใหม่หรือเวลารอรวม
   • Jitter: เพิ่ม "Jitter" แบบสุ่มจำนวนเล็กน้อยลงในความล่าช้าของ Backoff เพื่อป้องกันปัญหา "Thundering Herd" ที่ไคลเอ็นต์จำนวนมากพยายามอีกครั้งพร้อมกัน

4. บันทึกอย่างละเอียด: บันทึกการตอบกลับข้อผิดพลาดทั้งหมด รวมถึงรายละเอียดทั้งหมด โดยเฉพาะรหัสคำขอ ข้อมูลนี้จำเป็นสำหรับการแก้ไขข้อบกพร่องและ สำหรับการรายงานปัญหาไปยังทีมสนับสนุนของ Google หากจำเป็น

5. แสดงความคิดเห็นของผู้ใช้: แสดงความคิดเห็นที่ชัดเจนและเป็นประโยชน์ต่อผู้ใช้แอปพลิเคชันของคุณโดยอิงตามรหัสและข้อความ GoogleAdsError ที่เฉพาะเจาะจง เช่น แทนที่จะแสดงข้อความ "เกิดข้อผิดพลาด" คุณสามารถแสดงข้อความ "ต้องระบุชื่อแคมเปญ" หรือ "ไม่พบรหัสกลุ่มโฆษณาที่ระบุ"

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