مشاركة عبر

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

  • مقالة

ينطبق على: الاستهلاك | المطور | أساسي | قياسي | بريميوم

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

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

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

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

إشعار

حاليا، تتبع طلبات واجهة برمجة التطبيقات غير مدعوم في مستويات الإصدار 2 الأساسي والقياسي v2.

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

هام

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

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

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

  2. تحديد APIs.

  3. حددDemo Conference API من قائمة API الخاصة بك.

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

  5. حدد عملية GetSpeakers.

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

    تلميح

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

  7. حدد تتبع.

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

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

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

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

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

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

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

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

    تلميح

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

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

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

تمكين التتبع من خلال الخطوات التالية باستخدام الاستدعاءات إلى API Management REST API.

إشعار

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

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

    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": "<API resource ID>",
    "purposes: ["tracing"]
}

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

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

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

    curl -v GET https://apim-hello-world.azure-api.net/conference/speakers HTTP/1.1 -H "Ocp-Apim-Subscription-Key: <subscription-key>" -H "Apim-Debug-Authorization: aid=api-name&p=tracing&ex=......."

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

    • إذا كان الرمز المميز صالحا، تتضمن الاستجابة عنوانا Apim-Trace-Id تكون قيمته هو معرف التتبع.
    • إذا انتهت صلاحية الرمز المميز، تتضمن الاستجابة عنوانا 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": "<trace ID>"
}

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

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

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

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

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

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

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