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

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

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

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

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

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

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

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

ทำตามขั้นตอนต่อไปนี้เมื่อคำขอไม่สำเร็จ

  1. ตรวจสอบรหัสข้อผิดพลาดเพื่อดูประเภทข้อผิดพลาด

    • หากคุณใช้ gRPC รหัสข้อผิดพลาดจะอยู่ในช่อง code ของ Status หากคุณใช้ไลบรารีของไคลเอ็นต์ ไลบรารีอาจแสดง ข้อยกเว้นประเภทใดประเภทหนึ่งที่เฉพาะเจาะจงซึ่งสอดคล้องกับรหัสข้อผิดพลาด เช่น ไลบรารีของไคลเอ็นต์สำหรับ Java จะแสดง com.google.api.gax.rpc.InvalidArgumentException หากรหัสข้อผิดพลาดคือ INVALID_ARGUMENT
    • หากคุณใช้ REST รหัสข้อผิดพลาดจะอยู่ในการตอบกลับข้อผิดพลาดที่ error.status และสถานะ HTTP ที่เกี่ยวข้องจะอยู่ที่ error.code

  2. ตรวจสอบเพย์โหลดรายละเอียดมาตรฐานสำหรับ รหัสข้อผิดพลาด เพย์โหลดรายละเอียดมาตรฐานคือชุดข้อความสำหรับข้อผิดพลาด จาก Google APIs ซึ่งจะให้รายละเอียดข้อผิดพลาดในลักษณะที่มีโครงสร้างและสอดคล้องกัน ข้อผิดพลาดแต่ละรายการจาก Data Manager API อาจมีข้อความเพย์โหลดรายละเอียดมาตรฐานหลายรายการ ไลบรารีของไคลเอ็นต์ Data Manager API มีเมธอดตัวช่วยเพื่อรับเพย์โหลดรายละเอียดมาตรฐาน จากข้อผิดพลาด

    ไม่ว่ารหัสข้อผิดพลาดจะเป็นอะไร เราขอแนะนำให้คุณตรวจสอบและบันทึกเพย์โหลด ErrorInfo, RequestInfo, Help, และ LocalizedMessage

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

    นอกจากนี้ เพย์โหลด BadRequest ยังมีประโยชน์สำหรับข้อผิดพลาด INVALID_ARGUMENT เนื่องจากมีข้อมูลเกี่ยวกับช่องที่ทำให้เกิดข้อผิดพลาด

เพย์โหลดรายละเอียดมาตรฐาน

เพย์โหลดรายละเอียดมาตรฐานที่พบบ่อยที่สุดสำหรับ Data Manager API ได้แก่

BadRequest

ตรวจสอบเพย์โหลด BadRequest เมื่อคำขอไม่สำเร็จด้วย INVALID_ARGUMENT (รหัสสถานะ HTTP 400)

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

field

ตำแหน่งของช่องในคำขอ โดยใช้ไวยากรณ์เส้นทาง Camel Case

หากเส้นทางชี้ไปยังรายการในรายการ (ช่อง repeated) ดัชนีของรายการจะแสดงในวงเล็บเหลี่ยม ([...]) หลังชื่อรายการ

เช่น destinations[0].operating_account.account_id คือ account_id ใน operating_account ของรายการแรกใน destinations รายการ

description

คำอธิบายสาเหตุที่ค่าทำให้เกิดข้อผิดพลาด

reason

Enum ErrorReason เช่น INVALID_HEX_ENCODING หรือ INVALID_CURRENCY_CODE.

ตัวอย่างของ BadRequest

นี่คือตัวอย่างการตอบกลับสำหรับข้อผิดพลาด INVALID_ARGUMENT พร้อมข้อความ BadRequest field_violations แสดงว่าข้อผิดพลาดคือ accountId ที่ไม่ใช่ตัวเลข ค่า field destinations[0].login_account.account_id แสดงว่า accountId ที่มีการละเมิดช่องอยู่ใน login_account ของรายการแรก ในรายการ destinations

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com",
        "metadata": {
          "requestId": "t-a8896317-069f-4198-afed-182a3872a660"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "t-a8896317-069f-4198-afed-182a3872a660"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "destinations[0].login_account.account_id",
            "description": "String is not a valid number.",
            "reason": "INVALID_NUMBER_FORMAT"
          }
        ]
      }
    ]
  }
}

