จัดการการตอบกลับข้อผิดพลาด

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

ภาพรวม

เมื่อคำขอ Merchant API ไม่สำเร็จ API จะแสดงรหัสสถานะ HTTP มาตรฐาน (4xx หรือ 5xx) และเนื้อความการตอบกลับ JSON ที่มีรายละเอียดเกี่ยวกับข้อผิดพลาด Merchant API เป็นไปตามมาตรฐาน AIP-193 สำหรับ รายละเอียดข้อผิดพลาด โดยให้ข้อมูลที่เครื่องอ่านได้ซึ่งช่วยให้แอปพลิเคชัน จัดการสถานการณ์ข้อผิดพลาดที่เฉพาะเจาะจงได้โดยใช้โปรแกรม

โครงสร้างการตอบกลับข้อผิดพลาด

การตอบกลับข้อผิดพลาดเป็นออบเจ็กต์ JSON ที่มีฟิลด์มาตรฐาน เช่น code, message และ status ที่สำคัญคือยังมีอาร์เรย์ details ด้วย หากต้องการ จัดการข้อผิดพลาดโดยใช้โปรแกรม คุณควรค้นหาออบเจ็กต์ภายใน details ซึ่ง @type เป็น type.googleapis.com/google.rpc.ErrorInfo

ออบเจ็กต์ ErrorInfo นี้ให้ข้อมูลที่มีโครงสร้างที่เสถียรเกี่ยวกับข้อผิดพลาด

  • โดเมน: การจัดกลุ่มข้อผิดพลาดเชิงตรรกะ ซึ่งโดยปกติคือ merchantapi.googleapis.com
  • metadata: แผนที่ของค่าแบบไดนามิกที่เกี่ยวข้องกับข้อผิดพลาด ซึ่งรวมถึง
    • REASON: ตัวระบุที่เฉพาะเจาะจงและเสถียรสำหรับข้อผิดพลาดที่แน่นอน (เช่น INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS) ฟิลด์นี้จะ มีอยู่เสมอ ใช้ฟิลด์นี้เพื่อการจัดการข้อผิดพลาดแบบละเอียด ในตรรกะของแอปพลิเคชัน
    • HELP_CENTER_LINK: ให้บริบทและวิธีการเพิ่มเติมในการ แก้ไขปัญหา ฟิลด์นี้ไม่ได้มีอยู่ในข้อผิดพลาดทั้งหมด แต่เราวางแผนที่จะ ขยายความครอบคลุมเมื่อเวลาผ่านไปสำหรับข้อผิดพลาดที่อาจต้องมีบริบทเพิ่มเติม
    • ฟิลด์แบบไดนามิกอื่นๆ: คีย์อื่นๆ ที่ให้บริบท เช่น ชื่อ ของฟิลด์ที่ไม่ถูกต้อง (FIELD_LOCATION) หรือค่าที่ทำให้เกิด ข้อผิดพลาด (FIELD_VALUE)

ตัวอย่างการตอบกลับข้อผิดพลาด

JSON ต่อไปนี้แสดงโครงสร้างของข้อผิดพลาดของ Merchant API ที่ ชื่อทรัพยากรมีรูปแบบไม่ถูกต้อง

{
  "error": {
    "code": 400,
    "message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "VARIABLE_NAME": "account",
          "FIELD_LOCATION": "name",
          "FIELD_VALUE": "abcd",
          "REASON": "INVALID_NAME_PART_NOT_NUMBER"
        }
      }
    ]
  }
}

ตัวอย่างข้อผิดพลาดในการตรวจสอบสิทธิ์มีดังนี้

{
  "error": {
    "code": 401,
    "message": "The caller does not have access to the accounts: [1234567]",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "unauthorized",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_IDS": "[1234567]",
          "REASON": "PERMISSION_DENIED_ACCOUNTS"
        }
      }
    ]
  }
}

ความเสถียรของฟิลด์ข้อผิดพลาด

