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

ينطبق على: IoT Edge 1.5 IoT Edge 1.4

هام

IoT Edge 1.5 LTS وIoT Edge 1.4 LTS هي إصدارات مدعومة. IoT Edge 1.4 LTS هو نهاية العمر الافتراضي في 12 نوفمبر 2024. إذا كنت تستخدم إصدارا سابقا، فشاهد تحديث IoT Edge.

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

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

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

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

إشعار

يصدر جهاز انتقال البيانات من الخادم البيانات مباشرة إلى الإنترنت أو إلى أجهزة البوابة (تمكين IoT Edge أو عدم تمكينه). يمكن أن يكون الجهاز التابع جهاز انتقال البيانات من الخادم أو جهاز بوابة في طوبولوجيا متداخلة.

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

تتوفر وحدة وكيل واجهة برمجة التطبيقات من سجل حاويات Microsoft (MCR) وURI للصورة هو mcr.microsoft.com/azureiotedge-api-proxy:latest. يمكنك نشر الوحدة النمطية باستخدام مدخل Azure أو Azure CLI.

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

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

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

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

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

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

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

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

تصغير المنافذ المفتوحة

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

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

1. قم بتحديث إعدادات الوحدة النمطية edgeHub لعدم الربط على المنفذ 443، وإلا ستكون هناك تعارضات في ربط المنفذ. بشكل افتراضي، تربط وحدة edgeHub على المنافذ 443 و5671 و8883. احذف ربط المنفذ 443 واترك الاثنين الآخرين في مكانهما:

   {
     "HostConfig": {
       "PortBindings": {
         "5671/tcp": [
           {
             "HostPort": "5671"
           }
         ],
         "8883/tcp": [
           {
             "HostPort": "8883"
           }
         ]
       }
     }
   }
   

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

   1. تعيين قيمة متغير البيئة NGINX_DEFAULT_PORT إلى 443.

   2. تحديث خيارات إنشاء الحاوية للربط على المنفذ 443.

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

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

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

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

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

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

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

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

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

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

  • تكوين createOptions التالية:

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

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

• وحدة وكيل واجهة برمجة التطبيقات. الوحدة النمطية لوكيل واجهة برمجة التطبيقات مطلوبة على جميع أجهزة الطبقة السفلية باستثناء جهاز الطبقة السفلية.

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

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

  • تكوين createOptions التالية:

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

كشف منفذ الوكيل

يتم عرض المنفذ 8000 بشكل افتراضي من صورة docker. إذا تم استخدام منفذ وكيل nginx مختلف، أضف قسم ExposedPorts الذي يعلن المنفذ في بيان النشر. على سبيل المثال، إذا قمت بتغيير منفذ وكيل nginx إلى 8001، أضف ما يلي إلى بيان النشر:

{
   "ExposedPorts": {
      "8001/tcp": {}
   },
   "HostConfig": {
      "PortBindings": {
            "8001/tcp": [
               {
                  "HostPort": "8001"
               }
            ]
      }
   }
}

تمكين تحميل الكائن الثنائي كبير الحجم

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

يستخدم هذا السيناريو وحدة Azure Blob Storage على IoT Edge في الطبقة العليا للتعامل مع إنشاء الكائن الثنائي كبير الحجم وتحميله. في سيناريو متداخل، يتم دعم ما يصل إلى خمس طبقات. وحدة Azure Blob Storage على IoT Edge مطلوبة على جهاز الطبقة العليا واختيارية لأجهزة الطبقة السفلية. للحصول على عينة توزيع متعدد الطبقات، راجع نموذج Azure IoT Edge for Industrial IoT .

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

• وحدة تخزين Azure Blob على IoT Edge.
• وحدة وكيل واجهة برمجة التطبيقات

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

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

  • تكوين createOptions التالية:

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

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

• وحدة وكيل واجهة برمجة التطبيقات

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

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

  • تكوين createOptions التالية:

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

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

1. إنشاء حاوية كائن ثنائي كبير الحجم، باستخدام مستكشف تخزين Azure أو واجهات برمجة تطبيقات REST. لمزيد من المعلومات، راجع تخزين البيانات على الحافة باستخدام Azure Blob Storage على IoT Edge.

2. طلب تحميل مجموعة سجلات أو دعم وفقا للخطوات الواردة في استرداد السجلات من عمليات نشر IoT Edge، ولكن استخدم اسم $upstream المجال ومنفذ الوكيل المفتوح بدلا من عنوان وحدة تخزين الكائن الثنائي كبير الحجم. على سبيل المثال:

   {
      "schemaVersion": "1.0",
      "sasUrl": "https://$upstream:8000/myBlobStorageName/myContainerName?SAS_key",
      "since": "2d",
      "until": "1d",
      "edgeRuntimeOnly": false
   }
   

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

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

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

• استخدم ${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}
  

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

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

1. اكتب ملف التكوين الخاص بك. يمكنك استخدام هذا القالب الافتراضي كمرجع: nginx_default_config.conf

2. انسخ نص ملف التكوين وقم بتحويله إلى base64.

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

   

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

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