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

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

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

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

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

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

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

โค้ด gRPC	โค้ด HTTP	ชื่อ Enum	คำอธิบาย	คำแนะนำ
0	200	OK	ไม่มีข้อผิดพลาด แสดงว่าสำเร็จ	ไม่มี
1	499	CANCELLED	การดำเนินการถูกยกเลิก โดยปกติแล้วจะยกเลิกโดยไคลเอ็นต์	โดยปกติหมายความว่าไคลเอ็นต์หยุดรอแล้ว ตรวจสอบการหมดเวลาฝั่งไคลเอ็นต์
2	500	UNKNOWN	เกิดข้อผิดพลาดที่ไม่รู้จัก ข้อความแสดงข้อผิดพลาดหรือรายละเอียดอาจมีรายละเอียดเพิ่มเติม	ถือว่าเป็นข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ มักลองใหม่ได้ด้วยการหยุดชั่วคราว
3	400	INVALID_ARGUMENT	ไคลเอ็นต์ระบุอาร์กิวเมนต์ไม่ถูกต้อง ซึ่งบ่งบอกถึงปัญหาที่ทำให้ API ประมวลผลคำขอไม่ได้ เช่น ชื่อทรัพยากรที่จัดรูปแบบไม่ถูกต้องหรือค่าที่ไม่ถูกต้อง	ข้อผิดพลาดของไคลเอ็นต์: ตรวจสอบพารามิเตอร์คำขอและดูว่าเป็นไปตามข้อกำหนดของ API โดยปกติแล้ว รายละเอียดข้อผิดพลาดจะให้ข้อมูลเกี่ยวกับอาร์กิวเมนต์ที่ไม่ถูกต้องและวิธีแก้ไขคำขอ อย่าลองอีกครั้งโดยไม่แก้ไขคำขอ
4	504	DEADLINE_EXCEEDED	กำหนดเวลาหมดอายุก่อนที่การดำเนินการจะเสร็จสมบูรณ์	ข้อผิดพลาดของเซิร์ฟเวอร์: มักเกิดขึ้นชั่วคราว ลองอีกครั้งโดยใช้ Exponential Backoff
5	404	NOT_FOUND	ไม่พบเอนทิตีที่ขอ เช่น แคมเปญหรือกลุ่มโฆษณา	ข้อผิดพลาดของไคลเอ็นต์: ตรวจสอบว่ามีทรัพยากรที่คุณพยายามเข้าถึงและมีรหัสของทรัพยากรนั้น อย่าลองอีกครั้งโดยไม่แก้ไข
6	409	ALREADY_EXISTS	มีเอนทิตีที่ไคลเอ็นต์พยายามสร้างอยู่แล้ว	ข้อผิดพลาดของไคลเอ็นต์: หลีกเลี่ยงการสร้างทรัพยากรที่ซ้ำกัน ตรวจสอบว่ามีทรัพยากรอยู่หรือไม่ก่อนที่จะพยายามสร้าง
7	403	PERMISSION_DENIED	ผู้เรียกใช้ไม่มีสิทธิ์ดำเนินการที่ระบุ	ข้อผิดพลาดของไคลเอ็นต์: ตรวจสอบการตรวจสอบสิทธิ์ การให้สิทธิ์ และบทบาทของผู้ใช้สำหรับบัญชี Google Ads อย่าลองอีกครั้งโดยไม่แก้ไขสิทธิ์
8	429	RESOURCE_EXHAUSTED	อาจเป็นเพราะใช้ทรัพยากรจนหมด (เช่น คุณใช้เกินโควต้า) หรือระบบทำงานหนักเกินไป	ข้อผิดพลาดของไคลเอ็นต์/เซิร์ฟเวอร์: โดยปกติแล้วต้องรอ ใช้ Exponential Backoff และอาจลดอัตราการส่งคำขอ ดูขีดจำกัดและโควต้า API
9	400	FAILED_PRECONDITION	การดำเนินการถูกปฏิเสธเนื่องจากระบบไม่ได้อยู่ในสถานะที่จำเป็นสำหรับการดำเนินการ เช่น ไม่มีข้อมูลในช่องที่ต้องกรอก	ข้อผิดพลาดของไคลเอ็นต์: คำขอถูกต้อง แต่สถานะไม่ถูกต้อง ตรวจสอบรายละเอียดข้อผิดพลาดเพื่อทำความเข้าใจว่าเหตุใดจึงไม่เป็นไปตามเงื่อนไขเบื้องต้น อย่าลองอีกครั้งโดยไม่แก้ไขสถานะ
10	409	ABORTED	การดำเนินการถูกยกเลิก ซึ่งมักเกิดจากปัญหาการทำงานพร้อมกัน เช่น ความขัดแย้งของธุรกรรม	ข้อผิดพลาดของเซิร์ฟเวอร์: มักจะลองใหม่ได้โดยใช้การหยุดชั่วคราวสั้นๆ
11	400	OUT_OF_RANGE	พยายามดำเนินการนอกช่วงที่ถูกต้อง	ข้อผิดพลาดของไคลเอ็นต์: แก้ไขช่วงหรือดัชนี
12	501	UNIMPLEMENTED	API ไม่ได้ใช้หรือรองรับการดำเนินการนี้	ข้อผิดพลาดของไคลเอ็นต์: ตรวจสอบเวอร์ชัน API และฟีเจอร์ที่พร้อมใช้งาน ไม่ต้องลองอีก
13	500	INTERNAL	เกิดข้อผิดพลาดภายใน นี่คือการดักจับทั่วไปสำหรับปัญหาฝั่งเซิร์ฟเวอร์	ข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์: โดยทั่วไปแล้วสามารถลองอีกครั้งได้โดยใช้ Exponential Backoff หากปัญหายังคงอยู่ โปรดรายงานปัญหา
14	503	UNAVAILABLE	บริการนี้ไม่พร้อมใช้งานชั่วคราว ซึ่งมักเป็นเพียงชั่วคราว	ข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์: ขอแนะนำให้ลองอีกครั้งโดยใช้ Exponential Backoff
15	500	DATA_LOSS	ข้อมูลสูญหายโดยกู้คืนไม่ได้หรือข้อมูลเสียหาย	ข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์: นานๆ ครั้ง บ่งบอกถึงปัญหาร้ายแรง ไม่ต้องลองอีก หากปัญหายังคงอยู่ โปรดรายงานปัญหา
16	401	UNAUTHENTICATED	คำขอไม่มีข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ที่ถูกต้อง	ข้อผิดพลาดของไคลเอ็นต์: ตรวจสอบโทเค็นการตรวจสอบสิทธิ์และข้อมูลเข้าสู่ระบบ อย่าลองอีกครั้งโดยไม่แก้ไขการตรวจสอบสิทธิ์

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

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

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

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

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

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

• error_code: Google Ads API ErrorCode ที่ละเอียดยิ่งขึ้น (ข้อผิดพลาดที่พบบ่อย) เช่น 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.v25.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 แบบสตรีม

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