مشاركة عبر

استخدام القيم المسماة في نهج إدارة APIM

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

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

القيم المسماة هي مجموعة عمومية من أزواج الاسم/القيم في كل مثيل إدارة APIM. يمكنك استخدام القيم المسماة لإدارة قيم السلسلة الثابتة والأسرار عبر جميع تكوينات واجهة برمجة التطبيقات والنهج.

القيم المسماة في مدخل Microsoft Azure

أنواع القيم

النوع ‏‏الوصف
واضح تعبير السلسلة الحرفية أو النهج
سر سلسلة حرفية أو تعبير نهج تم تشفيره بواسطة إدارة واجهة برمجة التطبيقات
Key Vault معرف البيانات السرية مُخزّن فيkey vault Azure.

يمكن أن تحتوي القيم العادية أو البيانات السرية على policy expressions. على سبيل المثال، إرجاع التعبير @(DateTime.Now.ToString()) سلسلة تحتوي على التاريخ والوقت الحاليين.

للحصول على تفاصيل حول سمات القيمة المسماة، راجع مرجع APIM REST API.

أسرار Key vault

يمكن تخزين القيم السرية إما كسلاسل مشفرة في APIM (أسرار مخصصة) أو عن طريق الرجوع إلى الأسرار في Azure Key Vault.

نوصي باستخدام أسرار مخزن المفاتيح لأنها تساعد في تحسين أمان إدارة واجهة برمجة التطبيقات:

إشعار

حاليا، لا يتوفر التكامل مع مخزن المفاتيح لهذا السيناريو في مساحات العمل.

  • يمكنك إعادة استخدام الأسرار المخزنة في مخازن المفاتيح عبر الخدمات.
  • يمكنك تطبيق نهج الوصول الدقيقة على الأسرار.
  • يتم تدوير الأسرار المحدثة في قبو المفتاح تلقائيا في APIM. بعد التحديث في مخزن المفاتيح، يتم تحديث قيمة مسماة في إدارة واجهة برمجة التطبيقات في غضون أربع ساعات. يمكنك أيضا تحديث السر يدويا باستخدام مدخل Microsoft Azure أو عبر إدارة REST API.

إشعار

يجب أن تكون الأسرار المخزنة في Azure Key Vault بين 1 و4096 حرفا، لأن إدارة واجهة برمجة التطبيقات لا يمكنها استرداد القيم التي تتجاوز هذا الحد.

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

المتطلبات الأساسية لدمج key vault الرئيسية

إشعار

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

تكوين الوصول إلى key vault

  1. في المدخل، انتقل إلى خزنة المفاتيح الخاصة بك.
  2. في القائمة اليمنى، حدد إعدادات>تكوين الوصول إلى الإعدادات. لاحظ نموذج الإذن الذي تم تكوينه.
  3. اعتمادا على نموذج الإذن، قم بتكوين إما نهج الوصول إلى مخزن المفاتيح أو الوصول إلى التحكم في الوصول استنادا إلى الدور في Azure للهوية المدارة لإدارة واجهة برمجة التطبيقات.

لإضافة نهج الوصول إلى مخزن المفاتيح:

  1. في القائمة اليسرى، حدد Access policies.
  2. في صفحة Access policies ، حدد + Create.
  3. في علامة التبويب أذونات ، ضمن أذونات سرية، حدد الحصول على وقائمة، ثم حدد التالي.
  4. في علامة التبويب الأساسي ، ابحث عن اسم المورد للهوية المدارة، ثم حدد التالي. إذا كنت تستخدم هوية معينة من قِبل النظام، فإن الأساسي هو اسم مثيل إدارة API الخاص بك.
  5. حدد التالي مرة أخرى. حدد Review + create من علامة التبويب، حدد Create.

لتكوين الوصول إلى Azure RBAC:

  1. على الجانب الأيسر، حدد التحكم بالوصول (IAM).
  2. في صفحة Access control (IAM)، حدد Add role assignment.
  3. في علامة التبويب الدور ، حدد مستخدم أسرار مخزن المفاتيح، ثم حدد التالي.
  4. في علامة التبويب Members ، حدد Managed identity>+ Select members.
  5. في صفحة تحديد الهوية المدارة، حدد الهوية المدارة المعينة من قبل النظام أو الهوية المدارة المعينة من قبل المستخدم المقترنة بمثيل إدارة واجهة برمجة التطبيقات، ثم حدد تحديد.
  6. حدد مراجعة + تعيين.

