تكوين الوحدة النمطية لوكيل واجهة برمجة التطبيقات لسيناريو التدرج الهرمي للبوابة (معاينة)

مقالة
04/27/2022
قراءة خلال 7 دقائق

ينطبق على: إنترنت الأشياء حافة 1.2

تتناول هذه المقالة خيارات التكوين لوحدة وكيل واجهة برمجة التطبيقات، بحيث يمكنك تخصيص الوحدة النمطية لدعم متطلبات التدرج الهرمي للبوابة.

تعمل وحدة وكيل API على تبسيط الاتصال بأجهزة IoT Edge عند نشر خدمات متعددة تدعم جميعها بروتوكول HTTPS وتتصل بالمنفذ 443. هذا مهم بشكل خاص في عمليات النشر الهرمية لأجهزة IoT Edge في البنى المعزولة بالشبكة المستندة إلى ISA-95 مثل تلك الموضحة في الشبكة التي تعزل الأجهزة النهائية لأن العملاء على الأجهزة الفرعية لا يمكنهم الاتصال مباشرة بالسحابة.

على سبيل المثال، للسماح لأجهزة IoT Edge التابعة بسحب صور Docker يتطلب نشر وحدة تسجيل Docker. للسماح بتحميل النقط، يتطلب نشر وحدة تخزين Azure Blob على نفس جهاز IoT Edge. تستخدم كلتا الخدمتين HTTPS للاتصال. يتيح وكيل واجهة برمجة التطبيقات عمليات النشر هذه على جهاز IoT Edge. بدلا من كل خدمة، ترتبط وحدة وكيل API بمنفذ 443 على الجهاز المضيف وتوجه الطلب إلى وحدة الخدمة الصحيحة التي تعمل على هذا الجهاز وفقا للقواعد القابلة للتكوين من قبل المستخدم. لا تزال الخدمات الفردية مسؤولة عن التعامل مع الطلبات ، بما في ذلك المصادقة على العملاء وتفويضهم.

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

نشر الوحدة النمطية للوكيل

تتوفر الوحدة النمطية لوكيل API من سجل حاويات Microsoft (MCR): mcr.microsoft.com/azureiotedge-api-proxy:1.1.

يمكنك أيضا نشر وحدة وكيل API مباشرة من Azure Marketplace: IoT Edge API Proxy (وكيل IoT Edge API Proxy Api).

فهم وحدة الوكيل

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

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

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

التكوين الافتراضي

تأتي الوحدة النمطية لوكيل API مع تكوين افتراضي يدعم السيناريوهات الشائعة ويسمح بالتخصيص. يمكنك التحكم في التكوين الافتراضي من خلال متغيرات البيئة الخاصة بالوحدة النمطية.

حاليا، تتضمن متغيرات البيئة الافتراضية ما يلي:

متغير البيئة	الوصف
`PROXY_CONFIG_ENV_VAR_LIST`	سرد كافة المتغيرات التي تنوي تحديثها في قائمة مفصولة بفواصل. تمنع هذه الخطوة تعديل إعدادات التكوين الخاطئة عن طريق الخطأ.
`NGINX_DEFAULT_PORT`	يغير المنفذ الذي يستمع إليه وكيل nginx. إذا قمت بتحديث متغير البيئة هذا، فتأكد من أن المنفذ الذي تحدده مكشوف أيضا في ملف dockerfile الخاص بالوحدة النمطية ويتم الإعلان عنه كمنفذ ملزم في بيان النشر. الافتراضي هو 443. عند النشر من Azure Marketplace، يتم تحديث المنفذ الافتراضي إلى 8000، لمنع التعارضات مع الوحدة النمطية edgeHub. لمزيد من المعلومات، راجع تصغير المنافذ المفتوحة.
`DOCKER_REQUEST_ROUTE_ADDRESS`	العنوان لتوجيه طلبات عامل الرصيف. قم بتعديل هذا المتغير على جهاز الطبقة العليا للإشارة إلى وحدة التسجيل. الافتراضي هو اسم المضيف الأصل.
`BLOB_UPLOAD_ROUTE_ADDRESS`	عنوان لتوجيه طلبات التسجيل blob. قم بتعديل هذا المتغير على جهاز الطبقة العليا للإشارة إلى وحدة تخزين blob. الافتراضي هو اسم المضيف الأصل.

تقليل المنافذ المفتوحة

لتقليل عدد المنافذ المفتوحة، يجب أن تقوم وحدة وكيل واجهة برمجة التطبيقات بترحيل كل حركة مرور HTTPS (المنفذ 443)، بما في ذلك حركة المرور التي تستهدف وحدة edgeHub. يتم تكوين الوحدة النمطية لوكيل API افتراضيا لإعادة توجيه كل حركة مرور edgeHub على المنفذ 443.

