|

تمت ترقية وتحسين وثائق استعلام معرّف الطلب في APIYI: طريقتان للحصول عليه من نص الخطأ ورؤوس الاستجابة

تمت ترقية وتحسين وثائق استعلام معرّف الطلب في APIYI: طريقتان للحصول عليه من نص الخطأ ورؤوس الاستجابة

ملاحظة الكاتب: تمت ترقية وثائق الاستعلام عن Request ID في APIYI. توضح هذه المقالة أي سلسلة يجب نسخها عند حدوث خطأ، وأي المعرّفات لا يمكن استخدامها، وكيفية حفظ task_id الخاص بالفيديو غير المتزامن، وما المواد التي يجب إضافتها عندما لا تظهر السجلات.

عند فتح تذكرة دعم بعد خطأ في الاستدعاء، غالبًا ما يتوقف المطورون عند المشكلة نفسها: بحوزتهم سلسلة معرّف (ID)، لكن فريق الدعم لا يجدها في السجلات. السبب في الغالب هو أنهم نسخوا X-Request-Id الخاص بالمزوّد الأصلي upstream، بدلًا من X-Shellapi-Request-Id الخاص بـ APIYI. وقد أُعيدت كتابة الوثائق الجديدة لحل هذه المشكلة بالتحديد، وعنوانها docs.apiyi.com/faq/request-id-troubleshooting.

هذا ليس تحديثًا شكليًا للوثائق. النسخة القديمة كانت تبدأ من “رؤوس الاستجابة” وتمتلئ بعبارات مثل “عادةً” و”قد”، وبعد قراءتها لا تزال لا تعرف من أين تنسخ. أما النسخة الجديدة فقد عكست الترتيب: تعطي الجواب أولًا، ثم طريقة الحصول عليه، وأخيرًا قالب تذكرة الدعم.

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

apiyi-request-id-docs-upgrade-ar-image-0


ما الذي تغيّر في ترقية توثيق Request ID في APIYI

الجملة الأولى في النسخة الجديدة من التوثيق تحمل الجواب مباشرة: قيمة Request ID في APIYI هي ترويسة الاستجابة X-Shellapi-Request-Id، وعند حدوث خطأ يظهر نفس القيمة في نهاية رسالة الخطأ . والصفحة القديمة كانت تصف x-request-id في أكثر من موضع بأنه “قيمة تُسجّلها لتسهيل التتبع”، وقد صُحّحت هذه الصياغة في التحديث الحالي.

بند المعلومات التفاصيل
وقت التحديث 2026-11-16
موضع التوثيق الصفحة الجديدة «تتبّع Request ID» في قسم FAQ
الجواب الأساسي Request ID = ترويسة الاستجابة X-Shellapi-Request-Id، والقيمة (request id: ...) في نهاية رسالة الخطأ هي القيمة نفسها
المحتوى المضاف طريقتان لاستخراج القيمة، جدول مقارنة المعرّفات، عدم ظهور المعرّف في سجلات لوحة التحكم، توضيح فيديو الطلبات غير المتزامنة، ما تفعله إذا لم تجد المعرّف، قالب تذكرة الدعم
ملاحظة أمنية Request ID ليس مفتاحًا، ويمكن لصقه في تذكرة الدعم أو المحادثة أو لقطة الشاشة؛ أما ما لا يجوز مشاركته خارجيًا فهو مفتاح API الكامل الذي يبدأ بـ sk-
الفئات المتأثرة كل المطورين الذين يستدعون عبر APIYI واجهات النصوص والصور وEmbedding وClaude Messages وResponses وواجهات الفيديو غير المتزامنة

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


Request ID في APIYI: أي سلسلة يجب نسخها الآن؟ مساران

