كيفية حفظ تكوين خدمة إدارة API باستخدام Git.

مقالة
05/12/2023

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

يحتفظ كل مثيل خدمة إدارة API قاعدة بيانات تكوين تحتوي على معلومات حول التكوين وبيانات التعريف لمثيل الخدمة. يمكن إجراء تغييرات على مثيل الخدمة عن طريق تغيير إعداد في مدخل Microsoft Azure، أو استخدام أدوات Azure مثل Azure PowerShell أو Azure CLI، أو إجراء استدعاء REST API. بالإضافة إلى هذه الطرق، يمكنك إدارة تكوين مثيل الخدمة الخاص بك باستخدام Git، مما يتيح السيناريوهات مثل:

إصدار التكوين- قم بتنزيل وتخزين إصدارات مختلفة من تكوين الخدمة
تغييرات التكوين المجمعة - قم بإجراء تغييرات على أجزاء متعددة من تكوين الخدمة في المستودع المحلي الخاص بك ودمج التغييرات مرة أخرى على الخادم بعملية واحدة
سلسلة أدوات Git المألوفة وسير العمل - استخدم أدوات Git ومهام سير العمل المألوفة لديك بالفعل

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

رسم تخطيطي يقارن طرق تكوين إدارة Azure API.

عند إجراء تغييرات على خدمتك باستخدام مدخل Microsoft Azure أو أدوات Azure مثل Azure PowerShell أو Azure CLI أو REST API، فأنت تدير قاعدة بيانات تكوين الخدمة باستخدام https://{name}.management.azure-api.net نقطة النهاية، كما هو موضح على الجانب الأيمن من الرسم التخطيطي. يوضح الجانب الأيسر من الرسم التخطيطي كيفية إدارة تكوين الخدمة باستخدام مستودع Git و Git للخدمة الموجودة في https://{name}.scm.azure-api.net.

توفر الخطوات التالية نظرة عامة حول إدارة مثيل خدمة إدارة API باستخدام Git.

الوصول إلى تكوين Git في خدمتك
حفظ قاعدة بيانات تكوين الخدمة إلى مستودع Git الخاص بك
استنساخ مستودع Git إلى الجهاز المحلي الخاص بك
سحب أحدث مستودع وصولاً إلى الجهاز المحلي الخاص بك، والالتزام ودفع التغييرات مرة أخرى إلى المستودع الخاص بك
نشر التغييرات من المستودع الخاص بك في قاعدة بيانات تكوين الخدمة

توضح هذه المقالة كيفية تمكين واستخدام Git لإدارة تكوين الخدمة وتوفر مرجعًا للملفات والمجلدات في مستودع Git.

هام

تم تصميم هذه الميزة للعمل مع تكوينات خدمة APIM الصغيرة إلى المتوسطة، مثل تلك التي يقل حجم تصديرها عن 10 ميجابايت، أو مع أقل من 10000 كيان. قد تواجه الخدمات التي تحتوي على عدد كبير من الكيانات (المنتجات وواجهات برمجة التطبيقات والعمليات والمخططات وما إلى ذلك) إخفاقات غير متوقعة عند معالجة أوامر Git. في حال واجهت هذه الإخفاقات، فيرجى تقليل حجم تكوين الخدمة الخاصة بك والمحاولة مرة أخرى. اتصل بدعم Azure إذا كنت بحاجة إلى مساعدة.

الوصول إلى تكوين Git في خدمتك

انتقل إلى مثيل APIM فيمدخل Microsoft Azure.
في القائمة اليسرى، أسفل التوزيع و بنية أساسية، اختر مستودع.

لقطة شاشة توضح كيفية الوصول إلى تكوين Git لإدارة واجهة برمجة التطبيقات.

احفظ تكوين الخدمة في مستودع Git

تنبيه

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

قبل استنساخ المستودع، احفظ الحالة الحالية لتكوين الخدمة في المستودع.

في صفحة المستودع، حدد الحفظ إلى المستودع.
قم بإجراء أي تغييرات مطلوبة على شاشة التأكيد، مثل اسم الفرع لحفظ التكوين، وحدد حفظ.

بعد لحظات قليلة يتم حفظ التكوين، ويتم عرض حالة تكوين المستودع، بما في ذلك تاريخ ووقت تغيير التكوين الأخير والمزامنة الأخيرة بين تكوين الخدمة والمستودع.

