العمل مع الوكلاء القدماء

مقالة
06/01/2023

هام

وكلاء Azure Functions هي ميزة قديمة للإصدارات من 1.x إلى 3.x من وقت تشغيل Azure Functions. يمكن إعادة تمكين دعم الوكلاء في الإصدار 4.x لترقية تطبيقات الوظائف بنجاح إلى أحدث إصدار من وقت التشغيل. في أقرب وقت ممكن، يجب التبديل إلى دمج تطبيقات الوظائف الخاصة بك مع Azure API Management. تتيح لك APIM الاستفادة من مجموعة أكثر اكتمالا من الميزات لتحديد واجهات برمجة التطبيقات المستندة إلى الوظائف وتأمينها وإدارتها والاستفادة منها. لمزيد من المعلومات، راجع تكامل APIM.

لمعرفة كيفية إعادة تمكين دعم الوكلاء في Functions الإصدار 4.x، راجع إعادة تمكين الوكلاء في Functions v4.x.

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

توضح هذه المقالة كيفية تكوين والعمل مع Azure Functions Proxies. باستخدام هذه الميزة، يمكنك تحديد نقاط النهاية على تطبيق الدالة الذي يتم تنفيذه بواسطة مورد آخر. يمكنك استخدام هذه الوكلاء لتقسيم API كبيرة إلى تطبيقات دالة متعددة (كما هو الحال في بنية microservice)، بينما لا يزال يقدم سطح API واحد للعملاء.

تنطبق فوترة الوظائف القياسية على عمليات التنفيذ بالوكالة. للحصول على مزيدٍ من المعلومات، راجع تسعير Azure Functions.

إعادة تمكين الوكلاء في Functions v4.x

بعد ترحيل تطبيق الوظائف إلى الإصدار 4.x من وقت تشغيل الوظائف، ستحتاج إلى وكلاء قابلين لإعادة تمكينهم على وجه التحديد. لا يزال يتعين عليك التبديل إلى دمج تطبيقات الوظائف مع Azure API Management في أقرب وقت ممكن، وليس الاعتماد فقط على الوكلاء.

تتطلب إعادة تمكين الوكلاء تعيين علامة في AzureWebJobsFeatureFlags إعداد التطبيق بإحدى الطرق التالية:

AzureWebJobsFeatureFlags إذا لم يكن الإعداد موجودا بالفعل، أضف هذا الإعداد إلى تطبيق الوظائف بقيمة EnableProxies.
إذا كان هذا الإعداد موجودا بالفعل، أضف ,EnableProxies إلى نهاية القيمة الموجودة.

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

إشعار

حتى عند إعادة التمكين باستخدام العلامة EnableProxies ، لا يمكنك العمل مع الوكلاء في مدخل Microsoft Azure. بدلا من ذلك، يجب العمل مباشرة مع ملف proxies.json لتطبيق الوظائف. لمزيد من المعلومات، راجع التكوين المتقدم.

إنشاء وكيل

هام

للحصول على محتوى مكافئ باستخدام APIM، راجع كشف واجهات برمجة التطبيقات بلا خادم من نقاط نهاية HTTP باستخدام إدارة واجهة برمجة تطبيقات Azure.

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

افتح بوابة Azure، ثم انتقل إلى تطبيق الوظائف الخاص بك.
في الجزء الأيسر، حدد الوكلاء ثم حدد + أضف .
قم بتوفير اسم للوكيل الخاص بك.
قم بتكوين نقطة النهاية التي يتم كشفها على هذا التطبيق وظيفة عن طريق تحديد قالب المساروأساليب HTTP. هذه المعلمات تتصرف وفقا لقواعد مشغلات HTTP.
قم بتعيين عنوان URL الخلفي إلى نقطة نهاية أخرى. يمكن أن تكون نقطة النهاية هذه دالة في تطبيق دالة آخر، أو قد تكون أي واجهة برمجة تطبيقات أخرى API. لا تحتاج القيمة إلى أن تكون ثابتة، ويمكن الرجوع إلى إعدادات التطبيق والمعلمات من طلب العميل الأصلي.
حدد إنشاء.

الوكيل الخاص بك موجود الآن كنقطة نهاية جديدة على تطبيق الوظيفة الخاص بك. من منظور العميل، إنه نفس HttpTrigger في Functions. يمكنك تجربة وكيلك الجديد عن طريق نسخ عنوان URL للوكيل واختباره مع عميل HTTP المفضل لديك.