تحقّق من الصيغة أولًا: يبدأ Request ID في APIYI بطابع زمني UTC من 14 خانة. على سبيل المثال 2026111602224568279882196e93ae3kTS58ypN، وأول 14 خانة 20261116022245 تمثل 2026-11-16 02:22:45 UTC، أي 10:22:45 بتوقيت بكين. قارن هذه البادئة بوقت الاستدعاء الخاص بك، وستعرف غالبًا ما إذا كنت قد نسخت السلسلة الخاطئة.

apiyi-request-id-docs-upgrade-ar-image-1

المسار الأول: النسخ مباشرة من JSON الخطأ

هذا المسار مناسب لمعظم مستخدمي تطبيقات العميل. عند وقوع خطأ، ستجد في نهاية حقل message ضمن JSON الخطأ مقطعًا بالصيغة (request id: ...)؛ انسخ السلسلة كاملة الموجودة بين القوسين.

  1. اعثر على JSON الخطأ الكامل في تطبيق العميل أو مخرجات السجل.
  2. حدّد نهاية حقل message.
  3. انسخ السلسلة كاملة التي تأتي بعد request id: دون قطعها.

سجلات لوحة التحكم: تؤكد الاستدعاء لكنها لا تعرض Request ID

كثيرون تكون ردة فعلهم الأولى البحث عن المعرّف في صفحة «السجلات» بلوحة التحكم. وقد خصصت الوثائق الجديدة قسمًا لذلك: صفحة السجلات لا تعرض X-Shellapi-Request-Id، ولا يوجد فيها مدخل للبحث به.

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

لذا عند الإبلاغ عن مشكلة، لا يأتي المعرّف إلا من مصدرين: نص الخطأ (المسار الأول) وترويسات الاستجابة (المسار الثاني). أما السجلات فتُستخدم لتكميل بيانات الوقت والنموذج والرمز والتكلفة.

المسار الثاني: قراءة ترويسة الاستجابة داخل الكود

عند جمع تقارير الأخطاء آليًا، يُستحسن تسجيل هذه الترويسة مباشرة في الكود. في جميع الطرق يجب أن يكون Base URL هو https://api.apiyi.com/v1.

  1. cURL: أضف curl -D headers.txt لكتابة ترويسات الاستجابة في ملف، ثم ابحث في الملف عن x-shellapi-request-id. وللفحص المؤقت يمكنك أيضًا استخدام curl -i للطباعة مباشرة.
  2. Python requests: بعد الحصول على كائن الاستجابة، اقرأ r.headers.get("x-shellapi-request-id"). ويمكنك قراءته في حالتي النجاح والخطأ.
  3. OpenAI SDK (Python): القيمة _request_id في الاستجابة العادية تقرأ x-request-id، وهي عادةً فارغة على APIYI. الطريقة الصحيحة هي استخدام client.chat.completions.with_raw_response.create(...)، ثم قراءة raw.headers.get("x-shellapi-request-id")، وأخذ النتيجة عبر raw.parse(). وعند حدوث خطأ اقرأ e.response.headers داخل except openai.APIStatusError as e.
  4. Node.js: عند استخدام fetch اقرأ res.headers.get("x-shellapi-request-id").
  5. Postman: بعد إرسال الطلب افتح تبويب Headers في منطقة الاستجابة، وابحث عن X-Shellapi-Request-Id.
  6. واجهة المتصفح الأمامية: استدعاءات النطاقات المتقاطعة تخضع لقيود CORS، لذا لا يستطيع JS قراءة هذه الترويسة. يمكنك تسجيلها في وكيل خلفي، أو عرضها في أدوات المطور ضمن Network ← الطلب ← Response Headers.

🚀 بداية سريعة: للتأكد من أن كودك يستطيع قراءة هذه الترويسة، استخدم رمزًا مميزًا من APIYI apiyi.com وأرسل طلبًا مصغرًا، وانظر هل يطبع معرّفًا يبدأ بطابع زمني من 14 رقمًا. هذه الخطوة تستهلك كمية قليلة من التوكنات، ويُفضّل اختيار موجه بإخراج قصير جدًا.


