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

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

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

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

أنواع القيم

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

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

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

Key vault secrets

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

يوصى باستخدام أسرار الخزنة الرئيسية لأنها تساعد على تحسين أمان APIM:

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

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

• إذا لم تنشئ بعد مثيل خدمة إدارة API، راجع إنشاء مثيل خدمة إدارة API.

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

• إذا لم يكن لديك مخزن مفاتيح بالفعل، فبادر بإنشاء مخزن. لمعرفة خطوات إنشاء مخزن مفاتيح، راجع التشغيل السريع: إنشاء مخزن مفاتيح باستخدام مدخل Microsoft Azure.

  لإنشاء سر أو استيراده إلى مخزن المفاتيح، راجع التشغيل السريع: تعيين سر واسترداده من Azure Key Vault باستخدام مدخل Microsoft Azure.

• تمكين managed identity معينة من قبل النظام أو المعينة من قبل المستخدم في مثيل APIM.

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

1. في المدخل، انتقل إلى key vault.

2. في القائمة اليسرى، حدد Access configuration، ولاحظ نموذج الإذن الذي تم تكوينه.

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

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

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

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

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

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

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

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

• في جدار الحماية Key Vault، قم بتمكين الخيار Allow Trusted Microsoft Services to bypass this firewall.

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

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

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

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

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

للتفاصيل راجع تكوين الشبكة عند إعداد إدارة واجهة برمجة التطبيقات Azure في VNET.

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

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

راجع Prerequisites for key vault integration.

هام

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

تنبيه

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

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

2. أسفلAPI حددNamed values>+Add.

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

4. في Value type، حدد Key vault.

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

   هام

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

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

   إشعار

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

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

8. حدد إنشاء.

   

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

المدخل

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

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

Azure CLI

للبدء في استخدام Azure CLI:

• استخدم بيئة Bash في Azure Cloud Shell. لمزيد من المعلومات، راجع التشغيل السريع ل Bash في Azure Cloud Shell.

  

• إذا كنت تفضل تشغيل أوامر مرجع CLI محلياً قم بتثبيت CLI Azure. إذا كنت تعمل على نظام تشغيل Windows أو macOS، ففكر في تشغيل Azure CLI في حاوية Docker. لمزيد من المعلومات، راجع كيفية تشغيل Azure CLI في حاوية Docker.

  • إذا كنت تستخدم تثبيت محلي، يُرجى تسجيل الدخول إلى Azure CLI مستخدمًا أمر az login. لإنهاء عملية المصادقة، اتبع الخطوات المعروضة في جهازك. للحصول على خيارات أخرى لتسجيل دخول، راجع تسجيل الدخول باستخدام Azure CLI.

  • عندما يُطلب منك، قم بتثبيت ملحق Azure CLI عند الاستخدام لأول مرة. لمزيد من المعلومات بشأن الامتدادات، راجع استخدام امتدادات مع Azure CLI.

  • يُرجى تشغيل إصدار az للوصول إلى الإصدار والمكتبات التابعة التي تم تثبيتها. للتحديث لآخر إصدار، يُرجى تشغيل تحديث az.

لإضافة قيمة مسماة، استخدم الأمر az apim nv create:

az apim nv create --resource-group apim-hello-word-resource-group \
    --display-name "named_value_01" --named-value-id named_value_01 \
    --secret true --service-name apim-hello-world --value test

بعد إنشاء قيمة مسماة، يمكنك تحديثه باستخدام الأمر az apim nv update. لمشاهدة كافة القيم المسماة الخاصة بك، قم بتشغيل الأمر az apim nv list:

az apim nv list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

لمشاهدة تفاصيل القيمة المسماة التي قمت بإنشائها لهذا المثال، قم بتشغيل الأمرaz apim nv show:

az apim nv show --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

هذا المثال قيمة سرية. لا يُرجّع الأمر السابق القيمة. لمراجعة القيمة، قم بتشغيل الأمر az apim nv show-secret:

az apim nv show-secret --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

لحذف قيمة مسماة، استخدم الأمر az apim nv delete:

az apim nv delete --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

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

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

الاسم	القيمة‬	سر
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، ستكون القيمة من Key Vault مرئية للمستخدمين الذين لديهم حق الوصول إلى الاشتراكات الممكنة لتتبع طلب API.

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

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

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

هام

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

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

• تعرف على المزيد حول العمل باستخدام النهج
  • النُهج في API Management
  • مرجع النهج
  • تعبيرات النهج