مشاركة عبر

البرنامج التعليمي: تصحيح APIs الخاصة بك باستخدام تتبع الطلب

  • مقالة

ينطبق على: جميع مستويات إدارة واجهة برمجة التطبيقات

يصف هذا البرنامج التعليمي كيفية فحص (تتبع) معالجة الطلب في Azure API Management. يساعدك التتبع على تصحيح أخطاء واجهة برمجة التطبيقات واستكشاف الأخطاء وإصلاحها.

في هذا البرنامج التعليمي، تتعلم كيفية:

  • تتبع استدعاء مثال في وحدة تحكم الاختبار
  • مراجعة خطوات معالجة الطلبات
  • تمكين التتبع لواجهة برمجة التطبيقات

لقطة شاشة تعرض مفتش واجهة برمجة التطبيقات.

المتطلبات الأساسية

هام

  • لم تعد API Management تدعم الاشتراكات للتتبع أو رأس Ocp-Apim-Trace .
  • لتحسين أمان واجهة برمجة التطبيقات، يمكن الآن تمكين التتبع على مستوى واجهة برمجة تطبيقات فردية عن طريق الحصول على رمز مميز محدود زمنيا باستخدام API Management REST API، وتمرير الرمز المميز في طلب إلى البوابة. للحصول على التفاصيل، راجع تمكين تتبع واجهة برمجة التطبيقات.
  • احرص عند تمكين التتبع، لأنه يمكن أن يعرض معلومات حساسة في بيانات التتبع. تأكد من وجود تدابير أمان مناسبة لحماية بيانات التتبع.

تتبع مكالمة في المدخل

اتبع هذه الخطوات لتتبع طلب واجهة برمجة التطبيقات في وحدة تحكم الاختبار في المدخل. يفترض هذا المثال أنك قمت باستيراد نموذج API في برنامج تعليمي سابق. يمكنك اتباع خطوات مماثلة باستخدام واجهة برمجة تطبيقات مختلفة قمت باستيرادها.

  1. تسجيل الدخول إلى بوابة Azure، والانتقال إلى مثيل API Management.

  2. حدد واجهات برمجة التطبيقات APIs>.

  3. حدد Petstore API من قائمة واجهة برمجة التطبيقات الخاصة بك.

  4. حدد علامة التبويب الاختبار.

  5. حدد عملية البحث عن أليف حسب المعرف .

  6. في معلمة petId Query، أدخل 1.

  7. تحقق اختياريًا من قيمة عنوان Ocp-Apim-Subscription-Key المستخدم في الطلب عن طريق تحديد أيقونة "العين".

    تلميح

    يمكنك منع قيمة Ocp-Apim-Subscription-Key عن طريق استرداد مفتاح لاشتراك آخر في المدخل. حددالاشتراكات، وافتح قائمة السياق (...) لاشتراك آخر. حدد إظهار/إخفاء المفاتيح وانسخ أحد المفاتيح. يمكنك أيضاً إعادة كتابة المفاتيح إذا لزم الأمر. بعد ذلك، في وحدة تحكم الاختبار، حدد + إضافة عنوان لإضافة عنوان Ocp-Apim-Subscription-Key بقيمة المفتاح الجديد.

  8. حدد تتبع.

مراجعة معلومات التتبع

  1. بعد اكتمال الاتصال، انتقل إلى علامة التبويبTrace في HTTP Response.

  2. حدد أيًا من الارتباطات التالية للانتقال إلى معلومات التتبع التفصيلية: الواردة، الخلفية، الصادرة، عند الخطأ.

    مراجعة تتبع الاستجابة

    • الواردة - يوضح original request الخاص بـ API Management المتلقاة من المتصل والسياسات المطبقة على الطلب. على سبيل المثال، إذا أضفت نهج في البرنامج التعليمي: تحويل واجهة برمجة التطبيقات الخاصة بك وحمايتها، فستظهر هنا.

    • الخليفة- إظهار الطلبات المرسلة عن طريق API Management إلى خليفة API والاستجابة التي تلقتها.

    • الصادرة- إظهار السياسات المطبقة على الاستجابة قبل إرسالها مرة أخرى إلى المتصل.

    • عند الخطأ - يعرض الأخطاء التي حدثت أثناء معالجة الطلب والنهج المطبقة على الأخطاء.

    تلميح

    تظهر كل خطوة أيضاً الوقت المنقضي منذ تلقي الطلب من جانبAPI Management.

تمكين التتبع لواجهة برمجة التطبيقات

