Package google.rpc

الفهرس

BadRequest

تصف هذه السمة الانتهاكات في طلب العميل. يركّز هذا النوع من الأخطاء على الجوانب النحوية للطلب.

الحقول
field_violations[]

FieldViolation

تصف هذه السمة جميع المخالفات في طلب العميل.

FieldViolation

نوع رسالة يُستخدَم لوصف حقل طلب غير صالح واحد.

الحقول
field

string

مسار يؤدي إلى حقل في نص الطلب ستكون القيمة عبارة عن سلسلة من المعرّفات المفصولة بنقاط والتي تحدّد حقلًا في بروتوكول المخزن المؤقت.

ننصحك باتّباع الخطوات التالية:

message CreateContactRequest {
  message EmailAddress {
    enum Type {
      TYPE_UNSPECIFIED = 0;
      HOME = 1;
      WORK = 2;
    }

    optional string email = 1;
    repeated EmailType type = 2;
  }

  string full_name = 1;
  repeated EmailAddress email_addresses = 2;
}

في هذا المثال، يمكن أن يأخذ field في نموذج البيانات إحدى القيم التالية:

  • ‫full_name لانتهاك في قيمة full_name
  • email_addresses[1].email بسبب مخالفة في الحقل email للرسالة الأولى email_addresses
  • email_addresses[3].type[2] بسبب مخالفة في القيمة الثانية type في الرسالة الثالثة email_addresses

في JSON، يتم تمثيل القيم نفسها على النحو التالي:

  • ‫fullName لانتهاك في قيمة fullName
  • emailAddresses[1].email بسبب مخالفة في الحقل email للرسالة الأولى emailAddresses
  • emailAddresses[3].type[2] بسبب مخالفة في القيمة الثانية type في الرسالة الثالثة emailAddresses
description

string

وصف لسبب عدم صلاحية عنصر الطلب.
reason

string

سبب الخطأ على مستوى الحقل. هذه قيمة ثابتة تحدّد السبب المباشر للخطأ على مستوى الحقل. يجب أن يحدّد بشكل فريد نوع FieldViolation ضمن نطاق google.rpc.ErrorInfo.domain. يجب ألا يزيد عدد الأحرف عن 63 حرفًا وأن يتطابق مع التعبير العادي [A-Z][A-Z0-9_]+[A-Z0-9] الذي يمثّل UPPER_SNAKE_CASE.
localized_message

LocalizedMessage

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

الرمز

رموز الخطأ الأساسية لواجهات برمجة التطبيقات gRPC

في بعض الأحيان، قد تنطبق رموز خطأ متعددة. يجب أن تعرض الخدمات رمز الخطأ الأكثر تحديدًا الذي ينطبق. على سبيل المثال، استخدِم OUT_OF_RANGE بدلاً من FAILED_PRECONDITION إذا كان الرمزان ينطبقان. وبالمثل، يجب تفضيل NOT_FOUND أو ALREADY_EXISTS على FAILED_PRECONDITION.

عمليات التعداد
OK

ليس خطأ، بل يتم عرضه عند النجاح.

ربط HTTP: 200 OK
CANCELLED

تم إلغاء العملية، وعادةً ما يكون ذلك من قِبل المتصل.

ربط HTTP: 499 Client Closed Request
UNKNOWN

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

ربط HTTP: 500 Internal Server Error
INVALID_ARGUMENT

حدّد العميل وسيطة غير صالحة. يُرجى العلم أنّ هذا يختلف عن FAILED_PRECONDITION. يشير INVALID_ARGUMENT إلى الوسيطات التي تسبّب مشاكل بغض النظر عن حالة النظام (مثل اسم ملف غير صالح).

ربط HTTP: طلب غير صالح (400)
DEADLINE_EXCEEDED

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

ربط HTTP: انتهت مهلة البوابة 504
NOT_FOUND

لم يتم العثور على بعض الكيانات المطلوبة (مثل ملف أو دليل).

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

تعيين HTTP: لم يتم العثور على الصفحة (404)
ALREADY_EXISTS

الكيان الذي حاول العميل إنشاءه (مثل ملف أو دليل) متوفّر مسبقًا.

ربط HTTP: 409 Conflict
PERMISSION_DENIED

ليس لدى المتصل إذن لتنفيذ العملية المحدّدة. يجب عدم استخدام PERMISSION_DENIED للرفض الناتج عن استنفاد بعض الموارد (استخدِم RESOURCE_EXHAUSTED بدلاً من ذلك لهذه الأخطاء). يجب عدم استخدام PERMISSION_DENIED إذا تعذّر تحديد هوية المتصل (استخدِم UNAUTHENTICATED بدلاً من ذلك لهذه الأخطاء). لا يعني رمز الخطأ هذا أنّ الطلب صالح أو أنّ العنصر المطلوب متوفّر أو يستوفي شروطًا مسبقة أخرى.

