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

توضح هذه المقالة كيفية إعداد سير عمل إجراءات GitHub الأساسية لتسجيل واجهة برمجة تطبيقات في مركز واجهة برمجة التطبيقات لمؤسستك عند إضافة ملف مواصفات واجهة برمجة التطبيقات إلى مستودع GitHub.

يوفر استخدام سير عمل GitHub Actions لتسجيل واجهات برمجة التطبيقات في مركز واجهة برمجة التطبيقات عملية CI/CD متناسقة وقابلة للتكرار لكل واجهة برمجة تطبيقات جديدة أو محدثة. يمكن توسيع سير العمل ليشمل خطوات مثل إضافة بيانات التعريف إلى تسجيل واجهة برمجة التطبيقات.

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

1. إعداد سير عمل GitHub Actions في المستودع الخاص بك الذي يتم تشغيله عند دمج طلب سحب إضافة ملف تعريف واجهة برمجة التطبيقات.
2. إنشاء فرع من الفرع الرئيسي في مستودع GitHub الخاص بك.
3. أضف ملف تعريف واجهة برمجة التطبيقات، وقم بتنفيذ التغييرات، وادفع إلى الفرع الجديد.
4. إنشاء طلب سحب لدمج الفرع الجديد في الفرع الرئيسي.
5. دمج طلب السحب.
6. يؤدي الدمج إلى تشغيل سير عمل GitHub Actions الذي يسجل واجهة برمجة التطبيقات في مركز API الخاص بك.

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

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

• أذونات لإنشاء كيان خدمة في مستأجر معرف Microsoft Entra

• حساب GitHub وم مستودع GitHub حيث يمكنك تكوين الأسرار وسير عمل إجراءات GitHub

• بالنسبة إلى 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 apic تتطلب apic-extension الأوامر ملحق Azure CLI. إذا لم تكن قد استخدمت az apic الأوامر، يمكن تثبيت الملحق ديناميكيا عند تشغيل الأمر الأول az apic ، أو يمكنك تثبيت الملحق يدويا. تعرف على المزيد حول ملحقات Azure CLI.

  راجع ملاحظات الإصدار للاطلاع على آخر التغييرات والتحديثات في apic-extension. قد تتطلب بعض الميزات معاينة أو إصدار معين من الملحق.

  إشعار

  يمكن تشغيل أمثلة أوامر Azure CLI في هذه المقالة في PowerShell أو bash shell. عند الحاجة بسبب بناء جملة متغير مختلف، يتم توفير أمثلة أوامر منفصلة للقذيفتين.

إعداد سير عمل إجراءات GitHub

في هذا القسم، يمكنك إعداد سير عمل GitHub Actions لهذا السيناريو:

• إنشاء كيان خدمة لاستخدامه لبيانات اعتماد Azure في سير العمل.
• أضف بيانات الاعتماد كبيانات سرية في مستودع GitHub الخاص بك.
• تكوين سير عمل GitHub Actions الذي يتم تشغيله عند دمج طلب سحب يضيف ملف تعريف واجهة برمجة التطبيقات. يتضمن ملف YAML لسير العمل خطوة تستخدم Azure CLI لتسجيل واجهة برمجة التطبيقات في مركز واجهة برمجة التطبيقات من ملف التعريف.

إعداد سر كيان الخدمة

في الخطوات التالية، قم بإنشاء كيان خدمة معرف Microsoft Entra، والذي سيتم استخدامه لإضافة بيانات اعتماد إلى سير العمل للمصادقة مع Azure.

أنشئ كيان خدمة باستخدام الأمر az ad sp create-for-rbac. يستخدم المثال التالي أولا الأمر az apic show لاسترداد معرف المورد لمركز API. ثم يتم إنشاء كيان الخدمة مع دور مساهم خدمة مركز واجهة برمجة تطبيقات Azure لمركز واجهة برمجة التطبيقات.

#! /bin/bash
apiCenter=<api-center-name>
resourceGroup=<resource-group-name>
spName=<service-principal-name>

apicResourceId=$(az apic show --name $apiCenter --resource-group $resourceGroup --query "id" --output tsv)

az ad sp create-for-rbac --name $spName --role "Azure API Center Service Contributor" --scopes $apicResourceId --json-auth

# PowerShell syntax
$apiCenter = "<api-center-name>"
$resourceGroup = "<resource-group-name>"
$spName = "<service-principal-name>"

