استخدام نوع المحتوى لتخزين قيم مفاتيح JSON في تكوين التطبيق

يتم تخزين البيانات في App Configuration كقيم مفاتيح، حيث يتم التعامل مع القيم كنوع السلسلة بشكل افتراضي. ومع ذلك، يمكنك تحديد نوع مخصص باستخدام خاصية نوع المحتوى المقترنة بكل قيمة مفتاح. تحافظ هذه العملية على النوع الأصلي لبياناتك أو تجعل تطبيقك يتصرف بشكل مختلف استنادا إلى نوع المحتوى.

نظرة عامة

في App Configuration، يمكنك استخدام نوع وسائط JSON كنوع محتوى لقيم المفاتيح للاستفادة من المزايا التالية:

• إدارة البيانات الأبسط: ستصبح إدارة قيم المفاتيح، مثل الصفائف، أسهل بكثير في مدخل Microsoft Azure.
• تصدير البيانات المحسن: سيتم الاحتفاظ بالأنواع الأولية والصفائف وعناصر JSON أثناء تصدير البيانات.
• الدعم الأصلي مع موفر App Configuration: ستعمل قيم المفاتيح مع نوع محتوى JSON بشكل جيد عند استهلاكها بواسطة مكتبات موفر تكوين التطبيق في تطبيقاتك.

نوع محتوى JSON صالح

يمكن تعيين أنواع الوسائط، كما هو محدد هنا، إلى نوع المحتوى المقترن بكل قيمة مفتاح. يتكون نوع الوسائط من نوع ونوع فرعي. إذا كان النوع هو application والنوع الفرعي (أو اللاحقة) هو json، اعتبار نوع الوسائط نوع محتوى JSON صالحا. بعض الأمثلة على أنواع محتويات JSON الصالحة هي:

• application/json
• application/activity+json
• application/vnd.foobar+json;charset=utf-8

قيم JSON صالحة

عندما تحتوي قيمة المفتاح على نوع محتوى JSON، يجب أن تكون قيمته بتنسيق JSON صالح للعملاء لمعالجته بشكل صحيح. وإلا، فقد يفشل العملاء أو يعودون ويعاملونها بتنسيق سلسلة. بعض الأمثلة على قيم JSON الصالحة هي:

• "John Doe"
• 723
• false
• null
• "2020-01-01T12:34:56.789Z"
• [1, 2, 3, 4]
• {"ObjectSetting":{"Targeting":{"Default":true,"Level":"Information"}}}

‏‫ملاحظة

بالنسبة لبقية هذه المقالة، ستتم الإشارة إلى أي قيمة مفتاح في App Configuration تحتوي على نوع محتوى JSON صالح وقيمة JSON صالحة باسم قيمة مفتاح JSON.

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

• إنشاء قيم مفتاح JSON في تكوين التطبيق.
• استيراد قيم مفتاح JSON من ملف JSON.
• تصدير قيم مفتاح JSON إلى ملف JSON.
• استهلاك قيم مفتاح JSON في تطبيقاتك.

إذا لم يكن لديك حساب Azure، فأنشئ حساباً مجانياً قبل أن تبدأ.

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

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

  

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

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

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

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

• متجر App Configuration، كما هو موضح في البرنامج التعليمي لإنشاء متجر.
• يتطلب هذا البرنامج التعليمي الإصدار 2.10.0 أو أحدث من Azure CLI. إذا كنت تستخدم Azure Cloud Shell، يتم تثبيت أحدث إصدار بالفعل.

إنشاء قيم مفاتيح JSON في تكوين التطبيق

يمكن إنشاء قيم مفاتيح JSON باستخدام مدخل Microsoft Azure أو Azure CLI أو عن طريق الاستيراد من ملف JSON. في هذا القسم، ستجد إرشادات حول إنشاء نفس قيم مفاتيح JSON باستخدام جميع الأساليب الثلاثة.

إنشاء قيم مفاتيح JSON باستخدام مدخل Microsoft Azure

أضف قيم المفاتيح التالية إلى متجر App Configuration. اترك Label بقيمتها الافتراضية. لمزيد من المعلومات حول كيفية إضافة قيم المفاتيح إلى مخزن باستخدام مدخل Microsoft Azure أو CLI، انتقل إلى إنشاء قيمة مفتاح.

المفتاح	القيمة	نوع المحتوى
الإعدادات:لون الخلفية	"أخضر"	application/json
الإعدادات:حجم الخط	24	application/json
الإعدادات:UseDefaultRouting	خطأ	application/json
الإعدادات:المستخدمون المحظورون	صِفْر	application/json
الإعدادات:تاريخ الإصدار	"2020-08-04T12:34:56.789Z"	application/json
الإعدادات:RolloutPercentage	[25,50,75,100]	application/json
الإعدادات:التسجيل	{"Test":{"Level":"Debug"},"Prod":{"Level":"Warning"}}	application/json

1. حدد تطبيق.

إنشاء قيم مفاتيح JSON باستخدام Azure CLI