تعيين HTTP: 403 Forbidden
UNAUTHENTICATED

لا يتضمّن الطلب بيانات اعتماد مصادقة صالحة للعملية.

ربط HTTP: 401 غير مصرّح به
RESOURCE_EXHAUSTED

تم استنفاد بعض الموارد، ربما حصة لكل مستخدم، أو ربما نفدت مساحة نظام الملفات بالكامل.

تعيين HTTP: 429 Too Many Requests
FAILED_PRECONDITION

تم رفض العملية لأنّ النظام ليس في الحالة المطلوبة لتنفيذها. على سبيل المثال، الدليل المطلوب حذفه غير فارغ، أو يتم تطبيق عملية rmdir على عنصر ليس دليلاً، وما إلى ذلك.

يمكن لمطوّري الخدمات استخدام الإرشادات التالية لتحديد ما إذا كان يجب استخدام FAILED_PRECONDITION أو ABORTED أو UNAVAILABLE: (أ) استخدِم UNAVAILABLE إذا كان بإمكان العميل إعادة محاولة إجراء المكالمة التي تعذّر إجراؤها فقط. (ب) استخدِم ABORTED إذا كان على العميل إعادة المحاولة على مستوى أعلى. على سبيل المثال، عندما يتعذّر إجراء اختبار وتعيين يحدّدهما العميل، ما يشير إلى أنّه على العميل إعادة تشغيل تسلسل القراءة والتعديل والكتابة. (ج) استخدِم FAILED_PRECONDITION إذا كان على العميل عدم إعادة المحاولة إلى أن يتم إصلاح حالة النظام بشكل صريح. على سبيل المثال، إذا تعذّر تنفيذ الأمر "rmdir" لأنّ الدليل غير فارغ، يجب عرض FAILED_PRECONDITION لأنّه لا يجب أن يعيد العميل المحاولة إلا بعد حذف الملفات من الدليل.

ربط HTTP: طلب غير صالح (400)
ABORTED

تم إلغاء العملية، وعادةً ما يكون ذلك بسبب مشكلة في التزامن، مثل فشل عملية التحقّق من التسلسل أو إلغاء المعاملة.

اطّلِع على الإرشادات أعلاه لتحديد ما إذا كان يجب استخدام FAILED_PRECONDITION أو ABORTED أو UNAVAILABLE.

ربط HTTP: 409 Conflict
OUT_OF_RANGE

تمت محاولة تنفيذ العملية بعد انتهاء النطاق الصالح. على سبيل المثال، البحث عن بيانات أو قراءتها بعد نهاية الملف

على عكس الخطأ INVALID_ARGUMENT، يشير هذا الخطأ إلى مشكلة يمكن حلّها إذا تغيّرت حالة النظام. على سبيل المثال، سينتج نظام الملفات 32 بت INVALID_ARGUMENT إذا طُلب منه القراءة عند إزاحة ليست في النطاق [0,2^32-1]، ولكن سينتج OUT_OF_RANGE إذا طُلب منه القراءة من إزاحة تتجاوز حجم الملف الحالي.

هناك تداخل كبير بين FAILED_PRECONDITION وOUT_OF_RANGE. ننصحك باستخدام OUT_OF_RANGE (الخطأ الأكثر تحديدًا) عندما يكون ذلك منطبقًا حتى يتمكّن المتصلون الذين يكرّرون عملية البحث في مساحة من البحث بسهولة عن خطأ OUT_OF_RANGE لمعرفة وقت انتهاء البحث.

ربط HTTP: طلب غير صالح (400)
UNIMPLEMENTED

لم يتم تنفيذ العملية أو أنّها غير متاحة/مفعّلة في هذه الخدمة.

ربط HTTP: 501 Not Implemented
INTERNAL

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

ربط HTTP: 500 Internal Server Error
UNAVAILABLE

هذه الخدمة غير متاحة حاليًا. من المرجّح أنّ هذه حالة عابرة يمكن تصحيحها من خلال إعادة المحاولة مع التراجع. يُرجى العِلم أنّه ليس من الآمن دائمًا إعادة محاولة تنفيذ العمليات غير المتكرّرة.

اطّلِع على الإرشادات أعلاه لتحديد ما إذا كان يجب استخدام FAILED_PRECONDITION أو ABORTED أو UNAVAILABLE.

ربط HTTP: خطأ 503: الخدمة غير متاحة
DATA_LOSS

ثمة بيانات تالفة أو بيانات مفقودة ويتعذّر استرجاعها.

ربط HTTP: 500 Internal Server Error