بمجرد حفظ التكوين إلى المستودع، يُمكن استنساخه.

للحصول على معلومات حول حفظ تكوين الخدمة باستخدام واجهة برمجة تطبيقات REST، راجع تكوين المستأجر - حفظ.

الحصول على بيانات اعتماد الوصول

لاستنساخ مستودع، بالإضافة إلى عنوان URL إلى المستودع الخاص بك، تحتاج إلى اسم مستخدم وكلمة مرور.

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

هام

دوّن كلمة المرور هذه. بمجرد ترك هذه الصفحة لن يتم عرض كلمة المرور مرة أخرى.

استنساخ المستودع إلى جهازك المحلي

تستخدم الأمثلة التالية أداة Git Bash من Git لـ Windows ولكن يمكنك استخدام أي أداة Git تعرفها.

افتح أداة Git في المجلد المطلوب وقم بتشغيل الأمر التالي لنسخ مستودع Git إلى جهازك المحلي، باستخدام الأمر التالي:

git clone https://{name}.scm.azure-api.net/

قم بتوفير اسم المستخدم وكلمة المرور عند مطالبتك بذلك.

إذا تلقيت أية أخطاء، حاول تعديل git clone الأمر لتضمين اسم المستخدم وكلمة المرور، كما هو موضح في المثال التالي.

git clone https://username:password@{name}.scm.azure-api.net/

إذا كان هذا يوفر خطأ، حاول URL ترميز جزء كلمة المرور من الأمر. طريقة سريعة واحدة للقيام بذلك هي فتح Visual Studio، وإصدار الأمر التالي في الإطار الفوري. لفتح نافذة فورية، افتح أي حل أو مشروع في Visual Studio (أو أنشئ تطبيق وحدة تحكم فارغة جديدة)، واختر Windows، مباشرة من القائمة تتبع الأخطاء.

?System.Net.WebUtility.UrlEncode("password from the Azure portal")

استخدم كلمة المرور المشفرة مع اسم المستخدم وموقع المستودع لإنشاء الأمر git.

git clone https://username:url encoded password@{name}.scm.azure-api.net/

بعد اكتمال الاستنساخ، قم بتغيير الدليل إلى المستودع الخاص بك عن طريق تشغيل أمر مثل ما يلي.

cd {name}.scm.azure-api.net/

إذا قمت بحفظ التكوين إلى فرع آخر غير الفرع الافتراضي (master)، فراجع الفرع:

git checkout <branch_name>

بمجرد استنساخ المستودع، يمكنك عرضه والعمل معه في نظام الملفات المحلي. للحصول على مزيدٍ من المعلومات، راجع مرجع بنية الملف والمجلد في مستودع Git المحلي.

قم بتحديث مستودعك المحلي بأحدث تكوين لطبعة الخدمة

إذا قمت بإجراء تغييرات على مثيل خدمة APIM في مدخل Microsoft Azure أو باستخدام أدوات Azure الأخرى، فيجب عليك حفظ هذه التغييرات في المستودع قبل أن تتمكن من تحديث المستودع المحلي بآخر التغييرات.

لحفظ التغييرات باستخدام مدخل Microsoft Azure، حدد الحفظ إلى المستودع في علامة التبويب المستودع لمثيل APIM.

بعد ذلك، لتحديث المستودع المحلي الخاص بك:

تأكد من أنك في مجلد المستودع المحلي الخاص بك. إذا كنت قد أكملت git clone الأمر للتو، فيجب عليك تغيير الدليل إلى المستودع الخاص بك عن طريق تشغيل أمر مثل التالي.
```
cd {name}.scm.azure-api.net/
```
في المجلد الخاص بالمستودع المحلي، قم بإصدار الأمر التالي.
```
git pull
```

لدفع التغييرات من المستودع المحلي إلى مستودع الخادم

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

git add --all
git commit -m "Description of your changes"

لدفع جميع الالتزامات إلى الخادم، قم بتشغيل الأمر التالي.

git push

لتوزيع أي تغييرات تكوين خدمة إلى مثيل خدمة APIM

بمجرد الالتزام بالتغييرات المحلية ودفعها إلى مستودع الخادم، يمكنك نشرها في مثيل خدمة APIM.

انتقل إلى مثيل APIM فيمدخل Microsoft Azure.
في القائمة اليسرى، أسفل التوزيع و بنية أساسية، اختر مستودع>توزيع إلى APIM.
في صفحة توزيع تكوين المستودع، أدخل اسم الفرع الذي يحتوي على تغييرات التكوين المطلوبة، وحدد اختياريًا إزالة اشتراكات المنتجات المحذوفة. حدد حفظ.

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