تعديل الطلبات والاستجابات

هام

تتيح لك APIM تغيير سلوك واجهة برمجة التطبيقات من خلال التكوين باستخدام السياسات. النُهج هي مجموعة من العبارات التي يتم تشغيلها بشكل تسلسلي بناءً على طلب أو استجابة واجهة برمجة التطبيقات. لمزيد من المعلومات حول نُهج APIM، راجع النُهج في APIM.

باستخدام النُهج، يمكنك تعديل الطلبات والاستجابات من النهاية الخلفية. يمكن استخدام هذه التحويلات المتغيرات كما هو محدد في استخدام المتغيرات.

تعديل طلب النهاية الخلفية

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

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

تعديل الاستجابة

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

يمكن تعديل الاستجابات الخلفية في المدخل عن طريق توسيع قسم تجاوز الاستجابة لصفحة تفاصيل الوكيل.

استخدام المتغيرات

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

دالات محلية مرجعية

يمكنك استخدامه localhost للإشارة إلى وظيفة داخل نفس التطبيق وظيفة مباشرة، دون طلب وكيل ذهابًا وإيابًا.

"backendUri": "https://localhost/api/httptriggerC#1" سيتم الرجوع إلى دالة HTTP محلية مشغلة في المسار /api/httptriggerC#1

إشعار

إذا كانت الدالة تستخدم مستويات التخويل الخاصة بك أو المسؤول أو sys، فستحتاج إلى توفير التعليمات البرمجية وclientId، وفقا لعنوان URL الأصلي للدالة. في هذه الحالة، سيبدو المرجع كما يلي: "backendUri": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>" نوصي بتخزين هذه المفاتيح في إعدادات التطبيق والرجوع إلى تلك الموجودة في وكلائك. هذا يتجنب تخزين الأسرار في التعليمات البرمجية المصدر.

معلمات طلب المرجع

يمكنك استخدام معلمات الطلب كمدخلات إلى خاصية عنوان URL الخلفي أو كجزء من تعديل الطلبات والاستجابات. يمكن ربط بعض المعلمات من قالب المسار المحدد في تكوين الوكيل الأساسي، ويمكن أن تأتي معلمات أخرى من خصائص الطلب الوارد.

معلمات قالب المسار

تتوفر المعلمات المستخدمة في قالب المسار للإشارة إليها بالاسم. أسماء المعلمات محاطة في الأقواس ( {} ).

على سبيل المثال، إذا كان الوكيل يحتوي على قالب توجيه، مثل /pets/{petId}، يمكن أن يتضمن عنوان URL الخلفي قيمة، كما هو الحال في {petId}https://<AnotherApp>.azurewebsites.net/api/pets/{petId}. إذا كان قالب التوجيه ينتهي في حرف بدل، مثل /api/{*restOfPath}، فإن القيمة {restOfPath} تمثل سلسلة من قطع المسار المتبقية من الطلب الوارد.

معلمات طلب إضافية

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

{request.method}: أسلوب HTTP المستخدم في الطلب الأصلي.
{request.headers. < HeaderName >} : عنوان يمكن قراءته من الطلب الأصلي. استبدل < HeaderName > باسم العنوان الذي تريد قراءته. إذا لم يتم تضمين الرأس على الطلب، القيمة ستكون السلسلة الفارغة.
{request.querystring. < ParameterName >} : معلمة سلسلة استعلام يمكن قراءتها من الطلب الأصلي. استبدل < ParameterName > باسم المعلمة التي تريد قراءتها. إذا لم يتم تضمين المعلمة على الطلب، عندها ستكون القيمة هي السلسلة الفارغة.

معلمات الاستجابة الخلفية المرجعية

يمكن استخدام معلمات الاستجابة كجزء من تعديل الاستجابة للعميل. يمكن استخدام القيم التالية في قيم التكوين:

{backend.response.statusCode}: رمز حالة HTTP الذي تم إرجاعه في استجابة النهاية الخلفية.
{backend.response.statusReason}: عبارة سبب HTTP التي تم إرجاعها في الاستجابة الخلفية.
{backend.response.headers. < HeaderName >} : عنوان يمكن قراءته من الاستجابة الخلفية. استبدل < HeaderName > باسم العنوان الذي تريد قراءته. إذا لم يتم تضمين العنوان في الاستجابة، ستكون القيمة السلسلة الفارغة.