ستنشئ الأوامر التالية قيم مفاتيح JSON في متجر App Configuration. استبدل <appconfig_name> باسم متجر App Configuration.

appConfigName=<appconfig_name>
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:BackgroundColor --value \"Green\"
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:FontSize --value 24
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:UseDefaultRouting --value false
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:BlockedUsers --value null
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:ReleaseDate --value \"2020-08-04T12:34:56.789Z\"
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:RolloutPercentage --value [25,50,75,100]
az appconfig kv set -n $appConfigName --content-type application/json --key Settings:Logging --value {\"Test\":{\"Level\":\"Debug\"},\"Prod\":{\"Level\":\"Warning\"}}

هام

إذا كنت تستخدم Azure CLI أو Azure Cloud Shell لإنشاء قيم مفاتيح JSON، يجب أن تكون القيمة المقدمة سلسلة JSON مهربة.

استيراد قيم مفتاح JSON من ملف

أنشئ ملف JSON يسمى Import.json بالمحتوى التالي واستورده كقيم مفاتيح إلى App Configuration:

{
  "Settings": {
    "BackgroundColor": "Green",
    "BlockedUsers": null,
    "FontSize": 24,
    "Logging": {"Test":{"Level":"Debug"},"Prod":{"Level":"Warning"}},
    "ReleaseDate": "2020-08-04T12:34:56.789Z",
    "RolloutPercentage": [25,50,75,100],
    "UseDefaultRouting": false
  }
}

az appconfig kv import -s file --format json --path "~/Import.json" --content-type "application/json" --separator : --depth 2

‏‫ملاحظة

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

يجب أن تبدو قيم مفتاح JSON التي قمت بإنشائها كما يلي في تكوين التطبيق:

للتحقق من ذلك، افتح مورد تكوين التطبيق في مدخل Microsoft Azure وانتقل إلى مستكشف التكوين.

تصدير قيم مفتاح JSON إلى ملف

تتمثل إحدى الفوائد الرئيسية لاستخدام قيم مفاتيح JSON في القدرة على الحفاظ على نوع البيانات الأصلي لقيمك أثناء التصدير. إذا لم يكن لقيمة المفتاح في App Configuration نوع محتوى JSON، التعامل مع قيمته كسلسلة.

ضع في اعتبارك قيم المفاتيح هذه بدون نوع محتوى JSON:

المفتاح	القيمة	نوع المحتوى
الإعدادات:حجم الخط	24
الإعدادات:UseDefaultRouting	خطأ

عند تصدير قيم المفاتيح هذه إلى ملف JSON، سيتم تصدير القيم كسلاسل:

{
  "Settings": {
    "FontSize": "24",
    "UseDefaultRouting": "false"
  }
}

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

az appconfig kv export -d file --format json --path "~/Export.json" --separator :

‏‫ملاحظة

إذا كان متجر App Configuration الخاص بك يحتوي على بعض القيم الرئيسية بدون نوع محتوى JSON، تصديرها أيضا إلى نفس الملف بتنسيق سلسلة.

استهلاك قيم مفتاح JSON في التطبيقات

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

على سبيل المثال، إذا كان لديك قيمة المفتاح التالية في تكوين التطبيق:

المفتاح	القيمة	نوع المحتوى
الإعدادات	{"FontSize":24,"UseDefaultRouting":false}	تطبيق/json

سيكون لتكوين تطبيق .NET الخاص بك القيم الرئيسية التالية:

المفتاح	القيمة
الإعدادات:حجم الخط	24
الإعدادات:UseDefaultRouting	خطأ

يمكنك الوصول إلى المفاتيح الجديدة مباشرة أو قد تختار ربط قيم التكوين بمثيلات كائنات .NET.

هام

يتوفر الدعم الأصلي لقيم مفاتيح JSON في إصدار موفر تكوين .NET 4.0.0 (أو أحدث). لمزيد من المعلومات، انتقل إلى قسم الخطوات التالية .

إذا كنت تستخدم SDK أو REST API لقراءة قيم المفاتيح من App Configuration، استنادا إلى نوع المحتوى، فإن تطبيقك مسؤول عن تحليل قيمة مفتاح JSON.

تنظيف الموارد

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

هام

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

1. سجل الدخول إلى مدخل Microsoft Azure، وحدد Resource groups.
2. في المربع تصفية حسب الاسم ، أدخل اسم مجموعة الموارد الخاصة بك.
3. في قائمة النتائج، حدد اسم مجموعة الموارد لاستعراض نظرة عامة.
4. حدد Delete resource group.
5. يُطلب منك تأكيد حذف مجموعة الموارد. أدخل اسم مجموعة الموارد للتأكيد وحدد "Delete".

بعد بضع لحظات، يتم حذف مجموعة الموارد وكافة مواردها.

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

الآن بعد أن عرفت كيفية العمل مع قيم مفاتيح JSON في متجر App Configuration، أنشئ تطبيقا لاستهلاك قيم المفاتيح هذه:

التشغيل السريع ASP.NET Core

التشغيل السريع ل .NET Core