تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

التعرّف على أخطاء واجهة برمجة التطبيقات

يوضّح هذا الدليل كيفية تعامل Data Manager API مع الأخطاء وكيفية إبلاغك بها. إنّ فهم بنية أخطاء واجهة برمجة التطبيقات ومعناها أمر بالغ الأهمية لإنشاء تطبيقات قوية يمكنها التعامل مع المشاكل بسلاسة، بدءًا من الإدخال غير الصالح إلى عدم توفّر الخدمة مؤقتًا.

تتّبع Data Manager API نموذج الخطأ العادي في Google API، والذي يستند إلى رموز الحالة في gRPC. يتضمّن كل ردّ من واجهة برمجة التطبيقات يؤدي إلى حدوث خطأ كائن Status يتضمّن ما يلي:

رمز خطأ رقمي
رسالة خطأ
تفاصيل إضافية اختيارية عن الخطأ

رموز الخطأ الأساسية

تستخدم Data Manager API مجموعة من رموز الخطأ الأساسية التي يحدّدها gRPC وHTTP. تقدّم هذه الرموز إشارة عامة إلى نوع الخطأ. يجب دائمًا التحقّق من هذا الرمز أولاً لفهم الطبيعة الأساسية للمشكلة.

لمزيد من التفاصيل حول هذه الرموز، يُرجى الاطّلاع على دليل تصميم واجهة برمجة التطبيقات - رموز الخطأ.

نموذج الفشل السريع

تستخدم Data Manager API نموذج الإيقاف السريع. إذا كان الطلب يتضمّن أخطاء بنيوية أو إذا تعذّر التحقّق من صحة أي سجلّ لحقل مطلوب، سيتعذّر تنفيذ الطلب بأكمله، ولن تعالج واجهة برمجة التطبيقات أيًا من البيانات الواردة في هذا الطلب.

المقارنة مع نموذج الفشل الجزئي

يختلف نموذج الإيقاف السريع عن نموذج الإيقاف الجزئي في بعض واجهات برمجة التطبيقات الأخرى من Google، مثل Google Ads API وCampaign Manager 360 API. في نموذج الفشل الجزئي، ينجح الطلب حتى إذا كانت بعض السجلات تتضمّن أخطاء، ويحتوي الردّ على تفاصيل الخطأ للسجلات التي تعذّر تنفيذها.

على الرغم من أنّ الفشل الجزئي قد يكون مناسبًا، إلا أنّه ينطوي على مخاطر كبيرة لأنّ نموذج الفشل الجزئي لا ينبّهك بشكل استباقي إلى الأخطاء، بل عليك التحقّق من الأخطاء بشكل صريح في كل ردّ. ويمكن أن يؤدي ذلك إلى إخفاء مشاكل مهمة لأنّ الطلب ينجح حتى إذا رفضت واجهة برمجة التطبيقات العديد من السجلات أو حتى جميعها في الطلب. إذا كان جزء كبير من السجلات في الطلب يتضمّن أخطاء ولم تفحص الاستجابة، قد لا تدرك تمامًا المشاكل المنتشرة في بياناتك، ولن تكتشف هذه المشاكل إلا بعد أيام أو أسابيع عندما لا تتوافق النتائج التراكمية مع توقعاتك.

يتجنّب نموذج الإيقاف السريع هذه المشاكل من خلال تنبيهك فورًا إلى المشاكل المتعلّقة ببياناتك أو عملية الدمج، ما يتيح لك اتّخاذ الإجراء المناسب.

البحث عن أخطاء التوقف السريع باستخدام `validateOnly`

تتيح معظم طلبات الإضافة والإزالة استخدام الحقل validateOnly. عند ضبط validateOnly على true، تنفّذ واجهة برمجة التطبيقات Data Manager API عمليات التحقّق الأساسية نفسها التي تنفّذها عند تلقّي طلب عادي، ولكنّها لا تستوعب أي بيانات أو تزيلها.

