ทำความเข้าใจข้อผิดพลาดของ 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 แต่ละรายการมีข้อมูลต่อไปนี้

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

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

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

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

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

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

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

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

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

การล้มเหลวบางส่วน

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

งานแบบกลุ่ม

สำหรับการประมวลผลแบบกลุ่ม คุณจะดูข้อผิดพลาดสำหรับการดำเนินการ แต่ละรายการได้โดยดึงข้อมูลผลลัพธ์ของงานแบบกลุ่มหลังจาก ที่งานเสร็จสมบูรณ์ ผลลัพธ์การดำเนินการแต่ละรายการจะมีช่อง 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 errorCode 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 แสดงผลได้อย่างมีประสิทธิภาพ ซึ่งจะทำให้แอปพลิเคชันมีเสถียรภาพมากขึ้นและใช้งานง่ายขึ้น