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

คู่มือนี้อธิบายวิธีจัดการข้อผิดพลาดที่ 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 นี้ให้ข้อมูลที่มีโครงสร้างและเสถียรเกี่ยวกับข้อผิดพลาด ดังนี้

• domain: การจัดกลุ่มข้อผิดพลาดเชิงตรรกะ ซึ่งโดยทั่วไปคือ 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

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

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

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

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

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