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

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