مرجع بنية الملف والمجلد لمستودع Git المحلي

تحتوي الملفات والمجلدات الموجودة في مستودع Git المحلي على معلومات التكوين حول مثيل الخدمة.

عنصر	‏‏الوصف
مجلد إدارة api الجذر	يحتوي على تكوين المستوى الأعلى لمثيل الخدمة
مجلد apiReleases	يحتوي على التكوين لإصدارات API في مثيل الخدمة
مجلد apis	يحتوي على تكوين واجهات برمجة التطبيقات في مثيل الخدمة
مجلد apiVersionSets	يحتوي على تكوين مجموعات إصدار API في مثيل الخدمة
مجلد الواجهات الخلفية	يحتوي على التكوين لموارد الواجهة الخلفية في مثيل الخدمة
مجلد المجموعات	يحتوي على تكوين المجموعات في مثيل الخدمة
مجلد النهج	يحتوي على النهج في مثيل الخدمة
مجلد portalStyles	يحتوي على التكوين لتخصيصات مدخل المطور في مثيل الخدمة
مجلد portalTemplates	يحتوي على التكوين لقوالب مدخل المطور في مثيل الخدمة
مجلد المنتجات	يحتوي على تكوين المنتجات في مثيل الخدمة
مجلد القوالب	يحتوي على تكوين قوالب عنوان البريد الإلكتروني في مثيل الخدمة

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

نوع الملف	الغرض
json	معلومات التكوين حول العنصر المعني
html	وصف العنصر، غالبًا ما يتم عرضه في مدخل المطور
xml	كشوفات النهج
css	أوراق الأنماط لتخصيص مدخل المطور

يمكن إنشاء هذه الملفات وحذفها وتحريرها وإدارتها على نظام الملفات المحلي، والتغييرات التي تم نشرها مرة أخرى إلى مثيل خدمة APIM.

إشعار

الكيانات التالية غير موجودة في مستودع Git ولا يمكن تكوينها باستخدام Git.

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

مجلد إدارة api الجذر

يحتوي المجلد الجذر api-management على ملف يحتوي على معلومات المستوى configuration.json الأعلى حول مثيل الخدمة بالتنسيق التالي.

{
  "settings": {
    "RegistrationEnabled": "True",
    "UserRegistrationTerms": null,
    "UserRegistrationTermsEnabled": "False",
    "UserRegistrationTermsConsentRequired": "False",
    "DelegationEnabled": "False",
    "DelegationUrl": "",
    "DelegatedSubscriptionEnabled": "False",
    "DelegationValidationKey": "",
    "RequireUserSigninEnabled": "false"
  },
  "$ref-policy": "api-management/policies/global.xml"
}

الإعدادات الأربعة الأولى ( RegistrationEnabled وUserRegistrationTerms وUserRegistrationTermsEnabled وUserRegistrationTermsConsentRequired) خريطة إلى الإعدادات التالية في علامة التبويب الهويات في قسم مدخل المطور.

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

الإعدادات الأربعة التالية ( DelegationEnabled وDelegationUrl وDelegatedSubscriptionEnabled وDelegationValidationKey) خريطة إلى الإعدادات التالية في علامة التبويب التفويض في قسم مدخل المطور.

إعداد التفويض	تعيين إلى:
تم تمكين التفويض	تفويض التسجيل والدخول خانة الاختيار
تفويض Url	مربع نص عنوان URL لنقطة نهاية التفويض
DelegatedSubscriptionEnabled	تفويض اشتراك المنتجات خانة الاختيار
DelegationValidationKey	مفتاح التحقق من صحة التفويض مربع الاختيار

الإعداد النهائي، $ref-policy، تعيين ملف عبارات النهج العمومي لمثيل الخدمة.

مجلد apiReleases

apiReleases يحتوي المجلد على مجلد لكل إصدار من إصدارات واجهة برمجة التطبيقات التي تم نشرها في واجهة برمجة تطبيقات الإنتاج، ويحتوي على العناصر التالية.

apiReleases\<api release Id>\configuration.json - تكوين الإصدار، يحتوي على معلومات حول تواريخ الإصدار. هذه هي نفس المعلومات التي سيتم إرجاعها إذا قمت باستدعاء عملية الحصول على إصدار مخصص.