إذا كان الطلب يتضمّن أخطاء، سيتعذّر تنفيذه وسيتم عرض استجابة الخطأ نفسها التي تتلقّاها من طلب عادي.
إذا اجتاز الطلب عملية التحقّق من الصحة، سينجح. تتضمّن الاستجابة أي fieldWarnings للحقول الاختيارية، تمامًا مثل الطلب العادي.

استخدِم validateOnly لإجراء ما يلي:

اختبار عملية دمج جديدة أو معدَّلة بدون التأثير في بياناتك المباشرة
تأكَّد من أنّ الإصلاح يحلّ الخطأ قبل إعادة إرسال الطلب.

التعامل مع الأخطاء

اتّبِع الخطوات التالية عند تعذُّر تنفيذ طلب:

اطّلِع على رمز الخطأ لمعرفة نوع الخطأ.
- إذا كنت تستخدم gRPC، سيكون رمز الخطأ في الحقل code من Status. إذا كنت تستخدم مكتبة برامج للعميل، قد تعرض نوعًا محدّدًا من الاستثناءات يتوافق مع رمز الخطأ. على سبيل المثال، تعرض مكتبة برامج Java com.google.api.gax.rpc.InvalidArgumentException إذا كان رمز الخطأ INVALID_ARGUMENT.
- إذا كنت تستخدم REST، سيكون رمز الخطأ في استجابة الخطأ في error.status، وستكون حالة HTTP المقابلة في error.code.
ملاحظة مهمة: تستخدِم واجهة Data Manager API نموذج الإيقاف السريع. في حال تعذّر تنفيذ الطلب، لن تتم معالجة أي من البيانات. يُرجى إصلاح الخطأ وإعادة إرسال الطلب بالكامل.
ابحث عن حمولة التفاصيل العادية الخاصة برمز الخطأ. حمولة التفاصيل العادية هي مجموعة من الرسائل المتعلقة بالأخطاء الناتجة عن Google APIs. وتقدّم لك تفاصيل الأخطاء بطريقة منظَّمة ومتسقة. قد يتضمّن كل خطأ من أخطاء Data Manager API عدة رسائل بيانات أساسية. تحتوي مكتبات عملاء Data Manager API على طُرق مساعدة للحصول على حمولات التفاصيل العادية من أحد الأخطاء.

بغض النظر عن رمز الخطأ، ننصحك بالتحقّق من حمولات ErrorInfo وRequestInfo وHelp وLocalizedMessage وتسجيلها.
- يحتوي ErrorInfo على معلومات قد لا تكون متوفرة في حمولات أخرى.
- تحتوي RequestInfo على رقم تعريف الطلب، وهو مفيد إذا كنت بحاجة إلى التواصل مع فريق الدعم.
- يحتوي الرمز Help والرمز LocalizedMessage على روابط وتفاصيل أخرى لمساعدتك في حلّ الخطأ.
بالإضافة إلى ذلك، يكون حمولة BadRequest مفيدة في ما يتعلّق بأخطاء INVALID_ARGUMENT، لأنّها تقدّم معلومات عن الحقول التي تسبّبت في حدوث الخطأ.

تحذيرات بشأن عملية نقل البيانات

تقبل Data Manager API أكبر قدر ممكن من طلبات النقل. إذا أدرجت بيانات غير مطلوبة، لن تؤدي أخطاء التحقّق من صحة هذه الحقول إلى تعذُّر تنفيذ الطلب. على سبيل المثال، إذا كان أحد عناصر سلة التسوّق لا يتضمّن معرّف منتج التاجر، ستعالج واجهة برمجة التطبيقات بقية الطلب وتعرض تحذيرًا.

تتضمّن استجابة الإدخال الناجحة (رمز حالة HTTP 200) هذه التحذيرات في قائمة fieldWarnings. كل إدخال هو كائن FieldWarning يتضمّن الحقول التالية:

field

موقع الحقل في الطلب، بتنسيق snake case للمسار