นี่คือตัวอย่างการตอบกลับอีกรายการจากข้อผิดพลาด INVALID_ARGUMENT พร้อมข้อความ BadRequest ในกรณีนี้ รายการ field_violations แสดงข้อผิดพลาด 2 รายการ

  1. event รายการแรกมีค่าที่ไม่ได้เข้ารหัสแบบเลขฐาน 16 ในตัวระบุผู้ใช้ที่ 2 ของเหตุการณ์

  2. event รายการที่ 2 มีค่าที่ไม่ได้เข้ารหัสแบบเลขฐาน 16 ในตัวระบุผู้ใช้ที่ 3 ของเหตุการณ์ 

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com",
        "metadata": {
          "requestId": "t-6bc8fb83-d648-4942-9c49-2604276638d8"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "t-6bc8fb83-d648-4942-9c49-2604276638d8"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers[1]",
            "description": "The HEX encoded value is malformed.",
            "reason": "INVALID_HEX_ENCODING"
          },
          {
            "field": "events.events[1].user_data.user_identifiers[2]",
            "description": "The HEX encoded value is malformed.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

RequestInfo

ตรวจสอบเพย์โหลด RequestInfo ทุกครั้งที่คำขอไม่สำเร็จ RequestInfo มี request_id ที่ระบุคำขอ API ของคุณโดยไม่ซ้ำกัน

{
  "@type": "type.googleapis.com/google.rpc.RequestInfo",
  "requestId": "t-4490c640-dc5d-4c28-91c1-04a1cae0f49f"
}

เมื่อบันทึกข้อผิดพลาดหรือ ติดต่อทีมสนับสนุน โปรดอย่าลืมใส่ รหัสคำขอเพื่อช่วยในการวินิจฉัยปัญหา

ErrorInfo

ตรวจสอบข้อความ ErrorInfo เพื่อดึงข้อมูลเพิ่มเติมที่ อาจไม่ได้บันทึกไว้ในเพย์โหลดรายละเอียดมาตรฐานอื่นๆ เพย์โหลด ErrorInfo มีแผนที่ metadata พร้อมข้อมูลเกี่ยวกับข้อผิดพลาด

ตัวอย่างเช่น นี่คือ ErrorInfo สำหรับความล้มเหลว PERMISSION_DENIED ที่เกิดจากการใช้ข้อมูลเข้าสู่ระบบสำหรับโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google ที่ไม่ได้เปิดใช้ Data Manager API ErrorInfo ให้ข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาด เช่น

  • โปรเจ็กต์ที่เชื่อมโยงกับคำขอใน metadata.consumer
  • ชื่อบริการใน metadata.serviceTitle
  • URL ที่เปิดใช้บริการได้ใน metadata.activationUrl
{
  "error": {
    "code": 403,
    "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "SERVICE_DISABLED",
        "domain": "googleapis.com",
        "metadata": {
          "consumer": "projects/PROJECT_NUMBER",
          "service": "datamanager.googleapis.com",
          "containerInfo": "PROJECT_NUMBER",
          "serviceTitle": "Data Manager API",
          "activationUrl": "https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
        }
      },
      ...
    ]
  }
}

Help และ LocalizedMessage

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

ตัวอย่างเช่น นี่คือ Help และ LocalizedMessage สำหรับความล้มเหลว PERMISSION_DENIED ที่เกิดจากการใช้ข้อมูลเข้าสู่ระบบสำหรับโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google ที่ไม่ได้เปิดใช้ Data Manager API เพย์โหลด Help แสดง URL ที่เปิดใช้บริการได้ และ LocalizedMessage มีคำอธิบายข้อผิดพลาด

{
  "error": {
    "code": 403,
    "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry."
      },
      {
        "@type": "type.googleapis.com/google.rpc.Help",
        "links": [
          {
            "description": "Google API Console API activation",
            "url": "https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
          }
        ]
      },
      ...
    ]
  }
}

เข้าถึงรายละเอียดข้อผิดพลาด

หากคุณใช้ไลบรารีของไคลเอ็นต์รายการใดรายการหนึ่ง ให้ใช้ เมธอดตัวช่วยเพื่อรับเพย์โหลดรายละเอียดมาตรฐาน

.NET

try {
    // Send API request
}
catch (Grpc.Core.RpcException rpcException)
{
    Console.WriteLine($"Exception encountered: {rpcException.Message}");
    var statusDetails =
        Google.Api.Gax.Grpc.RpcExceptionExtensions.GetAllStatusDetails(
            rpcException
        );
    foreach (var detail in statusDetails)
    {
        if (detail is Google.Rpc.BadRequest)
        {
            Google.Rpc.BadRequest badRequest = (Google.Rpc.BadRequest)detail;
            foreach (
                BadRequest.Types.FieldViolation? fieldViolation in badRequest.FieldViolations
            )
            {
                // Access attributes such as fieldViolation!.Reason and fieldViolation!.Field
            }
        }
        else if (detail is Google.Rpc.RequestInfo)
        {
            Google.Rpc.RequestInfo requestInfo = (Google.Rpc.RequestInfo)detail;
            string requestId = requestInfo.RequestId;
            // Log the requestId...
        }
        else if (detail is Google.Rpc.ErrorInfo)
        {
            Google.Rpc.ErrorInfo errorInfo = (Google.Rpc.ErrorInfo)detail;
            // Log the errorInfo.Reason and errorInfo.Metadata...

            // Log the details in the 'Metadata' map...
            foreach (
                KeyValuePair<String, String> metadataEntry in errorInfo.Metadata
            )
            {
                // Log the metadataEntry.Key and metadataEntry.Value...
            }
        }
        else
        {
            // ...
        }
    }
}

