أعاد فريق واجهة برمجة التطبيقات تسمية حقل من customer_name إلى customer_full_name. أعلنوا عن ذلك، وحدّثوا الوثائق، وتلقى كل عميل يتم صيانته يدويًا طلب سحب. عميلك الآلي لم يتلق شيئًا، لأن لا أحد اعتبره عميلًا. استمر في إرسال الحقل القديم، واستمرت واجهة برمجة التطبيقات في قبول الطلب وتجاهل المفتاح غير المعروف، ولمدة أسبوعين، كانت كل سجلات أنشأها تحتوي على اسم فارغ.
العملاء الآليون هم مستهلكو واجهة برمجة التطبيقات الأقل قدرة على ملاحظة التغيير والأكثر احتمالاً للتغطية عليه. العميل البشري يطلق استثناءً. العميل الآلي يقرأ 200، ويقرر أن الاستدعاء نجح، وينتقل. أحيانًا يرتجل حول المشكلة بطريقة تبدو وكأنها نجاح.
يغطي هذا الدليل لماذا يعتبر العملاء الآليون هشين بشكل غير عادي تجاه انحراف واجهة برمجة التطبيقات، وما هي التغييرات التي تعطلهم ولا تعطل العملاء العاديين، وكيفية تثبيت الإصدارات واكتشافها، وكيفية اكتشاف الانحراف في CI قبل حدوث التشغيل. يغطي منشورنا حول لماذا تفشل العملاء الآليون في بيئة الإنتاج أنماط الفشل؛ هذا هو النوع الذي يأتي من خارج قاعدة التعليمات البرمجية الخاصة بك.
Apidog مهم هنا لأن الاكتشاف يمثل مشكلة في المواصفات. إذا كان لديك الإصدار السابق من تعريف واجهة برمجة التطبيقات والإصدار الحالي، فإن الاختلاف يكون ميكانيكيًا.
لماذا يلاحظ العملاء الآليون أقل مما يلاحظه العملاء العاديون
تتضافر أربع خصائص بشكل سيء.
التسامح الصامت. تتجاهل معظم واجهات برمجة التطبيقات الحقول غير المعروفة في نص الطلب. الحقل الذي أعيدت تسميته يعني أن الجديد غير موجود والقديم يتم التخلص منه، مع `200` في النهاية. لا يوجد ما يثير اعتراضًا.
الارتجال. عندما يكون هناك قيمة مفقودة في الاستجابة، غالبًا ما يستمر النموذج باستخدام بديل معقول بدلاً من التوقف. هذا سلوك مفيد في المحادثة وسلوك خطير ضد واجهة برمجة التطبيقات.
الأوصاف في المطالبة. تُشفر أوصاف أدوات العميل الآلي افتراضات حول واجهة برمجة التطبيقات في النص. عندما تتغير واجهة برمجة التطبيقات، تصبح الأوصاف خاطئة بشكل دقيق، وتنتج الأوصاف الخاطئة استدعاءات خاطئة دون تدخل أي كود. يغطي منشورنا حول تصميم مخطط أدوات واجهة برمجة التطبيقات مدى تأثير السلوك على هذا النص.
لا يوجد مُصرِّف. ينهار العميل المُحدد النوع في وقت البناء عندما يختفي حقل. يعيش عقد العميل الآلي في مخططات JSON والنثر، ولا يتم التحقق منه حتى يفشل استدعاء، أو الأسوأ من ذلك، حتى لا يفشل بصمت.
الخلاصة: التغييرات الآمنة للعملاء التقليديين ليست دائمًا آمنة للعملاء الآليين، ويجب تصنيفها بشكل منفصل.
ما هي التغييرات التي تعطل العملاء الآليين بالفعل
لا يزال الانقسام المعتاد بين التغييرات الإضافية والتغييرات التي تسبب عطلاً ساريًا، ويضيف العملاء الآليون فئة متوسطة.
مسببة للتعطيل حقًا، للجميع. إزالة نقطة نهاية، إزالة حقل، إعادة تسمية حقل، تغيير نوع، جعل معلمة اختيارية إلزامية، تغيير عنوان URL. يتعطل العملاء الآليون هنا أيضًا، ولكن بشكل أكثر هدوءًا.
آمنة للعملاء مُحددي النوع، محفوفة بالمخاطر للعملاء الآليين:
- حقل مطلوب جديد. كل عميل حالي يتعطل، لكن العميل الآلي يتعطل بخطأ تحقق قد يحاول إصلاحه باختراع قيمة. وهذا أسوأ من الفشل التام.
- قيمة تعداد جديدة. العملاء العاديون يتجاهلون ما لا يتعاملون معه. قد يستنتج العميل الآلي بناءً على القيمة غير المألوفة ويتوصل إلى استنتاج لم يقصده منتجك أبدًا.
- قاعدة تحقق مشددة. الحقل الذي كان يقبل أي سلسلة نصية يتطلب الآن نمطًا. ليس لدى العميل الآلي طريقة لتعلم النمط إلا بالفشل، وهذا هو السبب في أن القاعدة يجب أن تكون في رسالة الخطأ، كما هو موضح في منشورنا حول تصميم رسائل خطأ واجهة برمجة التطبيقات للعملاء الآليين.
- تغيير الافتراضي. ينخفض الافتراضي للترقيم من 100 إلى 20، والعميل الآلي، الذي لم يرسل حدًا أبدًا، يرى الآن خمس البيانات ويبلغ عنها وكأنها كاملة.
- إعادة صياغة التوثيق. لا يوجد تغيير في السلوك على الإطلاق، ولكن إذا تم إنشاء أدواتك من المواصفات، كما في دليلنا حول تحويل مواصفات OpenAPI إلى أدوات عملاء آليين، فإن نص الوصف يتغير ويمكن أن يتغير معه اختيار الأداة.
آمنة للعملاء الآليين أيضًا. إضافة حقل اختياري، إضافة نقطة نهاية، إضافة معلمة اختيارية بقيمة افتراضية محفوظة، تخفيف التحقق.
هذه القائمة المتوسطة هي التي يجب مراقبتها، لأنه لا يوجد شيء في مراجعة التغيير القياسية يشير إليها.
ثبت الإصدار، دائمًا
الدفاع الأول هو رفض الانتقال ضمنيًا.
أرسل إصدارًا صريحًا في كل طلب، بغض النظر عن الآلية التي تقدمها واجهة برمجة التطبيقات: جزء مسار، ترويسة، أو تثبيت على مستوى الحساب. تستخدم وثائق تحديد إصدار واجهة برمجة تطبيقات GitHub ترويسة تاريخ، وتثبت Stripe إصدارًا لكل حساب مع خطوة ترقية صريحة. كلاهما يمنحك نفس الخاصية: لا شيء يتغير تحتك حتى تقرر.
DEFAULT_HEADERS = {
"X-API-Version": "2026-06-01",
"User-Agent": "billing-agent/1.4 (+https://example.com/agents)",
}
قيمة `User-Agent` لا تقل عن قيمة تثبيت الإصدار. عندما يحتاج مزود واجهة برمجة التطبيقات إلى تحذير المتصلين بشأن إهمال، فإنهم ينظرون إلى حركة المرور. العميل الآلي الذي يُعرّف عن نفسه يتلقى البريد الإلكتروني؛ بينما الذي يرسل سلسلة مكتبة افتراضية لا يتلقاه.
إذا كنت تملك واجهة برمجة التطبيقات، فانشر إصدارًا واحتفظ به. يغطي دليلنا حول أفضل استراتيجية لتحديد إصدار واجهة برمجة التطبيقات الخيارات المتاحة، ويغطي إدارة تحديد إصدار واجهة برمجة التطبيقات في Apidog كيفية إبقاء عدة إصدارات حية في وقت واحد.
بالنسبة لواجهات برمجة التطبيقات التابعة لجهات خارجية التي لا تحتوي على تحديد إصدار على الإطلاق، ثبت ما تستطيع: سجل شكل الاستجابة الذي بنيت عليه وتحقق منه، وهذا ما سنتناوله في القسم التالي.
اكتشف الانحراف قبل أن يحدث التشغيل
التثبيت يشتري الوقت. إنه لا يوقف الترقية النهائية، ولا يفعل شيئًا لواجهات برمجة التطبيقات التي تتغير دون تحديد إصدار. لذا، اكتشف.
قارن المواصفات بانتظام. إذا نشر المزود مستند OpenAPI، فقم بجلبه يوميًا وقارنه بالنسخة التي أنشأت منها الأدوات. حقول محذوفة، أنواع متغيرة، متطلبات مضافة، تعدادات موسعة، أوصاف معدلة. في Apidog، يمكنك الاحتفاظ بالتعريف المستورد في المشروع ورؤية ما تغير بين الإصدارات، مما يحول سؤال "هل تغير أي شيء" إلى تقرير بدلاً من تحقيق.
اختبر عقود نقاط النهاية التي تستدعيها. لكل أداة يمتلكها العميل الآلي، أرسل طلبًا معروفًا وصالحًا وتحقق من شكل الاستجابة: وجود الحقول المطلوبة، صحة الأنواع، قيم التعداد ضمن المجموعة التي تتوقعها. يصطاد هذا الانحراف في واجهات برمجة التطبيقات التي لا تنشر أي مواصفات على الإطلاق، وهو معظمها. يغطي دليلنا حول اختبار عقود واجهة برمجة التطبيقات هذا النمط، ويغطي اختبار العقود ثنائي الاتجاه تشغيله من كلا الجانبين.
تحقق من الشكل في وقت التشغيل. تحقق من الاستجابات في غلاف الأداة مقابل المخطط الذي تتوقعه، وسجل تحذيرًا عندما يظهر شيء غير متوقع. هذا هو الخط الأخير، وهو الذي يكتشف التغيير الذي لم يعلن عنه أحد.
def check_shape(tool_name, payload, expected):
missing = [f for f in expected["required"] if f not in payload]
extra = [f for f in payload if f not in expected["properties"]]
if missing:
log.error("api_drift", tool=tool_name, missing=missing)
raise ApiDriftError(f"{tool_name}: missing fields {missing}")
if extra:
log.warning("api_new_fields", tool=tool_name, fields=extra)
return payload
افشل عند النقص، وحذر عند الزيادة. يعني الحقل المطلوب المفقود أن العميل الآلي على وشك العمل ببيانات غير كاملة، وهو الفشل الذي يستحق التوقف عنده. الحقول الجديدة عادة ما تكون إضافية وتستحق المعرفة بها دون مقاطعة التشغيل. وجه كلاهما إلى سجل التتبع الموصوف في منشورنا حول تتبع استدعاءات أدوات العميل الآلي.
راقب السلوك، وليس المخططات فقط. بعض الانحرافات غير مرئية لفحص الشكل: قيمة افتراضية تغيرت، حد معدل أصبح أكثر صرامة، استجابة أصبحت أبطأ. تتبع الاستدعاءات لكل مهمة مكتملة، معدل إعادة المحاولة لكل نقطة نهاية، ومتوسط حجم الاستجابة لكل أداة. التغيير المفاجئ في أي منها يعني عادة أن شيئًا ما قد تغير في المصدر.
الترقية دون تعطيل العميل الآلي
عندما تنتقل إلى إصدار جديد، تعامل معه كتغيير في العميل الآلي، لأنه كذلك.
أعد إنشاء الأدوات بدلاً من تعديلها يدويًا، بحيث تنتقل الأوصاف والمخططات معًا. ثم اقرأ الفرق في تعريفات الأدوات التي تم إنشاؤها. هذا الفرق هو النطاق الحقيقي للتأثير، وغالبًا ما يكون أصغر أو أكبر مما يوحي به سجل تغييرات واجهة برمجة التطبيقات.
شغل العميل الآلي مقابل نسخة وهمية من الإصدار الجديد قبل توجيهه إلى أي شيء حي. هذه هي الخطوة الأعلى قيمة والأكثر تجاهلًا: تتيح لك نسخة وهمية مبنية من المواصفات الجديدة تشغيل مجموعة مهامك بأكملها مقابل الأشكال الجديدة بدون مخاطر، باتباع منشورنا حول تشغيل العملاء الآليين مقابل النسخ الوهمية بدلاً من الإنتاج.
أعد تشغيل مجموعة الاختبار للاختيار. تؤدي تغييرات الوصف إلى تغيير الأداة التي يختارها النموذج، وهذا التراجع غير مرئي لفرق المخطط. تحقق من اختيار الأداة لمجموعة ثابتة من المطالبات، كما هو الحال في دليلنا حول اختبار العملاء الآليين غير الحتميين.
اطرح التغيير خلف علامة، على شريحة من حركة المرور، مع بقاء الإصدار القديم مثبتًا وجاهزًا. راقب نفس الأرقام الأربعة ليوم واحد. تظهر تراجعات العميل الآلي على شكل المزيد من الاستدعاءات لكل مهمة والمزيد من عمليات إعادة المحاولة قبل وقت طويل من تقديم أي شخص شكوى.
ثلاثة انحرافات وصلت إلى الإنتاج
الحقل الذي أعيدت تسميته. القصة الافتتاحية. رمز `200` في كل استدعاء، أسماء فارغة في كل سجل، اكتشفها إنسان بعد أسبوعين من قراءة تقرير. فحص شكل وقت التشغيل على الاستجابة كان سيكشفها في أول استدعاء، لأن الحقل الذي كان العميل الآلي يتوقع قراءته لم يعد موجودًا.
الاعداد الافتراضي للترقيم المشدد. خفّض المزود حجم الصفحة الافتراضي من 100 إلى 20. لم يرسل العميل الآلي `limit` مطلقًا، لذلك بدأ يرى 20 سجلًا ويلخصها على أنها المجموعة الكاملة. لم يحدث أي خطأ. كانت الملخصات خاطئة ببساطة، بطريقة بدت واثقة. كان الحل عبارة عن سطر واحد، إرسال `limit` صريح، والدرس أوسع: اعتمد على الافتراضات وستكون لديك تبعية غير معلنة على قرار شخص آخر.
قيمة التعداد الجديدة. أضافت واجهة برمجة تطبيقات المدفوعات `status: "disputed"`. تجاهلتها العملاء محددة النوع. استنتج العميل الآلي حولها، وقرر أن الشحنة المتنازع عليها تُحسب كاسترداد، وأبلغ عن كتب متطابقة لم تكن كذلك. كان من شأن التحقق الصريح من التعداد أن يثير اعتراضًا على القيمة غير المألوفة بدلاً من ترك النموذج يفسرها.
النمط: تم الإعلان عن كل تغيير، وكان كل منها إضافيًا أو ثانويًا حسب تصنيف المزود، وكان كل منها معطلاً للعميل الآلي. تلك الفجوة هي ما يجب التصميم بناءً عليه.
تعامل مع الإهمالات كعنصر عمل
عادةً ما يحذرك المزودون. يصل التحذير في سجل التغييرات، أو بريد إلكتروني، أو ترويسة `Deprecation` في الاستجابة، ومن السهل ألا يصل أي من هذه التحذيرات إلى الشخص الذي يدير العميل الآلي.
ادمجها في قائمة انتظارك العادية. كل من ترويسة Deprecation و ترويسة Sunset موحدتان، لذا يعمل الفحص العام عبر المزودين. سجلها عند ظهورها، ونبه عند أول رؤية بدلاً من الألف. الترويسة التي تظهر في 3 بالمائة من الاستدعاءات اليوم هي انقطاع كامل في تاريخ الغروب (انتهاء الدعم).
احتفظ بجرد أيضًا: أي عميل آلي، أي مزود، أي إصدار، أي نقاط نهاية، ومن يملكه. عشرة أسطر في ملف كافية. عند وصول إشعار إهمال، يجب أن يستغرق سؤال "هل يؤثر هذا علينا" دقيقة واحدة، وليس فترة ما بعد الظهر من البحث.
الانحراف هو عمل، لذا امنحه مالكًا
ينتج الكشف قائمة انتظار: فرق مواصفات، اختبار عقد فاشل، ترويسة إهمال شوهدت لأول مرة. كل واحد منها عبارة عن قطعة عمل صغيرة مرفق بها موعد نهائي، ونمط الفشل هو أن تبقى في قناة لا يملكها أحد حتى تاريخ انتهاء الدعم.
ضعها حيث يتتبع فريقك العمل بالفعل. إذا كانت عملاءك الآليون يعملون كبيئات تشغيل برمجية بدلاً من خدمة قمت بنشرها، يمكن للمنصة التي تديرها إغلاق الحلقة: تقوم Sharkly بتعيين مهمة لعميل آلي أو طاقم عمل وتحتفظ بالهدف، وتتبع التنفيذ، والمراجعة في مكان واحد، بحيث يصبح "واجهة برمجة تطبيقات المدفوعات أهملت نقطة النهاية هذه" مهمة معينة بنتيجة بدلاً من رسالة في سلسلة. مهما كان ما تستخدمه، فإن القاعدة هي نفسها. تنبيه الانحراف بدون مالك هو إهمال ستواجهه مرة أخرى في اليوم الذي يتعطل فيه النظام.
قائمة تحقق
- كل طلب يرسل إصدارًا صريحًا لواجهة برمجة التطبيقات و`User-Agent` معرفًا.
- يتم جلب وثائق المواصفات من جهات خارجية ومقارنتها بانتظام.
- كل أداة يمكن للعميل الآلي استدعاؤها لديها اختبار عقد يؤكد شكل الاستجابة.
- أغلفة الأدوات تتحقق من الاستجابات في وقت التشغيل: تفشل عند النقص، وتحذر عند الجديد.
- يتم تتبع المقاييس السلوكية لكل نقطة نهاية لكي يظهر الانحراف الصامت.
- ترقيات الإصدار تعيد إنشاء الأدوات بدلاً من تعديلها يدويًا.
- مجموعة المهام ومجموعة الاختيار يتم تشغيلهما مقابل نسخة وهمية من الإصدار الجديد أولاً.
- الانتشار يتم بوضع علامة عليه وقابل للعكس، مع بقاء الإصدار السابق مثبتًا.
سيستمر فريق واجهة برمجة التطبيقات في إجراء التغييرات، وهذا أمر جيد. ما تحتاجه هو أن يكون عميلك الآلي عميلًا يلاحظ التغييرات، وهذا يتطلب تثبيت إصدار، واختبار عقد، وفحص شكل وقت التشغيل. نزّل Apidog لمقارنة المواصفات ومحاكاة الإصدار التالي قبل أن يصل إلى تشغيل حي.
الأسئلة المتكررة
كم مرة يجب أن أتحقق من مواصفات طرف ثالث بحثًا عن تغييرات؟ يوميًا يكفي لمعظم الحالات، وهو رخيص التشغيل الآلي. بالنسبة لواجهات برمجة التطبيقات التي لا تحتوي على مواصفات منشورة، اعتمد على اختبارات العقود التي تعمل في CI بدلاً من ذلك، لأنها تكتشف نفس الانحراف من الخارج.
هل يجب دائمًا التثبيت على أقدم إصدار يعمل؟ لا. ثبت الإصدار بحيث تكون الترقيات متعمدة، ثم قم بالترقية وفق جدول زمني. البقاء على إصدار قديم حتى يتم إزالته يحول التغيير المخطط له إلى حالة طوارئ.
ماذا لو عمل العميل الآلي بشكل جيد بعد التغيير؟ تحقق بدلاً من الافتراض. النتائج الخطيرة هي تلك التي لا تزال تعيد `200`، مثل حقل أعيدت تسميته وتم إسقاطه بصمت. تأكيد الشكل يخبرك بما لا يمكن أن يخبرك به التشغيل الأخضر.
هل أحتاج إلى تحديد إصدار واجهة برمجة التطبيقات الخاصة بي بشكل مختلف للعملاء الآليين؟ ليس بشكل مختلف، بل بشكل أكثر صرامة. تعامل مع الحقول المطلوبة الجديدة، وقيم التعداد الجديدة، والإعدادات الافتراضية المتغيرة على أنها مسببة للعطل لمستهلكي العملاء الآليين حتى عندما تكون إضافية للعملاء مُحددي النوع، وأعلن عنها بنفس الطريقة.
كيف أعرف أي العملاء الآليين يستدعي أي نقاط نهاية؟ من تتبعاتك. اسم الأداة بالإضافة إلى نقطة النهاية لكل تشغيل يمنحك خريطة التبعية، ويخبرك بالضبط من يتأثر بالإهمال. يغطي منشورنا حول تتبع استدعاءات أدوات العميل الآلي شكل السجل.
هل يمكن للعميل الآلي التكيف مع واجهة برمجة تطبيقات متغيرة بمفرده؟ أحيانًا، ولكن لا يجب الاعتماد على ذلك. النموذج الذي يرتجل حول حقل مفقود ينتج مخرجات معقولة دون أي إشارة إلى أن شيئًا ما قد حدث بشكل خاطئ. افشل بصوت عالٍ وقم بإصلاح الأدوات بدلاً من ذلك.