إذا كان المسار يشير إلى عنصر في قائمة (حقل repeated)، سيظهر فهرسه بين قوسين مربّعين ([...]) بعد اسم القائمة.

على سبيل المثال، يشير events.events[0].cart_data.items[0].merchant_product_id إلى تحذير مرتبط بالعنصر الأول في بيانات سلة التسوّق الخاصة بالحدث الأول في الطلب.

description

توضيح لسبب ظهور تحذير بسبب القيمة المقدَّمة

reason

قيمة التعداد WarningReason التي تحدّد نوع التحذير.

مثال مع `FieldWarning`

في ما يلي نموذج استجابة لطلب استيعاب ناجح يتضمّن تحذيرًا لأنّه لم يتم توفير معرّف منتج التاجر لأحد عناصر سلّة التسوّق.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a",
  "fieldWarnings": [
    {
      "field": "events.events[0].cart_data.items[0].merchant_product_id",
      "description": "The merchant product ID is missing in the cart item.",
      "reason": "WARNING_REASON_CART_DATA_ITEM_MERCHANT_PRODUCT_ID_MISSING"
    }
  ]
}

حمولة التفاصيل العادية

في ما يلي حمولات التفاصيل العادية الأكثر شيوعًا لواجهة Data Manager API:

BadRequest
RequestInfo
ErrorInfo
‫Help وLocalizedMessage

`BadRequest`

ابحث عن حمولة BadRequest عندما يتعذّر تنفيذ طلب بسبب الخطأ INVALID_ARGUMENT (رمز حالة HTTP‏ 400).

تعرض الرسالة BadRequest أنّ الطلب يتضمّن حقولاً ذات قيم غير صالحة أو أنّه لا يتضمّن قيمة لحقل مطلوب. راجِع قائمة field_violations في BadRequest لمعرفة الحقول التي تتضمّن أخطاء. يحتوي كل إدخال field_violations على معلومات لمساعدتك في إصلاح الخطأ:

field

موقع الحقل في الطلب، بتنسيق snake case للمسار

إذا كان المسار يشير إلى عنصر في قائمة (حقل repeated)، سيظهر فهرسه بين قوسين مربّعين ([...]) بعد اسم القائمة.

على سبيل المثال، destinations[0].operating_account.account_id هو account_id في operating_account الخاص بالعنصر الأول في قائمة destinations.

description

توضيح لسبب تسبُّب القيمة في حدوث خطأ

reason

تُستخدَم السمة ErrorReason من النوع enum، مثل 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 خطأين:

يحتوي event الأول على قيمة غير مشفّرة بنظام الست عشري في معرّف المستخدم الثاني للحدث.
يحتوي event الثاني على قيمة غير مشفّرة بنظام الستة عشر على معرّف المستخدم الثالث للحدث.

{
  "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 الذي يحدّد طلب البيانات من واجهة برمجة التطبيقات بشكل فريد.

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

عند تسجيل الأخطاء أو التواصل مع فريق الدعم، احرص على تضمين معرّف الطلب للمساعدة في تشخيص المشاكل.

`ErrorInfo`

ابحث عن الرسالة ErrorInfo لاسترداد معلومات إضافية قد لا يتم تسجيلها في حمولات التفاصيل العادية الأخرى. تحتوي البيانات الأساسية ErrorInfo على خريطة metadata تتضمّن معلومات عن الخطأ.

على سبيل المثال، إليك ErrorInfo لخطأ PERMISSION_DENIED ناتج عن استخدام بيانات اعتماد لمشروع على Google Cloud لم يتم تفعيل 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"
        }
      },
      ...
    ]
  }
}

أخطاء متعلقة بسقف الحصص وحدود المعدّل

عندما يتجاوز الطلب أحد حدود المشروع، تعرض واجهة برمجة التطبيقات RESOURCE_EXHAUSTED خطأً (رمز حالة HTTP 429). يقدّم حمولة ErrorInfo تفاصيل حول الحدّ الذي تم تجاوزه في خريطة metadata:

