إضافة إجراءات مخصصة إلى واجهة برمجة تطبيقات REST من Azure

مقالة
06/01/2023

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

كيفية تعريف نقطة نهاية الإجراء

نقطة النهاية هي عنوان URL الذي يشير إلى خدمة، والتي تنفذ الاتفاق الأساسي بينها وبين Azure. يتم تعريف نقطة النهاية في موفر الموارد المخصصة ويمكن أن يكون أي URL يمكن الوصول إليه بشكل عام. تحتوي العينة أدناه على إجراء يسمى myCustomAction وتم تنفيذه من قِبل endpointURL.

عينة موفر الموارد:

{
  "properties": {
    "actions": [
      {
        "name": "myCustomAction",
        "routingType": "Proxy",
        "endpoint": "https://{endpointURL}/"
      }
    ]
  },
  "location": "eastus",
  "type": "Microsoft.CustomProviders/resourceProviders",
  "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}",
  "name": "{resourceProviderName}"
}

تحويل نقطة نهاية إجراء برمجياً

يجب على نقطة النهاية التي تقوم بتنفيذ إجراء معالجة الطلب والاستجابة لواجهة التطبيقات الجديدة في Azure. عند إنشاء موفر موارد مخصصة مع إجراء، فإنه سيتم إنشاء مجموعة جديدة من واجهات برمجة التطبيقات في Azure. في هذه الحالة، سيقوم الإجراء بإنشاء واجهة برمجة تطبيقات جديدة للإجراء من Azure لاستدعاءات POST:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}/myCustomAction

الطلب الوارد لواجهة برمجة تطبيقات Azure:

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}/myCustomAction?api-version=2018-09-01-preview
Authorization: Bearer eyJ0e...
Content-Type: application/json

{
    "myProperty1": "myPropertyValue1",
    "myProperty2": {
        "myProperty3" : "myPropertyValue3"
    }
}

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

POST https://{endpointURL}/?api-version=2018-09-01-preview
Content-Type: application/json
X-MS-CustomProviders-RequestPath: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}/myCustomAction

{
    "myProperty1": "myPropertyValue1",
    "myProperty2": {
        "myProperty3" : "myPropertyValue3"
    }
}

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

مستند عنصر JSON صالح. يجب أن تتداخل جميع الصفائف والسلاسل ضمن عنصر علوي.
يجب تعيين العنوان Content-Type إلى "application/json; charset=utf-8".

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "myProperty1": "myPropertyValue1",
    "myProperty2": {
        "myProperty3" : "myPropertyValue3"
    }
}

استجابة موفر الموارد المخصصة من Azure:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "myProperty1": "myPropertyValue1",
    "myProperty2": {
        "myProperty3" : "myPropertyValue3"
    }
}

استدعاء إجراء مخصص

هناك طريقتان رئيسيتان لإلغاء إجراء مخصص من موفر مورد مخصص:

Azure CLI
قوالب Azure Resource Manager

Azure CLI

az resource invoke-action --action {actionName} \
                          --ids /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName} \
                          --request-body \
                            '{
                                "myProperty1": "myPropertyValue1",
                                "myProperty2": {
                                    "myProperty3": "myPropertyValue3"
                                }
                            }'

المعلمة	مطلوب	الوصف
إجراء	نعم	اسم الإجراء المحدد في ResourceProvider.
ids	نعم	معرف المورد من ResourceProvider.
request-body	لا	نص الطلب الذي سيتم إرساله إلى نقطة النهاية.

قالب Azure Resource Manager

ملاحظة

الإجراءات التي حددت الدعم في قوالب Azure Resource Manager. لكي يتم استدعاء الإجراء داخل قالب، يجب أن يحتوي على البادئة list داخل اسمه.

عينة ResourceProvider مع إجراء القائمة:

{
  "properties": {
    "actions": [
      {
        "name": "listMyCustomAction",
        "routingType": "Proxy",
        "endpoint": "https://{endpointURL}/"
      }
    ]
  },
  "location": "eastus"
}

عينة قالب Azure Resource Manager:

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "variables": {
        "resourceIdentifier": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/{resourceProviderName}",
        "apiVersion": "2018-09-01-preview",
        "functionValues": {
            "myProperty1": "myPropertyValue1",
            "myProperty2": {
                "myProperty3": "myPropertyValue3"
            }
        }
    },
    "resources": [],
    "outputs": {
        "myCustomActionOutput": {
            "type": "object",
            "value": "[listMyCustomAction(variables('resourceIdentifier'), variables('apiVersion'), variables('functionValues'))]"
        }
    }
}

المعلمة	مطلوب	الوصف
resourceIdentifier	نعم	معرف المورد من ResourceProvider.
apiVersion	نعم	إصدار واجهة برمجة التطبيقات لوقت تشغيل المورد. يجب أن يكون هذا دائماً "2018-09-01-preview".
functionValues	لا	نص الطلب الذي سيتم إرساله إلى نقطة النهاية.

Share via