أي معرفات ليست Request ID الخاصة بـ APIYI

قد يظهر في الاستجابة الواحدة عدة أنواع من “المعرفات” في آن واحد، وكثير من تذاكر الدعم تتعثر عند هذه النقطة بالتحديد. الوثائق الجديدة تضمّن جدول مقارنة، وفيما يلي نلخّص أهم نقاطه.

apiyi-request-id-docs-upgrade-ar-image-2

الحقل المصدر هل يصلح للإبلاغ عن مشكلة والبحث في السجلات علامة التعرّف
X-Shellapi-Request-Id APIYI ✅ هو المطلوب يبدأ بـ 14 خانة زمنية بتوقيت UTC
X-Oneapi-Request-Id الطبقة الوسيطة ❌ اسم الترويسة مختلف
X-Request-Id المزوّد الأصلي ❌ لا يمكن العثور عليه في سجلات APIYI غالبًا يبدأ بـ req_ أو يكون UUID
ترويسات مخصّصة من قنوات أخرى القناة ❌ أسماء الترويسات متعددة
id في جسم الاستجابة Completion ID / Response ID ❌ يبدأ بـ chatcmpl- أو resp_
generation_id للصورة نتيجة توليد الصور ❌ موجود داخل جسم الاستجابة
task_id المهمة غير المتزامنة ❌ ليس Request ID، لكن يجب تقديمه معه لمتابعة المهمة والتحقق من خصم الرسوم

قاعدة التمييز بسيطة: كل ما لا يبدأ بـ 14 خانة زمنية ليس Request ID الخاص بـ APIYI. وإذا كان المعرف الذي لديك يبدأ بـ req_، فمن المحتمل أن الطلب وصل مباشرة إلى OpenAI الرسمية. في هذه الحالة، تحقّق أولاً من أن Base URL مكتوب بالشكل https://api.apiyi.com/v1.


كيف نفصل بين تخزين task_id و Request ID في الفيديوهات غير المتزامنة

يمر الفيديو غير المتزامن بخطوتين: “الإرسال” و”الاستعلام”، وكل خطوة تُرجع قيمة جديدة من X-Shellapi-Request-Id، إضافةً إلى معرّف المهمة (task ID)، ما يجعل الخلط بينها أمرًا واردًا. وتوصي الوثائق الجديدة بما يلي: احفظ Request ID الخاص بطلب الإرسال ومعرّف المهمة المستخدم في الاستعلام بشكل منفصل.

النموذج موضع معرّف المهمة واجهة الاستعلام الحقول الأكثر التباسًا
Seedance الحقل id في المستوى الأعلى من جسم الاستجابة (الحقل لا يُسمى task_id) GET /seedance/api/v3/contents/generations/tasks/{id} —
Wan / HappyHorse output.task_id GET /v1/tasks/{task_id} الحقل request_id في جسم الاستجابة يعود إلى المنبع وليس ذلك المسجّل في سجلات APIYI

عند التخزين الفعلي، يُنصح بحفظ 3 حقول لكل مهمة: X-Shellapi-Request-Id عند الإرسال، ومعرّف المهمة، ووقت الإرسال. ويمكن تسجيل Request ID الذي يُرجع عند الاستعلام عن المهمة عند الحاجة. وعند فشل الإرسال، استخدم Request ID للإبلاغ عن المشكلة؛ وعندما تتعطل المهمة أو يشتبه في أمر يتعلق بالخصم، ستحتاج إلى معرّف المهمة للاستعلام عن المهمة وعن الخصم معًا.


ما يجب إضافته عندما لا يظهر Request ID في السجل

حتى لو حصلت على الـ ID، فليس مضمونًا أن تجده في السجل. الوثائق الجديدة أفردت قسمًا مستقلًا لحالة «لا يوجد Request ID في سجل الكونسول»، وهناك حالات أخرى لعدم العثور عليه يمكن التعامل معها على النحو التالي.