consumer: مشروع Google Cloud المرتبط بالطلب، بالتنسيق projects/PROJECT_NUMBER
quota_limit: اسم سقف الاستخدام الذي تم تجاوزه، مثل IngestionMutateRequestsPerMinutePerProject أو IngestionMutateRequestsPerDayPerProject يمكنك استخدام هذه القيمة لتحديد ما إذا كان التطبيق قد تجاوز الحدّ الأقصى المسموح به في الدقيقة أو الحدّ الأقصى اليومي. للاطّلاع على القائمة الكاملة بأسماء الحدود القصوى، يُرجى الرجوع إلى حدود المشاريع.
quota_location: الموقع الجغرافي الذي يتم فيه تطبيق الحصة. بالنسبة إلى Data Manager API، تكون القيمة دائمًا global.
quota_metric: المقياس المرتبط بالحدّ الأقصى، مثل datamanager.googleapis.com/ingestion_mutate_requests
service: اسم الخدمة، datamanager.googleapis.com

في ما يلي مثال على استجابة الخطأ RESOURCE_EXHAUSTED عندما يتجاوز الطلب الحدّ المسموح به في الدقيقة لطلبات التعديل الخاصة بعملية الاستيعاب:

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric 'Ingestion mutate requests' and limit 'Ingestion mutate requests per minute' of service 'datamanager.googleapis.com' for consumer 'project_number:PROJECT_NUMBER'.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RATE_LIMIT_EXCEEDED",
        "domain": "googleapis.com",
        "metadata": {
          "consumer": "projects/PROJECT_NUMBER",
          "quota_limit": "IngestionMutateRequestsPerMinutePerProject",
          "quota_location": "global",
          "quota_metric": "datamanager.googleapis.com/ingestion_mutate_requests",
          "service": "datamanager.googleapis.com"
        }
      }
    ]
  }
}

`Help` و`LocalizedMessage`

ابحث عن حمولات Help وLocalizedMessage للحصول على روابط تؤدي إلى مستندات ورسائل خطأ مترجَمة تساعدك في فهم الخطأ وإصلاحه.

على سبيل المثال، إليك الرمزين Help وLocalizedMessage لخطأ PERMISSION_DENIED ناتج عن استخدام بيانات اعتماد لمشروع على السحابة الإلكترونية Google Cloud لم يتم تفعيل 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...

            // If handling a rate limit error, check the exceeded quota limit:
            if (errorInfo.Reason == "RATE_LIMIT_EXCEEDED" &&
                errorInfo.Metadata.TryGetValue("quota_limit", out string quotaLimit))
            {
                // Inspect quotaLimit to determine whether it is a per-minute
                // or daily limit (for example,
                // IngestionMutateRequestsPerMinutePerProject).
            }

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

جافا

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'...

  // If handling a rate limit error, check the exceeded quota limit:
  if (errorInfo != null && "RATE_LIMIT_EXCEEDED".equals(errorInfo.getReason())) {
    String quotaLimit = errorInfo.getMetadataMap().get("quota_limit");
    // Inspect quotaLimit to determine whether it is a per-minute
    // or daily limit (for example,
    // IngestionMutateRequestsPerMinutePerProject).
  }

  // 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 = apiException.getErrorDetails().getRequestInfo();
  if (requestInfo != null) {
    String requestId = requestInfo.getRequestId();
    // Log the requestId...
  }
  ...
}

أفضل الممارسات المتعلّقة بمعالجة الأخطاء

لإنشاء تطبيقات مرنة، اتّبِع أفضل الممارسات التالية.

التحقّق من صحة المعلومات قبل الإرسال

عند إنشاء عملية دمج أو تغييرها، أرسِل طلبات مع ضبط validateOnly على true لرصد أخطاء الإيقاف السريع قبل استيعاب البيانات.

فحص تفاصيل الخطأ

ابحث دائمًا عن إحدى حمولة التفاصيل العادية، مثل BadRequest. تحتوي كل حمولة تفاصيل عادية على معلومات تساعدك في فهم سبب الخطأ.