مجلد apis

apisيحتوي المجلد على مجلد لكل API في مثيل الخدمة الذي يحتوي على العناصر التالية.

apis\<api name>\configuration.json- تكوين لواجهة برمجة التطبيقات، يحتوي على معلومات حول عنوان URL للخدمة الخلفية والعمليات. هذه هي نفس المعلومات التي سيتم إرجاعها إذا كنت تريد استدعاء عملية الحصول على واجهة مخصصة لبرمجة التطبيقات .
apis\<api name>\api.description.html - وصف واجهة برمجة التطبيقات، المقابلة لخاصية description كيان واجهة برمجة التطبيقات في واجهة برمجة تطبيقات REST.
apis\<api name>\operations\- يحتوي هذا المجلد على <operation name>.description.html الملفات التي تعين العمليات في API. يحتوي كل ملف على وصف عملية واحدة في API، والتي تعين description خاصية كيان العملية في واجهة برمجة تطبيقات REST.

مجلد apiVersionSets

apiVersionSets يحتوي المجلد على مجلد لكل مجموعة إصدارات API تم إنشاؤها لواجهة برمجة التطبيقات، ويحتوي على العناصر التالية.

apiVersionSets\<api version set Id>\configuration.json - تكوين مجموعة الإصدار. هذه هي نفس المعلومات التي سيتم إرجاعها إذا قمت باستدعاء عملية الحصول على إصدار محدد.

مجلد المجموعات

groups يحتوي المجلد على مجلد لكل مجموعة معرفة في مثيل الخدمة.

groups\<group name>\configuration.json - تكوين المجموعة. هذه هي نفس المعلومات التي سيتم إرجاعها إذا كنت تريد استدعاء الحصول على مجموعة خاصة التشغيل.
groups\<group name>\description.html - هذا هو وصف المجموعة ويتوافق مع description خاصية كيان المجموعة.

مجلد النهج

policies يحتوي المجلد على عبارات النهج لمثيل الخدمة الخاص بك.

policies\global.xml - يحتوي على نهج محددة في النطاق العمومي لمثيل الخدمة.
policies\apis\<api name>\ - إذا كان لديك أي نهج معرفة في نطاق API، فهي موجودة في هذا المجلد.
policies\apis\<api name>\<operation name>\ المجلد - إذا كان لديك أي نهج معرفة في نطاق العملية، فهي موجودة في هذا المجلد في <operation name>.xml الملفات التي تعين إلى عبارات النهج لكل عملية.
policies\products\ - إذا كان لديك أي نهج معرفة في نطاق المنتجات، فهي موجودة في هذا المجلد الذي يحتوي على <product name>.xml الملفات التي تعين إلى عبارات النهج لكل منتج.

مجلد portalStyles

portalStyles يحتوي المجلد على التكوين وأوراق الأنماط لتخصيصات مدخل المطور لمثيل الخدمة.

portalStyles\configuration.json - يحتوي على أسماء أوراق الأنماط المستخدمة من قِبل مدخل المطور
portalStyles\<style name>.css - يحتوي كل <style name>.css ملف على أنماط لمدخل المطور (Preview.css و Production.css بشكل افتراضي).

مجلد portalTemplates

portalTemplates يحتوي المجلد على قوالب لتخصيص مدخل المطور المهمل لمثيل الخدمة.

portalTemplates\<template name>\configuration.json - تكوين القالب.
portalTemplates\<template name>\<page name>.html - صفحات HTML الأصلية والمعدلة للقالب.

مجلد المنتجات

products يحتوي المجلد على مجلد لكل منتج في مثيل الخدمة.

products\<product name>\configuration.json - التكوين للمنتج. هذه هي نفس المعلومات التي سيتم إرجاعها إذا كنت تريد استدعاء الحصول على منتج خاص التشغيل.
products\<product name>\product.description.html - وصف المنتج ويتوافق مع description خاصية كيان المنتج في واجهة برمجة تطبيقات REST.

القوالب

templates يحتوي المجلد على تكوين قوالب عنوان البريد الإلكتروني في مثيل الخدمة

<template name>\configuration.json - التكوين لقالب البريد الإلكتروني.
<template name>\body.html - نص قالب البريد الإلكتروني.

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

للحصول على معلومات حول طرق أخرى لإدارة مثيل الخدمة، راجع:

مشاركة عبر