اتبع الخطوات التالية لتكوين النشر لتقليل المنافذ المفتوحة:

قم بتحديث إعدادات الوحدة النمطية edgeHub لعدم ربطها بالمنفذ 443، وإلا ستكون هناك تعارضات في ربط المنفذ. بشكل افتراضي، ترتبط الوحدة النمطية edgeHub بالمنافذ 443 و5671 و8883. احذف ربط المنفذ 443 واترك المنفذ الآخر في مكانه:
```
{
  "HostConfig": {
    "PortBindings": {
      "5671/tcp": [
        {
          "HostPort": "5671"
        }
      ],
      "8883/tcp": [
        {
          "HostPort": "8883"
        }
      ]
    }
  }
}
```
قم بتكوين الوحدة النمطية لوكيل API للربط على المنفذ 443.
1. تعيين قيمة متغير البيئة NGINX_DEFAULT_PORT إلى 443.
2. تحديث خيارات إنشاء الحاوية للربط على المنفذ 443.
```
{
  "HostConfig": {
    "PortBindings": {
      "443/tcp": [
        {
          "HostPort": "443"
        }
      ]
    }
  }
}
```

إذا لم تكن بحاجة إلى تقليل المنافذ المفتوحة ، فيمكنك السماح لوحدة edgeHub النمطية باستخدام المنفذ 443 وتكوين وحدة وكيل API للاستماع إلى منفذ آخر. على سبيل المثال، يمكن لوحدة وكيل API الاستماع إلى المنفذ 8000 عن طريق تعيين قيمة متغير بيئة NGINX_DEFAULT_PORT وإنشاء 8000 ربط منفذ للمنفذ 8000.

تمكين تنزيل صورة الحاوية

تتمثل إحدى حالات الاستخدام الشائعة لوحدة وكيل API في تمكين أجهزة IoT Edge في الطبقات السفلية من سحب صور الحاويات. يستخدم هذا السيناريو وحدة تسجيل Docker النمطية لاسترداد صور الحاوية من السحابة وتخزينها مؤقتا في الطبقة العليا. يقوم وكيل API بترحيل جميع طلبات HTTPS لتنزيل صورة حاوية من الطبقات السفلية ليتم خدمتها بواسطة وحدة التسجيل في الطبقة العليا.

يتطلب هذا السيناريو أن تشير أجهزة IoT Edge النهائية إلى اسم $upstream المجال متبوعا برقم منفذ الوحدة النمطية لوكيل API بدلا من سجل حاوية الصورة. على سبيل المثال: $upstream:8000/azureiotedge-api-proxy:1.1.

يتم توضيح حالة الاستخدام هذه في البرنامج التعليمي إنشاء تسلسل هرمي لأجهزة IoT Edge باستخدام البوابات.

قم بتكوين الوحدات التالية في الطبقة العليا:

وحدة تسجيل Docker
- قم بتكوين الوحدة النمطية باسم لا ينسى مثل التسجيل وعرض منفذ في الوحدة النمطية لتلقي الطلبات.
- قم بتكوين الوحدة النمطية للتعيين إلى سجل الحاوية الخاص بك.

وحدة وكيل API

تكوين متغيرات البيئة التالية:

الاسم	القيمة
`DOCKER_REQUEST_ROUTE_ADDRESS`	اسم الوحدة النمطية للتسجيل والمنفذ المفتوح. على سبيل المثال، ⁧`registry:5000`⁩.
`NGINX_DEFAULT_PORT`	المنفذ الذي يستمع إليه وكيل nginx للطلبات الواردة من الأجهزة النهائية. على سبيل المثال، ⁧`8000`⁩.

تكوين خيارات الإنشاء التالية:

