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

ينطبق على: جميع API Management المستويات

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

إشعار

حاليا، هذه الميزة غير متوفرة في مساحات العمل.

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

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

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

تعلم مصطلحات إدارة Azure API.
أكمل البدء السريع التالي: إنشاء مثيل إدارة Azure API.
أكمل البرنامج التعليمي التالي:استيراد API الأولي الخاصة بك ونشرها.

هام

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

تتبع مكالمة في بوابة Azure

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

سجل الدخول إلى بوابة Azure، وانتقل إلى مثيل إدارة واجهة برمجة التطبيقات الخاصة بك.
حدد واجهات برمجة التطبيقات APIs>.
حدد Petstore API من قائمة واجهة برمجة التطبيقات الخاصة بك.
حدد علامة التبويب الاختبار.
حدد عملية البحث عن أليف حسب المعرف .
في معلمة petId Query، أدخل 1.
تحقق اختياريًا من قيمة عنوان Ocp-Apim-Subscription-Key المستخدم في الطلب عن طريق تحديد أيقونة "العين".

تلميح

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

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

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

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

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

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

الحصول على رمز تتبع الأخطاء للتتبع.
أضف قيمة الرمز في رأس طلب Apim-Debug-Authorization إلى بوابة API Management.
الحصول على معرف تتبع في عنوان الاستجابة Apim-Trace-Id .
استرداد التتبع المطابق لمعرف التتبع.

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

إشعار

تتطلب هذه الخطوات API Management نسخة REST API 2023-05-01-preview أو أحدث.
يجب أن يتم تعيين دور المساهم أو الدور الأعلى في مثيل إدارة واجهة برمجة التطبيقات (API) أو أن يكون لديك أذونات كتابة مكافئة على واجهة برمجة التطبيقات للحصول على رمز تصحيح.
للحصول على معلومات حول المصادقة مع واجهة برمجة تطبيقات REST، راجع Azure REST API reference.

احصل على رمز تصحيح. اتصل بواجهة اعتماد تصحيح الأخطاء List الخاصة ببوابة API Management. في 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": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}",
    "purposes": ["tracing"]
}
```
إشعار

يمكن سحب apiId فقط من معرف المورد الكامل، وليس من الاسم المعروض في بوابة Azure.

الحصول على معرف واجهة برمجة التطبيقات:
```
az apim api list --resource-group <resource-group> --service-name <service-name> -o table
```
يتم إرجاع بيانات التصحيح في الرد، مشابهة للمثال التالي:
```
{
      "token": "aid=api-name&......."
}
```
أضف قيمة الرمز في رأس الطلب. لتمكين تتبع الطلب إلى بوابة API Management، أرسل قيمة الرمز في رأس 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&......."
```

قيم الاستجابة. يمكن أن تحتوي الاستجابة على أحد الرؤوس التالية حسب حالة رمز التصحيح:

العنوان استجابة	الشرح
`Apim-Trace-Id`	رمز التصحيح صالح. القيمة هي معرف الأثر، مثل: `Apim-Trace-Id: 0123456789abcdef....`
`Apim-Debug-Authorization-Expired`	الرمز منتهية الصلاحية. يتضمن الرأس معلومات عن تاريخ انتهاء الصلاحية.
`Apim-Debug-Authorization-WrongAPI`	تم الحصول على رمز لواجهة برمجة تطبيقات مختلفة. يتضمن الرأس رسالة خطأ.

استرجع الأثر. مرر معرف التتبع الذي تم الحصول عليه في الخطوة السابقة إلى واجهة برمجة تطبيقات تتبع القائمة الخاصة بالبوابة. على سبيل المثال، لاسترجاع التتبع الخاص بالبوابة المدارة، استخدم طلبا مشابها للمثال التالي:
```
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...."
}
```
يحتوي نص الاستجابة على بيانات التتبع لطلب واجهة برمجة التطبيقات السابق إلى البوابة. يشبه التتبع التتبع الذي يمكنك رؤيته عن طريق تتبع استدعاء في وحدة تحكم اختبار المدخل.

مثال على ملف http لامتداد عميل VS Code REST

للمساعدة في أتمتة هذه الخطوات باستخدام امتداد تعليمة Visual Studio برمجية REST Client، يمكنك استخدام المثال التالي .http الملف:

@subscriptionId = // Your subscription ID
@resourceGroup = // Your resource group
@apimName = // Your API Management service name
@clientId = // Client ID from an app registration for authentication
@clientSecret = // Client secret from app registration
@externalHost = // The host name of the App Gateway or the fully qualified gateway URL
@subscriptionKey = // API Management subscription key
@apiEndPoint = // API URL
@requestBody = // Data to send
@tenantId = // Tenant ID
@apiId = // Api Id for which trace log is to be generated.

# @name login 
POST https://login.microsoftonline.com/{{tenantId}}/oauth2/token
content-type: application/x-www-form-urlencoded
 
grant_type=client_credentials&client_id={{clientId}}&client_secret={{clientSecret}}&resource=https%3A%2F%2Fmanagement.azure.com%2F
 
###
@authToken = {{login.response.body.$.access_token}}
###
# @name listDebugCredentials
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
Authorization: Bearer {{authToken}}

Content-Type: application/json
{
    "credentialsExpireAfter": "PT1H",
    "apiId": "/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/apis/{{apiId}}",
    "purposes": ["tracing"]
}
 
###
@debugToken = {{listDebugCredentials.response.body.$.token}}
 
###
# @name callApi
POST {{apiEndPoint}} HTTP/1.1
Host: {{externalHost}}
Apim-Debug-Authorization: {{debugToken}}
Ocp-Apim-Subscription-Key: {{subscriptionKey}}
Content-Type: application/json

{{requestBody}}
 
###
@traceId = {{callApi.response.headers.Apim-Trace-Id}}
 
###
# @name getTrace
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/gateways/managed/listTrace?api-version=2024-06-01-preview
Authorization: Bearer {{authToken}}
Content-Type: application/json
 
{
    "traceId": "{{traceId}}"
}

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

الملخص

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

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

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

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

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

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-03-11