Java

try {
  // Send API request
} catch (com.google.api.gax.rpc.InvalidArgumentException invalidArgumentException) {
  // Gets the standard BadRequest payload from the exception.
  BadRequest badRequest = invalidArgumentException.getErrorDetails().getBadRequest();
  for (int i = 0; i < badRequest.getFieldViolationsCount(); i++) {
    FieldViolation fieldViolation = badRequest.getFieldViolations(i);
    // Access attributes such as fieldViolation.getField() and fieldViolation.getReason()
  }

  // Gets the standard RequestInfo payload from the exception.
  RequestInfo requestInfo = invalidArgumentException.getErrorDetails().getRequestInfo();
  if (requestInfo != null) {
    String requestId = requestInfo.getRequestId();
    // Log the requestId...
  }
} catch (com.google.api.gax.rpc.ApiException apiException) {
  // Fallback exception handler for other types of ApiException.

  // Gets the standard ErrorInfo payload from the exception.
  ErrorInfo errorInfo = apiException.getErrorDetails().getErrorInfo();
  // Log the 'reason' and 'domain'...

  // Log the details in the 'metadata' map...
  for (Entry<String, String> metadataEntry : errorInfo.getMetadataMap().entrySet()) {
    // Log the metadataEntry key and value...
  }

  // Gets the standard RequestInfo payload from the exception.
  RequestInfo requestInfo = invalidArgumentException.getErrorDetails().getRequestInfo();
  if (requestInfo != null) {
    String requestId = requestInfo.getRequestId();
    // Log the requestId...
  }
  ...
}

แนวทางปฏิบัติแนะนำสำหรับการจัดการข้อผิดพลาด

หากต้องการสร้างแอปพลิเคชันที่มีความยืดหยุ่น ให้ปฏิบัติตามแนวทางปฏิบัติแนะนำต่อไปนี้

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

พิจารณาว่าข้อผิดพลาดเกิดจากปัญหาในการนำไปใช้ (ไคลเอ็นต์) หรือปัญหาเกี่ยวกับ API (เซิร์ฟเวอร์)

  • ข้อผิดพลาดของไคลเอ็นต์: รหัสต่างๆ เช่น INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED ข้อผิดพลาดเหล่านี้ต้องมีการเปลี่ยนแปลงคำขอหรือสถานะ/ข้อมูลเข้าสู่ระบบของแอปพลิเคชัน อย่าลองส่งคำขออีกครั้งโดยไม่แก้ไขปัญหา
  • ข้อผิดพลาดของเซิร์ฟเวอร์: รหัสต่างๆ เช่น UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN ข้อผิดพลาดเหล่านี้บ่งบอกถึงปัญหาชั่วคราวเกี่ยวกับบริการ API
ใช้กลยุทธ์การลองอีกครั้ง

พิจารณาว่าข้อผิดพลาดสามารถลองอีกครั้งได้หรือไม่ และใช้กลยุทธ์การลองอีกครั้ง

  • ลองอีกครั้ง เฉพาะ สำหรับข้อผิดพลาดของเซิร์ฟเวอร์ชั่วคราว เช่น UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN และ ABORTED
  • ใช้อัลกอริทึม Exponential Backoff เพื่อรอช่วงเวลาที่เพิ่มขึ้น ระหว่างการลองอีกครั้ง ซึ่งจะช่วยหลีกเลี่ยงไม่ให้บริการที่ทำงานหนักอยู่แล้วต้องทำงานหนักขึ้น เช่น รอ 1 วินาที จากนั้น 2 วินาที จากนั้น 4 วินาที และรอต่อไปจนกว่าจะถึงจำนวนการลองอีกครั้งสูงสุดหรือเวลารอทั้งหมด
  • เพิ่ม "Jitter" แบบสุ่มเล็กน้อยลงในระยะเวลาหน่วง Exponential Backoff เพื่อป้องกันปัญหา "Thundering Herd" ที่ไคลเอ็นต์จำนวนมากจะลองอีกครั้งพร้อมกัน
บันทึกอย่างละเอียด

บันทึกการตอบกลับข้อผิดพลาดแบบเต็ม รวมถึงเพย์โหลดรายละเอียดมาตรฐานทั้งหมด, โดยเฉพาะรหัสคำขอ ข้อมูลนี้มีความสำคัญอย่างยิ่งสำหรับการแก้ไขข้อบกพร่องและการรายงานปัญหาไปยังทีมสนับสนุนของ Google หากจำเป็น

ให้ความคิดเห็นจากผู้ใช้

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

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

ก่อนหน้า
เข้ารหัสข้อมูลผู้ใช้
ถัดไป
แนวทางปฏิบัติแนะนำ