الحالة السبب ما يجب إضافته
يفشل الطلب قبل استلام الاستجابة DNS، أو TCP/TLS، أو رفض الوكيل، أو مهلة العميل — فلا توجد ترويسة استجابة أصلاً نص الخطأ كما هو، ووقت الاستدعاء، ووصف بيئة الشبكة
العميل يعرض «فشل الطلب» فقط العميل لا يُظهر الخطأ الأصلي احصل على الـ ID عبر المسار الأول أو الثاني؛ والسجل لا يستطيع إلا تأكيد ما إذا وصل الاستدعاء أم لا
الـ ID يبدأ بـ req_ قد يكون الطلب قد وصل إلى OpenAI الرسمي تحقق من Base URL ثم أعد المحاولة
لا يمكن العثور عليه في السجل أيضًا خارج فترة الاحتفاظ، أو أن الـ ID الذي حصلت عليه خاطئ تحقق من صيغة الـ ID؛ فالسجل يحتفظ بالشهر الحالي والشهرين الطبيعيين السابقين فقط

نقطة أخرى: صفحة الكونسول لا تعرض الـ ID، لكن واجهة استعلام السجلات يمكنها البحث بواسطة request_id. الجدول التالي يوثّق عملية تحقق من استدعاء حقيقي بتاريخ 2026-11-16، باستخدام الموديلين deepseek-flash و gpt-image-2، مع إرسال الطلبات إلى https://api.apiyi.com/v1.

الاستدعاء حالة HTTP ترويسة الاستجابة نتيجة الاستعلام في السجل بواسطة request_id
deepseek-flash غير متدفق 200 توجد x-shellapi-request-id، ولا توجد x-request-id استعلام دقيق يعيد سطر استهلاك واحدًا
deepseek-flash متدفق 200 موجودة، ويمكن قراءتها قبل أول كتلة data: —
gpt-image-2، size=999×999 400 نفس قيمة request id في نهاية message 3 أسطر خطأ/إعادة محاولة، بلا سطر استهلاك
اسم موديل غير موجود 503 نفس قيمة request id في نهاية message لا يمكن العثور على أي سطر

الخلاصة: صفحة السجل في الكونسول لا تعرض Request ID، لكن واجهة استعلام السجلات تستطيع العثور على «سطر الاستهلاك» و«سطر الخطأ» عبر request_id، وليس مضمونًا أن تجد شيئًا في كل مرة. الطلبات التي وصلت إلى القناة ثم فشلت عند القناة نفسها (مثل خطأ في المعاملات) تترك سطر خطأ. أما الطلبات التي رُفضت فورًا عند طبقة البوابة (مثل عدم وجود قناة متاحة) فقد لا تترك أي سطر. وعندما لا تجد شيئًا، استخدم الـ ID الموجود في ترويسة الاستجابة أو في نص الخطأ، مع وقت الاستدعاء، لتكملة المواد.

إذا احتاج فريق الدعم إلى إعادة إنتاج المشكلة، يمكنك على APIYI apiyi.com استدعاء النموذج مرة أخرى بالرمز نفسه ومجموعة المعاملات نفسها، أو تغيير الموديل لمقارنة ما إذا كان الخطأ نفسه يتكرر. إعادة الإنتاج تستهلك tokens أيضًا، فتذكّر أن تسجّل Request ID لكل عملية إعادة إنتاج.

🎯 اقتراح للتشخيص: عند إعادة إنتاج الخطأ، ثبّت Base URL على https://api.apiyi.com/v1، وسجّل في كل مرة X-Shellapi-Request-Id ووقت الاستدعاء. ثم قدّم الـ ID مع وقت الاستدعاء إلى فريق الدعم، ليبحث الفريق في الخلفية بواسطة الـ ID، فيُحدَّد بسرعة أكبر ما إذا كان الخطأ قد حدث في طبقة البوابة أم في طبقة القناة.