إعدادات التطبيق المرجعي

يمكنك أيضًا الرجوع إلى إعدادات التطبيق المعرفة لتطبيق الدالة من خلال إحاطة اسم الإعداد بعلامات النسبة المئوية (٪).

على سبيل المثال، قد يتم استبدال عنوان URL الخلفي لـ https://%ORDER_PROCESSING_HOST%/api/orders "٪ORDER_PROCESSING_HOST٪" بقيمة إعداد ORDER_PROCESSING_HOST.

تلميح

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

استكشاف أخطاء الوكلاء وإصلاحها

بإضافة العلامة "debug":true إلى أي وكيل في proxies.json الخاص بك، ستتمكن من تمكين تسجيل التصحيح. يتم تخزين السجلات فيها D:\home\LogFiles\Application\Proxies\DetailedTrace ويمكن الوصول إليها من خلال الأدوات المتقدمة (kudu). أي استجابات HTTP أيضا تحتوي على Proxy-Trace-Location عنوان مع عنوان URL للوصول إلى ملف السجل.

يمكنك تصحيح وكيل من جانب العميل عن طريق إضافة Proxy-Trace-Enabled تعيين عنوان إليهtrue. هذا أيضًا تسجيل تتبع إلى نظام الملفات ثم إرجاع URL التتبع كعنوان في الاستجابة.

حظر آثار الوكيل

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

قم بتعطيل آثار تماما عن طريق إضافة "debug":falseإلى أي وكيل معين في الخاص بك proxies.json.

تكوين متقدم

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

تلميح

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

يتم تعريف Proxies.js ككائن وكلاء، الذي يتكون من وكلاء اسمه والتعاريف الخاصة بهم. اختياريًا، إذا كان المحرر الخاص بك يدعم ذلك، يمكنك الرجوع إلى مخطط JSON لإكمال التعليمات البرمجية. قد يبدو ملف مثال كما يلي:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>"
        }
    }
}

كل وكيل له اسم مألوف، مثل proxy1 في المثال السابق. يتم تعريف كائن تعريف الوكيل المطابق بواسطة الخصائص التالية:

matchCondition: مطلوب-- كائن تعريف الطلبات التي تؤدي إلى تنفيذ هذا الوكيل. يحتوي على خاصيتين تتم مشاركتها مع مشغلات HTTP:
- أساليب: صفيف من أساليب HTTP التي يستجيب الوكيل لها. إذا لم يتم تحديد الوكيل يستجيب لكافة أساليب HTTP على المسار.
- المسار: مطلوب--يعرف قالب المسار، والتحكم في عناوين URLs للطلب الذي يستجيب الوكيل الخاص بك إليه. بعكس مشغلات HTTP، لا توجد قيمة افتراضية.
backendUri: عنوان URL للمورد الخلفي الذي يجب أن يكون الطلب وكيلًا. يمكن لهذه القيمة الرجوع إلى إعدادات التطبيق والمعلمات من طلب العميل الأصلي. إذا لم يتم تضمين هذه الخاصية، يستجيب Azure دالات مع HTTP 200 موافق.
requestOverrides:كائن يعرّف التحويلات إلى طلب النهاية الخلفية. راجع تعريف كائن requestOverrides.
requestOverrides:كائن يعرّف التحويلات إلى طلب النهاية الخلفية. راجع تعريف كائن requestOverrides.

إشعار

خاصية التوجيه في وكلاء Azure Functions Proxies لا تحترم خاصية routePrefix تكوين مضيف "تطبيق دالة". إذا كنت تريد تضمين بادئة مثل /api، فيجب تضمينها في خاصية المسار.

تعطيل الوكلاء الفرديين

يمكنك تعطيل وكلاء الفردية عن طريق الإضافة "disabled": true إلى الوكيل في proxies.json الملف. سيؤدي هذا إلى أي إرجاع كل طلبات matchCondition الخطأ 404.

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "Root": {
            "disabled":true,
            "matchCondition": {
                "route": "/example"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>"
        }
    }
}

إعدادات التطبيق

يمكن التحكم في سلوك الوكيل من خلال العديد من إعدادات التطبيق. يتم تحديدها جميعا في مرجع "وظائف التطبيق" الإعدادات