متطلبات جدار الحماية Key Vault

إذا تم تمكين جدار حماية Key Vault على مخزن المفاتيح الخاص بك، فيجب عليك تلبية هذه المتطلبات:

  • يجب استخدام الهوية المدارة المعينة من قبل النظام لمثيل API Management للوصول إلى مخزن المفاتيح.

  • تأكد من أن نسخة إدارة API الخاصة بك لديها خط رؤية شبكي لخزنة المفاتيح. اعتمادا على سيناريوهاتك الطبيعية، قم بتكوين أحد خيارات الوصول إلى الشبكة التالية على خزنة المفاتيح:

    • السماح بالوصول العام من جميع الشبكات.

    • قم بتعيين قاعدة أمان للشبكة للسماح بحركة إدارة واجهة برمجة التطبيقات بناء على عنوان IP أو الاتصال بالشبكة الافتراضية.

    • تأمين حركة المرور من إدارة واجهات برمجة التطبيقات باستخدام الاتصال بالروابط الخاصة.

    • استخدم محيط أمني الشبكة لتأمين خزنة المفاتيح والسماح بحركة المرور من إدارة واجهات برمجة التطبيقات.

  • تأكد من أن عنوان IP للعميل المحلي لديك مسموح له بالوصول إلى مخزن المفاتيح مؤقتاً خلال تحديد شهادة أو سر لإضافته إلى Azure API M. للحصول على مزيدٍ من المعلومات، راجع تكوين إعدادات شبكة Azure Key Vault.

    بعد إكمال التكوين، يمكنك حظر عنوان العميل الخاص بك في جدار حماية مخزن المفاتيح.

هام

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

متطلبات الشبكة الافتراضية

إذا تم توزيع مثيل إدارة APIM في شبكة ظاهرية، فقم أيضاً بتكوين إعدادات الشبكة التالية:

  • تمكين نقطة نهاية خدمة إلى Key Vault على الشبكة الفرعية لإدارة واجهة برمجة التطبيقات.
  • قم بتكوين قاعدة مجموعة أمان الشبكة (NSG) للسماح بنسبة استخدام الشبكة الصادرة إلى علامات خدمة AzureKeyVault وAzureActiveDirectory service tags.

للحصول على التفاصيل، راجع تكوين الشبكة عند إعداد APIM في شبكة ظاهرية.

إضافة قيمة مسماة أو تحريرها

إضافة سر key vault إلى APIM

راجع Prerequisites for key vault integration.

هام

عند إضافة سر مخزن مفاتيح إلى مثيل APIM الخاص بك، يجب أن يكون لديك أذونات لسرد الأسرار من مخزن المفاتيح.

تنبيه

عند استخدام البيانات السرية لkey vault في APIM، يجب الحرص على عدم حذف البيانات السرية key vault أو هوية مدارة المستخدمة للوصول إلى key vault.

  1. في مدخل Azure، انتقل إلى مثيل API Management الخاص بك.

  2. ضمن واجهات برمجة التطبيقات، حدد القيم>المسماة+ إضافة.

  3. ادخل اسم المعرف، وادخلعرض الاسم المستخدم في الإشارة المرجعية للخاصية في النهج.

  4. أضف علامة اختيارية واحدة أو أكثر للمساعدة في تنظيم القيم المسماة.

  5. في القائمة المنسدلة النوع ، حدد مخزن المفاتيح.

  6. أدخل معرف البيانات السرية key vault (بدون إصدار)، أو اختر تحديد لتحديد البيانات السرية من key vault.

    هام

    إذا أدخلت معرفا سريا key vault بنفسك، فتأكد من عدم وجود معلومات حول الإصدار. وإلا، لن يتم تدوير السر تلقائيا في APIM بعد تحديث في key vault.

  7. في Client identity، حدد هوية مُدارة معينة من قِبل النظام أو هوية مُدارة معينة من قِبل المستخدم. تعرف على كيفية إضافة أو تعديل الهويات المُدارة في خدمة API Management.

    إشعار

    تحتاج الهوية إلى أذونات للحصول على أسرار من key vault وسردها. إذا لم تكن قد قمت بتكوين الوصول إلى key vault، فإن APIM تطالبك حتى تتمكن من تكوين الهوية تلقائيا باستخدام الأذونات اللازمة.

  8. حدد حفظ، ثم حدد إنشاء.

    إضافة قيمة سرية لخزنة المفاتيح