قالب تذكرة الإبلاغ عن خطأ Request ID في APIYI

انسخ الحقول التالية مباشرةً وأدخلها في التذكرة:

  • Request ID: السلسلة التي تبدأ بالطابع الزمني المكوّن من 14 خانة
  • النموذج: مثل gpt-image-2
  • نقطة النهاية: مثل POST /v1/chat/completions
  • الوقت: مع المنطقة الزمنية، مثل 2026-11-16 11:24:04 UTC+8
  • حالة HTTP: مثل 400 / 503
  • رسالة الخطأ: الصق نص الخطأ كاملاً، بما في ذلك (request id: ...)
  • ما جُرّب بالفعل: مثل تغيير النموذج، أو التحقق من Base URL، أو إعادة المحاولة مرتين
  • task_id (للمهام غير المتزامنة للفيديو فقط): معرّف المهمة الذي أرجعه طلب الإرسال

انتبه إلى نقطتين: لا تُرسل مفتاح API كاملاً؛ وإذا كان جسم الطلب أو الصورة يحتوي على بيانات خاصة، فاحذفها قبل الإرسال.


أثر ترقية وثائق Request ID على المطورين

الأثر على المطورين

  • تقليل جولات الإبلاغ عن الأعطال: يُدخل المعرّف الصحيح من المرة الأولى، فلا يضطر فريق الدعم إلى العودة والسؤال مرة أخرى.
  • مستخدمو SDK لن يحصلوا على قيمة فارغة بعد الآن: أصبحت مشكلة _request_id وطريقة الحصول عليه عبر with_raw_response موضّحة بشكل صريح.
  • مهام الفيديو أصبحت قابلة للتتبع: يُحفظ Request ID ومعرّف المهمة بشكل منفصل، فيتوفّر أساس للاستعلام عن المهمة وعن الرسوم المخصومة.

ما يجب الانتباه إليه عند قراءة الوثائق القديمة

لا تزال بعض صفحات قدرات الواجهات، وصفحات الأخبار، والصفحات التي تُحفظ فيها رسائل الأخطاء، تصف x-request-id بأنه شيء “سجّله لتسهيل الفحص”. عند مصادفة هذا الوصف، اعتمد صفحة Request ID الجديدة هذه كمرجع. واستبدل أيضًا x-request-id في قوالب الشفرة البرمجية بـ x-shellapi-request-id.


الأسئلة الشائعة (FAQ)

س1: أي Request ID هو المقصود بالضبط في APIYI؟

هو X-Shellapi-Request-Id الموجود في ترويسة الاستجابة، ويبدأ بـ 14 خانة من توقيت UTC. وعند حدوث خطأ، تكون القيمة نفسها موجودة في نهاية `message` الخاص بالخطأ داخل `(request id: …)`.

س2: هل من الآمن مشاركة Request ID مع الآخرين؟

نعم، آمن. وفق نص التوثيق، Request ID ليس مفتاحًا، ويمكن لصقه في تذكرة دعم أو محادثة أو لقطة شاشة. أما ما لا يجوز إرساله للخارج فهو مفتاح API الكامل الذي يبدأ بـ `sk-`.

س3: لماذا يكون المعرّف الذي يقرأه OpenAI SDK فارغًا؟

يقرأ `_request_id` الافتراضي في SDK قيمة x-request-id. استخدم `with_raw_response` بدلًا من ذلك، أو خذ x-shellapi-request-id من ترويسات استجابة `APIStatusError`.

س4: كيف أتحقق سريعًا من أنني أحصل على Request ID الصحيح؟

1. سجّل في APIYI عبر apiyi.com واحصل على مفتاح API؛ يملك المستخدمون الجدد رصيد اختبار مجاني.
2. اضبط Base URL على `https://api.apiyi.com/v1` وأرسل أصغر طلب ممكن.
3. اطبع x-shellapi-request-id وتأكد من الحصول على هذه السلسلة في كل استدعاء؛ صفحة السجلات تتيح فقط التحقق مما إذا كان هذا الاستدعاء قد وصل وهل تم خصم الرسوم، ولا تعرض المعرّف.