{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

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

وحدة وكيل API

تكوين متغيرات البيئة التالية:

الاسم	القيمة
`NGINX_DEFAULT_PORT`	المنفذ الذي يستمع إليه وكيل nginx للطلبات الواردة من الأجهزة النهائية. على سبيل المثال، ⁧`8000`⁩.

تكوين خيارات الإنشاء التالية:

{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

تمكين تحميل blob

حالة استخدام أخرى لوحدة وكيل API هي تمكين أجهزة IoT Edge في الطبقات السفلى من تحميل النقط. تتيح حالة الاستخدام هذه وظيفة استكشاف الأخطاء وإصلاحها على أجهزة الطبقة السفلى مثل تحميل سجلات الوحدات النمطية أو تحميل حزمة الدعم.

يستخدم هذا السيناريو وحدة تخزين Azure Blob على IoT Edge في الطبقة العليا للتعامل مع إنشاء الفقاعة وتحميلها.

قم بتكوين الوحدات التالية في الطبقة العليا:

A Azure Blob Storage on IoT Edge module.

وحدة وكيل API

تكوين متغيرات البيئة التالية:

الاسم	القيمة
`BLOB_UPLOAD_ROUTE_ADDRESS`	اسم وحدة تخزين blob والمنفذ المفتوح. على سبيل المثال، ⁧`azureblobstorageoniotedge:1102`⁩.
`NGINX_DEFAULT_PORT`	المنفذ الذي يستمع إليه وكيل nginx للطلبات الواردة من الأجهزة النهائية. على سبيل المثال، ⁧`8000`⁩.

تكوين خيارات الإنشاء التالية:

{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

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

وحدة وكيل API

تكوين متغيرات البيئة التالية:

الاسم	القيمة
`NGINX_DEFAULT_PORT`	المنفذ الذي يستمع إليه وكيل nginx للطلبات الواردة من الأجهزة النهائية. على سبيل المثال، ⁧`8000`⁩.

تكوين خيارات الإنشاء التالية:

{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

اتبع الخطوات التالية لتحميل حزمة الدعم أو ملف السجل إلى وحدة تخزين blob الموجودة في الطبقة العليا:

قم بإنشاء حاوية blob ، باستخدام Azure Storage Explorer أو واجهات برمجة تطبيقات REST. لمزيد من المعلومات، راجع تخزين البيانات على الحافة باستخدام Azure Blob Storage على IoT Edge.
اطلب تحميل سجل أو حزمة دعم وفقا للخطوات الواردة في استرداد السجلات من عمليات نشر IoT Edge، ولكن استخدم اسم $upstream المجال ومنفذ الوكيل المفتوح بدلا من عنوان وحدة تخزين blob. على سبيل المثال:
```
{
   "schemaVersion": "1.0",
   "sasUrl": "https://$upstream:8000/myBlobStorageName/myContainerName?SAS_key",
   "since": "2d",
   "until": "1d",
   "edgeRuntimeOnly": false
}
```

تحرير تكوين الوكيل

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

عند كتابة التكوين الخاص بك، لا يزال بإمكانك استخدام البيئة لضبط الإعدادات لكل عملية نشر. استخدم الصيغة التالية:

استخدم ${MY_ENVIRONMENT_VARIABLE} لاسترداد قيمة متغير بيئة.

استخدم العبارات الشرطية لتشغيل الإعدادات أو إيقاف تشغيلها استنادا إلى قيمة متغير البيئة:

#if_tag ${MY_ENVIRONMENT_VARIABLE}
     statement to execute if environment variable evaluates to 1
#endif_tag ${MY_ENVIRONMENT_VARIABLE}

#if_tag !${MY_ENVIRONMENT_VARIABLE}
     statement to execute if environment variable evaluates to 0
#endif_tag !${MY_ENVIRONMENT_VARIABLE}

عندما تقوم الوحدة النمطية لوكيل API بتحليل تكوين وكيل، فإنها تحل أولا محل جميع متغيرات البيئة المدرجة في PROXY_CONFIG_ENV_VAR_LIST القائمة بقيمها المقدمة باستخدام الاستبدال. بعد ذلك ، يتم استبدال كل شيء بين #if_tag الزوج والزوج #endif_tag . ثم توفر الوحدة النمطية التكوين المحلل للوكيل العكسي nginx.

لتحديث تكوين الوكيل ديناميكيا، اتبع الخطوات التالية:

اكتب ملف التكوين. يمكنك استخدام هذا القالب الافتراضي كمرجع: nginx_default_config.conf
انسخ نص ملف التكوين وقم بتحويله إلى base64.
الصق ملف التكوين المشفر كقيمة proxy_config الخاصية المطلوبة في توأم الوحدة النمطية.

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

استخدم وحدة وكيل API الاتصال جهاز IoT Edge في المراحل النهائية إلى بوابة Azure IoT Edge.

تكوين الوحدة النمطية لوكيل واجهة برمجة التطبيقات لسيناريو التدرج الهرمي للبوابة (معاينة)

هل هذه الصفحة مفيدة؟

نشر الوحدة النمطية للوكيل

فهم وحدة الوكيل

التكوين الافتراضي

تقليل المنافذ المفتوحة

تمكين تنزيل صورة الحاوية

تمكين تحميل blob

تحرير تكوين الوكيل

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