الأحرف المحجوزة (تنسيق السلسلة)

يقرأ الوكلاء كافة السلاسل من ملف JSON، وذلك باستخدام \ كرمز الهروب. تقوم الوكلاء أيضًا بتفسير الأقواس المجعدة. انظر مجموعة كاملة من الأمثلة أدناه.

الحرف	حرف هارب	مثال
{ أو }	{{ أو }}	`{{ example }}` -->`{ example }`
\	\\	`example.com\\text.html` -->`example.com\text.html`
"	\"	`\"example\"` -->`"example"`

تعريف كائن requestOverrides

يعرف الكائن requestOverrides التغييرات التي تم إجراؤها على الطلب عند استدعاء المورد الخلفي. يتم تعريف الكائن بواسطة الخصائص التالية:

backend.request.method: أسلوب HTTP المستخدمة في استدعاء النهاية الخلفية.
backend.request.querystring. < ParameterName > : معلمة سلسلة استعلام يمكن تعيينها للاستدعاء إلى الخلفية. استبدل < ParameterName > باسم المعلمة التي تريد ضبطها. إذا تم توفير سلسلة فارغة، المعلمة لا يزال مضمنًا في طلب النهاية الخلفية.
backend.request.headers.<HeaderName>: عنوان يمكن ضبطه للاستدعاء إلى الخلفية. استبدل <HeaderName> باسم العنوان الذي تريد ضبطه. إذا تم توفير سلسلة فارغة، المعلمة لا يزال مضمنًا في طلب النهاية الخلفية.

يمكن للقيم الرجوع إلى إعدادات التطبيق والمعلمات من طلب العميل الأصلي.

قد يبدو تكوين مثال ما كما يلي:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>",
            "requestOverrides": {
                "backend.request.headers.Accept": "application/xml",
                "backend.request.headers.x-functions-key": "%ANOTHERAPP_API_KEY%"
            }
        }
    }
}

تعريف كائن responseOverrides

يعرف الكائن requestOverrides التغييرات التي يتم إجراؤها على الاستجابة التي تم تمريرها مرة أخرى إلى العميل. يتم تعريف الكائن بواسطة الخصائص التالية:

response.statusCode: رمز حالة HTTP ليتم إرجاعها إلى العميل.
response.statusReason: عبارة سبب HTTP ليتم إرجاعها إلى العميل.
response.body: تمثيل سلسلة من النص الأساسي إلى أن تعاد إلى العميل.
response.headers. < HeaderName > : عنوان يمكن ضبطه للاستجابة إلى العميل. استبدل <HeaderName> باسم العنوان الذي تريد ضبطه. إذا قمت بتوفير السلسلة الفارغة، لا يتم تضمين الرأس في الاستجابة.

يمكن للقيم الرجوع إلى إعدادات التطبيق والمعلمات من طلب العميل الأصلي والمعلمات من الاستجابة الخلفية.

قد يبدو تكوين مثال ما كما يلي:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "responseOverrides": {
                "response.body": "Hello, {test}",
                "response.headers.Content-Type": "text/plain"
            }
        }
    }
}

إشعار

في هذا المثال، يتم تعيين نص الاستجابة مباشرة، لذلك لا backendUri توجد خاصية مطلوبة. يوضح المثال كيفية استخدام وكلاء وظائف Azure Functions Proxies لتقليد واجهات برمجة التطبيقات APIs.

مشاركة عبر

العمل مع الوكلاء القدماء

إعادة تمكين الوكلاء في Functions v4.x

إنشاء وكيل

تعديل الطلبات والاستجابات

تعديل طلب النهاية الخلفية

تعديل الاستجابة

استخدام المتغيرات

دالات محلية مرجعية

معلمات طلب المرجع

معلمات قالب المسار

معلمات طلب إضافية

معلمات الاستجابة الخلفية المرجعية

إعدادات التطبيق المرجعي

استكشاف أخطاء الوكلاء وإصلاحها

حظر آثار الوكيل

تكوين متقدم

تعطيل الوكلاء الفرديين

إعدادات التطبيق

الأحرف المحجوزة (تنسيق السلسلة)

تعريف كائن requestOverrides

تعريف كائن responseOverrides

الملاحظات

الموارد الإضافية