$apicResourceId = $(az apic show --name $apiCenter --resource-group $resourceGroup --query "id" --output tsv)

az ad sp create-for-rbac --name $spName --role "Azure API Center Service Contributor" --scopes $apicResourceId --json-auth

انسخ إخراج JSON، والذي يجب أن يبدو مشابها للآتي:

{
  "clientId": "<GUID>",
  "clientSecret": "<GUID>",
  "subscriptionId": "<GUID>",
  "tenantId": "<GUID>",
  "activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
  "resourceManagerEndpointUrl": "https://management.azure.com/",
  [...other endpoints...]
}

إضافة كيان الخدمة كسر GitHub

1. في GitHub، تصفح المستودع الخاص بك. حدد الإعدادات.

2. ضمن Security، حدد Secrets and variables>Actions

3. حدد سر مستودع جديد.

4. الصق ناتج JSON بالكامل من أمر واجهة سطر الأوامر Azure في حقل قيمة بيانات الدخول السرية. اسم السر AZURE_CREDENTIALS. حدد ⁧⁩Add secret⁧⁩.

   يتم سرد البيانات السرية ضمن Repository secrets.

   

عند تكوين ملف سير عمل GitHub لاحقا، يمكنك استخدام السر لإدخال credsإجراء Azure/login . على سبيل المثال:

- uses: azure/login@v1
  with:
    creds: ${{ secrets.AZURE_CREDENTIALS }}

إضافة ملف سير العمل إلى مستودع GitHub الخاص بك

يتم تمثيل سير عمل GitHub Actions بواسطة ملف تعريف YAML (.yml). ويتضمن هذا التعريف الخطوات والمعلمات المختلفة التي تشكّل سير العمل. معرفة المزيد

فيما يلي ملف سير عمل أساسي لهذا المثال يمكنك استخدامه أو تعديله.

في هذا المثال:

• يتم تشغيل سير العمل عند إغلاق طلب سحب يضيف تعريف JSON في APIs المسار على الفرع الرئيسي.
• يتم استخراج موقع التعريف من طلب السحب باستخدام برنامج نصي GitHub، والذي تتم مصادقته مع رمز GitHub المميز الافتراضي.
• تستخدم بيانات اعتماد Azure المحفوظة في المستودع لتسجيل الدخول إلى Azure.
• يسجل الأمر az apic register واجهة برمجة التطبيقات في مركز API المحدد في متغيرات البيئة.

لتكوين ملف سير العمل:

1. انسخ الملف واحفظه باسم مثل register-api.yml.
2. قم بتأكيد أو تحديث اسم مجلد المستودع (APIs) حيث ستضيف ملف تعريف واجهة برمجة التطبيقات.
3. أضف ملف سير العمل هذا في /.github/workflows/ المسار في مستودع GitHub الخاص بك.
4. تعيين متغيراتSERVICE_NAME الإجراءات وفي RESOURCE_GROUP المستودع الخاص بك لاسم مركز واجهة برمجة التطبيقات واسم مجموعة الموارد في Azure.

name: Register API Definition to Azure API Center
on:
  pull_request:
    types: [ closed ]
    branches:
      - [ "main" ]
    paths:
      - "APIs/**/*.json"
permissions:
  contents: read
  pull-requests: read
jobs:
  register:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v2
      
      - name: Get specification file path in the PR
        id: get-file-location
        uses: actions/github-script@v5
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const pull_number = context.payload.pull_request.number;
            const owner = context.repo.owner;
            const repo = context.repo.repo;
            const files = await github.rest.pulls.listFiles({
              owner,
              repo,
              pull_number
            });
            if (files.data.length === 1) {
              const filename = files.data[0].filename;
              core.exportVariable('API_FILE_LOCATION', filename);
              console.log(`API_FILE_LOCATION: ${{ env.API_FILE_LOCATION }}`);
            }
            else {
              console.log('The PR does not add exactly one specification file.');
            }

      - name: Azure login
        uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}

      - name: Register to API Center
        uses: azure/CLI@v2
        with:
          azcliversion: latest
          inlineScript: |
            az apic api register -g ${{ vars.RESOURCE_GROUP }} -n ${{ vars.SERVICE_NAME }} --api-location ${{ env.API_FILE_LOCATION }}

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