س5: هل يمكن البحث عن خطأ حدث قبل ثلاثة أشهر؟

عادةً لا. تحتفظ السجلات بالشهر الحالي والشهرين التقويميين السابقين، أما السجلات الأقدم فتتطلب شرحًا اعتمادًا على Request ID والخطأ الأصلي اللذين حفظتهما بنفسك.


النقاط الأساسية لمعرّف الطلب في APIYI

  • المعرّف الصحيح الوحيد: X-Shellapi-Request-Id، ويبدأ بوقت UTC مكوّن من 14 خانة
  • طريقتان للحصول عليه: نسخه من رسالة الخطأ، أو قراءة رأس الاستجابة في الكود (السجلات تؤكد الاستدعاء فقط ولا تعرض المعرّف)
  • أخطاء شائعة في التقاط المعرّف: X-Request-Id وreq_ وchatcmpl- وresp_ وUUID كلها غير صالحة للإبلاغ عن الأعطال
  • الفيديو يتطلب حفظ شيئين: معرّف الطلب المُرسَل ومعرّف المهمة يُحفظان كلٌّ على حدة
  • السجلات ليست مضمونة 100%: صفحة لوحة التحكم لا تعرض المعرّف؛ والطلبات التي ترفضها البوابة فورًا قد لا يكون لها سجل أصلاً، لذا يجب إضافة نص الخطأ والوقت
  • التحقق الأولي: أرسل طلبًا بسيطًا في APIYI عبر apiyi.com لتتأكد من إمكانية قراءة هذا الرأس

الخلاصة

تحديث وثائق استعلام معرّف الطلب (Request ID) في APIYI يتلخص في ثلاثة أمور أساسية:

  1. الإجابة أولاً: معرّف الطلب هو X-Shellapi-Request-Id، وتوجد القيمة نفسها في نهاية رسالة الخطأ.
  2. استبعاد المعرّفات الخاطئة: جدول المقارنة يوضح الفرق بين الطبقة الوسيطة والمصدر الأعلى وجسم الاستجابة ومعرّف المهمة.
  3. خطة بديلة عند عدم العثور عليه: أربع حالات، لكل منها المواد التي يجب إضافتها، مع قالب تذكرة جاهز للاستخدام مباشرةً.

ننصح الآن بتغيير حقول سجل الأخطاء في الكود إلى x-shellapi-request-id. وبعد ذلك، عند مواجهة مشكلة، قدّم المعرّف ووقت الاستدعاء معًا لخدمة العملاء، ليبحث الفريق الخلفي بواسطة المعرّف، ثم قدّم التذكرة مع المواد الكاملة.


📚 المراجع

  1. وثائق استكشاف أخطاء Request ID في APIYI (الإصدار الجديد): الأساس الواقعي لهذا المقال
  2. الرابط: docs.apiyi.com/faq/request-id-troubleshooting
  3. الوصف: يتضمن طريقتين للحصول على المعرّف، وشرح سجلات وحدة التحكم، وجدول مقارنة المعرّفات، وتوضيح الفيديو غير المتزامن، وقالب تذكرة الدعم

  4. كم تُحفظ السجلات؟: توضيح فترة الاحتفاظ بالسجلات

  5. الرابط: docs.apiyi.com/faq/log-retention-policy
  6. الوصف: للتأكد مما إذا كانت سجلات الأخطاء لا تزال قابلة للاستعلام

المؤلف: فريق APIYI التقني
للتواصل التقني: نرحب بتواصلكم معنا عبر الصفحة الرئيسية لموقع APIYI على apiyi.com، وإرفاق X-Shellapi-Request-Id عند إرسال تذكرة دعم يسرّع عملية المعالجة

موضوعات ذات صلة