ErrorInfo

تصف هذه السمة سبب الخطأ بتفاصيل منظَّمة.

مثال على حدوث خطأ عند التواصل مع واجهة برمجة التطبيقات "pubsub.googleapis.com" عندما تكون غير مفعّلة:

{ "reason": "API_DISABLED"
  "domain": "googleapis.com"
  "metadata": {
    "resource": "projects/123",
    "service": "pubsub.googleapis.com"
  }
}

تشير هذه الاستجابة إلى أنّ واجهة برمجة التطبيقات pubsub.googleapis.com غير مفعّلة.

في ما يلي مثال على خطأ يتم عرضه عند محاولة إنشاء مثيل Spanner في منطقة غير متوفّرة:

{ "reason": "STOCKOUT"
  "domain": "spanner.googleapis.com",
  "metadata": {
    "availableRegions": "us-central1,us-east2"
  }
}
الحقول
reason

string

سبب الخطأ هذه قيمة ثابتة تحدّد السبب المباشر للخطأ. تكون أسباب الخطأ فريدة ضمن نطاق معيّن من الأخطاء. يجب ألا يزيد عدد الأحرف عن 63 حرفًا وأن يتطابق مع التعبير العادي [A-Z][A-Z0-9_]+[A-Z0-9] الذي يمثّل UPPER_SNAKE_CASE.
domain

string

تمثّل هذه السمة المجموعة المنطقية التي ينتمي إليها "السبب". عادةً ما يكون نطاق الخطأ هو اسم الخدمة المسجَّل للأداة أو المنتج الذي يعرض الخطأ. مثال: "pubsub.googleapis.com". إذا تم إنشاء الخطأ بواسطة بعض البنية الأساسية الشائعة، يجب أن يكون نطاق الخطأ قيمة فريدة على مستوى العالم تحدّد البنية الأساسية. بالنسبة إلى بنية Google API الأساسية، يكون نطاق الخطأ هو "googleapis.com".
metadata

map<string, string>

تفاصيل إضافية منظَّمة حول هذا الخطأ

يجب أن تتطابق المفاتيح مع تعبير عادي من [a-z][a-zA-Z0-9-_]+، ولكن من المفترض أن تكون lowerCamelCase. ويجب أيضًا أن يكون طولها 64 حرفًا كحدّ أقصى. عند تحديد القيمة الحالية للحدّ المتجاوز، يجب أن تكون الوحدات مضمّنة في المفتاح وليس في القيمة. على سبيل المثال، بدلاً من {"instanceLimit": "100/request"}، يجب عرض {"instanceLimitPerRequest": "100"} إذا تجاوز العميل عدد المثيلات التي يمكن إنشاؤها في طلب واحد (على شكل دُفعة).

مساعدة

توفّر روابط إلى المستندات أو لتنفيذ إجراء خارج النطاق.

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

الحقول

LocalizedMessage

توفّر هذه السمة رسالة خطأ مترجَمة يمكن إرجاعها بأمان إلى المستخدم ويمكن إرفاقها بخطأ في استدعاء الإجراء عن بُعد (RPC).

الحقول
locale

string

اللغة المستخدَمة وفقًا للمواصفات المحدّدة في https://www.rfc-editor.org/rfc/bcp/bcp47.txt أمثلة: "en-US" أو "fr-CH" أو "es-MX"
message

string

رسالة الخطأ المترجَمة باللغة المحدّدة أعلاه

RequestInfo

يحتوي على بيانات وصفية حول الطلب يمكن للعملاء إرفاقها عند الإبلاغ عن خطأ أو تقديم أشكال أخرى من الملاحظات.

الحقول
request_id

string

سلسلة غير شفافة يجب أن تفسّرها الخدمة التي تنشئها فقط. على سبيل المثال، يمكن استخدامها لتحديد الطلبات في سجلّات الخدمة.
serving_data

string

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

الحالة

يحدّد نوع Status نموذجًا منطقيًا للتعامل مع الأخطاء، يناسب بيئات البرمجة المختلفة مثل REST API وRPC API. يتم استخدامه من خلال gRPC. تتكون رسالة Status من ثلاثة أجزاء من البيانات، هي رمز الخطأ ورسالته وتفاصيله.

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

الحقول
code

int32

هو رمز الحالة، ويجب أن يكون قيمة محدّدة مسبقًا من google.rpc.Code.
message

string

يشير إلى رسالة خطأ موجّهة للمطوّرين، ويجب أن تكون الرسالة بالإنجليزية. أما رسائل الخطأ الموجّهة للمستخدمين، فيجب ترجمتها وإرسالها في حقل google.rpc.Status.details أو ترجمتها من قِبل العميل.
details[]

Any

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