اختبر سير العمل عن طريق إضافة ملف تعريف واجهة برمجة التطبيقات إلى المستودع. اتبع هذه الخطوات عالية المستوى، والتي تعد نموذجية لسير عمل التطوير. للحصول على تفاصيل حول العمل مع فروع GitHub، راجع وثائق GitHub.

1. إنشاء فرع عمل جديد من الفرع الرئيسي في المستودع الخاص بك.

2. أضف ملف تعريف واجهة برمجة التطبيقات إلى المستودع في APIs المسار. على سبيل المثال، APIs/catfacts-api/07-15-2024.json

3. قم بتنفيذ التغييرات ودفعها إلى فرع العمل.

4. إنشاء طلب سحب لدمج فرع العمل في الفرع الرئيسي.

5. بعد المراجعة، قم بدمج طلب السحب. يؤدي الدمج إلى تشغيل سير عمل GitHub Actions الذي يسجل واجهة برمجة التطبيقات في مركز واجهة برمجة التطبيقات.

   

تحقق من تسجيل واجهة برمجة التطبيقات

تحقق من تسجيل واجهة برمجة التطبيقات في مركز واجهة برمجة التطبيقات.

1. في مدخل Microsoft Azure، انتقل إلى مركز واجهة برمجة التطبيقات.
2. في القائمة اليسرى، ضمن Assets، حدد APIs.
3. تحقق من ظهور واجهة برمجة التطبيقات المسجلة حديثا في قائمة واجهات برمجة التطبيقات.

إضافة إصدار واجهة برمجة تطبيقات جديد

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

1. قم بالتغيير إلى نفس فرع العمل في المستودع الخاص بك، أو قم بإنشاء فرع عمل جديد.
2. أضف ملف تعريف API جديدا إلى المستودع في APIs المسار، في المجلد لواجهة برمجة تطبيقات موجودة. على سبيل المثال، إذا قمت مسبقا بإضافة تعريف Cat Facts API، أضف إصدارا جديدا مثل APIs/catfacts-api/07-22-2024.json.
3. قم بتنفيذ التغييرات ودفعها إلى فرع العمل.
4. إنشاء طلب سحب لدمج فرع العمل في الفرع الرئيسي.
5. بعد المراجعة، قم بدمج طلب السحب. يؤدي الدمج إلى تشغيل سير عمل GitHub Actions الذي يسجل إصدار واجهة برمجة التطبيقات الجديد في مركز واجهة برمجة التطبيقات.
6. في مدخل Microsoft Azure، انتقل إلى مركز واجهة برمجة التطبيقات وتأكد من تسجيل الإصدار الجديد.

توسيع السيناريو

يمكنك توسيع سير عمل GitHub Actions لتضمين خطوات أخرى، مثل إضافة بيانات التعريف لتسجيل واجهة برمجة التطبيقات. على سبيل المثال:

1. باستخدام مخطط بيانات التعريف في مركز واجهة برمجة التطبيقات، قم بإنشاء ملف JSON لبيانات التعريف لتطبيق قيم بيانات التعريف على تسجيل واجهة برمجة التطبيقات.

   على سبيل المثال، إذا كان مخطط بيانات التعريف يتضمن خصائص مثل approverو teamو cost center، فقد يبدو ملف JSON لبيانات التعريف كما يلي:

   {
     "approver": "diego@contoso.com",
     "team": "Store API dev team",
     "costCenter": "12345"  
   }
   

2. تحميل ملف JSON لبيانات التعريف في المجلد لكل واجهة برمجة تطبيقات في المستودع.

3. أضف خطوة سير عمل لتطبيق بيانات التعريف على تسجيل واجهة برمجة التطبيقات باستخدام الأمر az apic api update . في المثال التالي، يتم تمرير معرف API وملف بيانات التعريف في متغيرات البيئة، والتي سيتم تعيينها في مكان آخر في ملف سير العمل.

   [...]
   - name: Apply metadata to API in API Center
       uses: azure/CLI@v2
       with:
         azcliversion: latest
         inlineScript: |
           az apic api update -g ${{ vars.RESOURCE_GROUP }} -n ${{ vars.SERVICE_NAME }} --api-id {{ env.API_ID }} --custom-properties {{ env.METADATA_FILE }}
   

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

• استخدام الأسرار في GitHub Actions
• إنشاء متغيرات التكوين لمستودع