เมื่อเขียนตรรกะการจัดการข้อผิดพลาด คุณควรทราบว่าฟิลด์ใดที่เชื่อถือได้ และฟิลด์ใดที่อาจมีการเปลี่ยนแปลง

  • ฟิลด์ที่เสถียร:

  • details.metadata.REASON: ตัวระบุข้อผิดพลาดที่เฉพาะเจาะจง คุณควร ใช้ฟิลด์นี้สำหรับตรรกะโฟลว์การควบคุมของแอปพลิเคชัน

    • details.metadata คีย์: คีย์ภายในแมปข้อมูลเมตา (เช่น FIELD_LOCATION, ACCOUNT_IDS) มีความเสถียร
    • code: รหัสสถานะ HTTP ระดับสูง (เช่น 400, 401, 503) มีความเสถียร

  • ฟิลด์ที่ไม่เสถียร:

    • message: ข้อความแสดงข้อผิดพลาดที่มนุษย์อ่านได้ไม่เสถียร มีไว้สำหรับการแก้ไขข้อบกพร่องของนักพัฒนาแอปเท่านั้น อย่าเขียนโค้ดที่แยกวิเคราะห์ หรืออิงตามเนื้อหาข้อความของฟิลด์ message เนื่องจากอาจมีการเปลี่ยนแปลง โดยไม่ต้องแจ้งให้ทราบเพื่อปรับปรุงความชัดเจนหรือเพิ่มบริบท
    • ค่าdetails.metadata: แม้ว่าคีย์จะคงที่ แต่ค่า สำหรับคีย์ข้อมูลอาจเปลี่ยนแปลงได้ เช่น หากมีการระบุHELP_CENTER_LINK คีย์ ระบบอาจอัปเดต URL ที่เฉพาะเจาะจงซึ่งคีย์นั้นชี้ไปยังหน้าเอกสารเวอร์ชันใหม่กว่าโดยไม่ต้องแจ้งให้ทราบล่วงหน้า อย่างไรก็ตาม ดังที่ กล่าวไว้ก่อนหน้านี้ ค่าของ details.metadata.REASON มีความเสถียร

แนวทางปฏิบัติแนะนำ

ทําตามแนวทางปฏิบัติแนะนําเหล่านี้เพื่อให้การผสานรวมจัดการข้อผิดพลาดได้อย่างราบรื่น

ใช้ details.metadata.REASON สำหรับตรรกะ

ใช้ REASON ที่เฉพาะเจาะจงภายในแผนที่ metadata เสมอเพื่อระบุสาเหตุของข้อผิดพลาด อย่าใช้รหัสสถานะ HTTP เพียงอย่างเดียว เนื่องจากข้อผิดพลาดหลายรายการอาจใช้รหัสสถานะเดียวกัน

อย่าแยกวิเคราะห์ข้อความแสดงข้อผิดพลาด

ดังที่ระบุไว้ในส่วนความเสถียร ฟิลด์ message มีไว้สำหรับมนุษย์ หากต้องการข้อมูลแบบไดนามิก (เช่น ฟิลด์ใดไม่ถูกต้อง) ให้นำข้อมูลดังกล่าวออกจาก แมป metadata โดยใช้คีย์ที่เสถียร เช่น FIELD_LOCATION, VARIABLE_NAME

ใช้ Exponential Backoff

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

  • quota/request_rate_too_high: ข้อผิดพลาดนี้บ่งชี้ว่าคุณใช้โควต้านาทีสำหรับกลุ่มโควต้าที่เฉพาะเจาะจงเกินแล้ว ชะลออัตราการส่งคำขอ
  • internal_error: โดยปกติแล้วข้อผิดพลาดเหล่านี้จะเกิดขึ้นชั่วคราว ลองอีกครั้งโดยใช้ Exponential Backoff หมายเหตุ: หากinternal_errorยังคงอยู่หลังจากลองอีกหลายครั้งโดยใช้ การถอย โปรดดูวิธีติดต่อทีมสนับสนุน Merchant API

วิธีติดต่อทีมสนับสนุน Merchant API

หากต้องการติดต่อทีมสนับสนุน Merchant API เกี่ยวกับข้อผิดพลาด ที่เฉพาะเจาะจง โปรดระบุข้อมูลต่อไปนี้ในคำขอ

  1. การตอบกลับที่มีข้อผิดพลาดที่ได้รับ
  2. ชื่อเมธอดของ API
  3. เพย์โหลดคำขอ
  4. การประทับเวลาหรือช่วงเวลาที่เรียกใช้เมธอดและได้รับข้อผิดพลาด