التمييز بين أخطاء العميل وأخطاء الخادم

حدِّد ما إذا كان الخطأ ناتجًا عن مشكلة في عملية التنفيذ (العميل) أو مشكلة في واجهة برمجة التطبيقات (الخادم).

أخطاء العميل: رموز مثل INVALID_ARGUMENT وNOT_FOUND وPERMISSION_DENIED وFAILED_PRECONDITION وUNAUTHENTICATED تتطلّب هذه الأخطاء إجراء تغييرات على الطلب أو حالة/بيانات اعتماد تطبيقك. لا تعِد محاولة إرسال الطلب بدون حلّ المشكلة.
أخطاء الخادم: رموز مثل UNAVAILABLE وINTERNAL وDEADLINE_EXCEEDED وUNKNOWN تشير هذه الرموز إلى حدوث مشكلة مؤقتة في خدمة واجهة برمجة التطبيقات.

تنفيذ استراتيجية إعادة المحاولة

تحديد ما إذا كان يمكن إعادة محاولة تنفيذ العملية التي أدّت إلى حدوث الخطأ، واستخدام استراتيجية إعادة المحاولة

أعِد المحاولة فقط في حال حدوث أخطاء مؤقتة في الخادم (مثل UNAVAILABLE وDEADLINE_EXCEEDED وINTERNAL وUNKNOWN وABORTED) وفي حال فرض حدود معدّل لكل دقيقة (RESOURCE_EXHAUSTED مع RATE_LIMIT_EXCEEDED).
بالنسبة إلى حدود المعدّل، افحص quota_limit في ErrorInfo:
- إذا كان الحدّ الأقصى في الدقيقة (مثل IngestionMutateRequestsPerMinutePerProject)، أوقِف الطلبات مؤقتًا وأعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي مع التشويش.
- إذا كان الحدّ يوميًا (مثل IngestionMutateRequestsPerDayPerProject)، لا تعِد المحاولة على الفور. إيقاف المعالجة مؤقتًا إلى أن تتم إعادة ضبط الحصة اليومية في منتصف الليل بتوقيت المحيط الهادئ
استخدِم خوارزمية الرقود الأسي الثنائي للانتظار لفترات زمنية متزايدة بين عمليات إعادة المحاولة. يساعد ذلك في تجنُّب إرهاق خدمة مضغوطة بالفعل. على سبيل المثال، الانتظار لمدة ثانية واحدة، ثم ثانيتين، ثم أربع ثوانٍ، وهكذا حتى الوصول إلى الحد الأقصى لعدد محاولات إعادة الإرسال أو إجمالي وقت الانتظار.
أضِف مقدارًا صغيرًا وعشوائيًا من "التشوّش" إلى فترات التأخير في التراجع لمنع حدوث مشكلة "القطيع الصاخب" حيث يعيد العديد من العملاء المحاولة في الوقت نفسه.

تسجيل البيانات بدقة

سجِّل استجابة الخطأ الكاملة، بما في ذلك جميع حمولات التفاصيل العادية، خاصةً معرّف الطلب. هذه المعلومات ضرورية لتحديد المشاكل وحلّها وإبلاغ فريق الدعم في Google بها عند الحاجة.

تقديم ملاحظات المستخدمين

استنادًا إلى الرموز والرسائل الواردة في حمولة التفاصيل العادية، قدِّم ملاحظات واضحة ومفيدة لمستخدمي تطبيقك. على سبيل المثال، بدلاً من قول "حدث خطأ"، يمكنك قول "لم يتم العثور على معرّف المعاملة" أو "لم يتم العثور على رقم تعريف حساب الوجهة".

من خلال اتّباع هذه الإرشادات، يمكنك تشخيص الأخطاء التي تعرضها واجهة برمجة التطبيقات Data Manager والتعامل معها بفعالية، ما يؤدي إلى إنشاء تطبيقات أكثر استقرارًا وسهولة في الاستخدام.

تشفير بيانات المستخدمين

أفضل الممارسات