الخطوات عالية المستوى التالية مطلوبة لتمكين التتبع لطلب إلى APIM عند استخدام curl، أو عميل REST مثل Visual Studio Code مع ملحق عميل REST، أو تطبيق عميل. حاليا يجب اتباع هذه الخطوات باستخدام API Management REST API:

  1. الحصول على بيانات اعتماد رمز مميز للتتبع.
  2. أضف قيمة الرمز المميز في Apim-Debug-Authorization عنوان طلب إلى بوابة APIM.
  3. الحصول على معرف تتبع في عنوان الاستجابة Apim-Trace-Id .
  4. استرداد التتبع المطابق لمعرف التتبع.

اتبع الخطوات التفصيلية.

إشعار

  • تتطلب هذه الخطوات API Management REST API الإصدار 2023-05-01-preview أو أحدث. يجب تعيين دور المساهم أو دور أعلى على مثيل APIM لاستدعاء واجهة برمجة تطبيقات REST.
  • للحصول على معلومات حول المصادقة على واجهة برمجة تطبيقات REST، راجع مرجع Azure REST API.

  1. الحصول على بيانات اعتماد رمز مميز - اتصل بواجهة برمجة تطبيقات قائمة بيانات اعتماد تتبع أخطاء بوابة إدارة واجهة برمجة التطبيقات. في URI، أدخل "managed" للبوابة المدارة للمثيل في السحابة، أو معرف البوابة لبوابة مستضافة ذاتيا. على سبيل المثال، للحصول على بيانات اعتماد التتبع للبوابة المدارة للمثيل، استخدم طلبا مشابها لما يلي:

    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview

    في نص الطلب، مرر معرف المورد الكامل لواجهة برمجة التطبيقات التي تريد تتبعها، وحدد purposes ك tracing. بشكل افتراضي تنتهي صلاحية بيانات اعتماد الرمز المميز التي تم إرجاعها في الاستجابة بعد ساعة واحدة، ولكن يمكنك تحديد قيمة مختلفة في الحمولة. على سبيل المثال:

    {
    "credentialsExpireAfter": PT1H,
    "apiId": ""/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiName}",
    "purposes": ["tracing"]
}

    يتم إرجاع بيانات اعتماد الرمز المميز في الاستجابة، على غرار ما يلي:

    {
      "token": "aid=api-name&......."
}

  2. إضافة قيمة الرمز المميز في عنوان طلب - لتمكين تتبع طلب إلى بوابة إدارة واجهة برمجة التطبيقات، أرسل قيمة الرمز المميز في Apim-Debug-Authorization عنوان. على سبيل المثال، لتتبع استدعاء لواجهة برمجة تطبيقات Petstore التي قمت باستيرادها في برنامج تعليمي سابق، يمكنك استخدام طلب مشابه لما يلي:

    curl -v https://apim-hello-world.azure-api.net/pet/1 HTTP/1.1 -H "Ocp-Apim-Subscription-Key: <subscription-key>" -H "Apim-Debug-Authorization: aid=api-name&......."

  3. اعتمادا على الرمز المميز، تحتوي الاستجابة على أحد العناوين التالية:

    • إذا كان الرمز المميز صالحا، تتضمن الاستجابة عنوانا Apim-Trace-Id تكون قيمته هو معرف التتبع، على غرار ما يلي:

      Apim-Trace-Id: 0123456789abcdef....

    • إذا انتهت صلاحية الرمز المميز، تتضمن الاستجابة عنوانا Apim-Debug-Authorization-Expired يحتوي على معلومات حول تاريخ انتهاء الصلاحية.

    • إذا تم الحصول على الرمز المميز لواجهة برمجة تطبيقات مختلفة، تتضمن الاستجابة عنوانا Apim-Debug-Authorization-WrongAPI برسالة خطأ.

  4. استرداد التتبع - قم بتمرير معرف التتبع الذي تم الحصول عليه في الخطوة السابقة إلى واجهة برمجة تطبيقات تتبع القائمة الخاصة بالبوابة. على سبيل المثال، لاسترداد تتبع البوابة المدارة، استخدم طلبا مشابها لما يلي:

    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview

    في نص الطلب، مرر معرف التتبع الذي تم الحصول عليه في الخطوة السابقة.

    {
    "traceId": "0123456789abcdef...."
}

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

للحصول على معلومات حول تخصيص معلومات التتبع، راجع نهج التتبع.

الخطوات التالية

في هذا البرنامج التعليمي، نتعلم طريقة القيام بما يأتي:

  • تتبع استدعاء مثال في اختبار conosle
  • مراجعة خطوات معالجة الطلبات
  • تمكين التتبع لواجهة برمجة التطبيقات

تقدم إلى البرنامج التعليمي الآتي:

استخدام المراجعات