إضافة قيمة عادية أو سرية إلى APIM

  1. في مدخل Azure، انتقل إلى مثيل API Management الخاص بك.
  2. أسفلAPI حددNamed values>+Add.
  3. ادخل اسم المعرف، وادخلعرض الاسم المستخدم في الإشارة المرجعية للخاصية في النهج.
  4. في القائمة المنسدلة النوع ، حدد عادي أو سري.
  5. في Value، أدخل سلسلة أو تعبير نهج.
  6. أضف علامة اختيارية واحدة أو أكثر للمساعدة في تنظيم القيم المسماة، ثم حفظ.
  7. حدد إنشاء.

بمجرد إنشاء القيمة المسماة، يمكنك تحريرها عن طريق تحديد الاسم. إذا قمت بتغيير اسم العرض، يتم تحديث أي نهج يشير إلى تلك القيمة المسماة تلقائيا لاستخدام اسم العرض الجديد.

استخدام قيمة مسماة

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

الاسم القيمة‬ سر
ContosoHeader TrackingId خطأ
ContosoHeaderValue •••••••••••••••••••••• صواب
ExpressionProperty @(DateTime.Now.ToString()) خطأ
ContosoHeaderValue2 This is a header value. خطأ

لاستخدام قيمة مسماة في نهج ما، ضع اسم العرض الخاص به داخل زوج مزدوج من الأقواس مثل{{ContosoHeader}}، كما هو موضح في المثال التالي:

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

في هذا المثال، ContosoHeader يستخدم كعنوان في set-header policy ContosoHeaderValue ويستخدم كقيمة ذلك العنوان. عند تقييم هذا النهج أثناء طلب أو استجابة مدخل APIM {{ContosoHeader}} وكذلك {{ContosoHeaderValue}} استبدالها بالقيم الخاصة بها.

يمكنك استخدام القيم المسماة كقيم سمة كاملة أو عناصر كما هو موضح في المثال السابق، ولكن يمكن أيضا إدراجها أو دمجها مع جزء من تعبير نصي حرفي كما هو موضح في المثال التالي:

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

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

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

عند تقييم هذا النهج، {{ExpressionProperty}} يتم استبداله @(DateTime.Now.ToString()) بقيمتها. نظرا لأن القيمة عبارة عن تعبير نهج، يتم تقييم التعبير ويستمر النهج في تنفيذه.

يمكنك اختبار هذا في مدخل Microsoft Azure أو مدخل developer عن طريق استدعاء عملية لها نهج مع القيم المسماة في النطاق. في المثال التالي، يتم استدعاء عملية مع نهجين المثال السابق set-headerمع القيم المسماة. لاحظ أن الاستجابة تحتوي على رأسين مخصصين تم تكوينهما باستخدام نهج ذات قيم مسماة.

لقطة شاشة لاستجابة واجهة برمجة تطبيقات الاختبار.

إذا نظرت إلى API trace الصادرة عن استدعاء يتضمن نهجين نموذج سابقين مع قيم مسماة، يمكنك مشاهدة set-header النهجين مع القيم المسماة إدراج وكذلك تقييم تعبير النهج للقيمة المسماة التي تحتوي على تعبير النهج.

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

يمكنك أيضا استخدام استيفاء السلسلة مع القيم المسماة.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

ستكون قيمة CustomHeaderThe URL encoded value is This+is+a+header+value..

تنبيه

إذا كان النهج يشير إلى سر في Azure Key Vault، فستكون القيمة من مخزن المفاتيح مرئية للمستخدمين الذين لديهم حق الوصول إلى الاشتراكات الممكنة لتتبع طلب واجهة برمجة التطبيقات.

بينما يمكن أن تحتوي القيم المسماة على تعبيرات النهج، لا يمكن أن تحتوي على قيم أخرى مسماة. إذا تم استخدام نص يحتوي على مرجع قيمة مسمى لقيمة، مثل Text: {{MyProperty}}، تعذر حل مشكلة هذا المرجع واستبداله.

حذف قيمة مسماة

لحذف قيمة مسماة، حدد الاسم، ثم حدد حذف من قائمة السياق (...).

هام

إذا تمت الإشارة إلى القيمة المسماة بواسطة أي نهج APIM، لا يمكنك حذفها حتى تقوم بإزالة القيمة المسماة من كافة النهج التي تستخدمها.

المحتويات ذات الصلة

مزيد من المعلومات حول التعامل مع السياسات:

  • Last updated on