Share via

تدفق تكامل شريك الاستشعار

  • مقالة

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

إعداد

يغطي الإعداد الخطوات المطلوبة من قبل كل من العملاء والشركاء للتكامل مع مدير البيانات للزراعة والبدء في تلقي/ إرسال بيانات تتبع الاستخدام للمستشعر على التوالي.

Screenshot showing sensor partners flow.

من الشكل أعلاه، الكتل المميزة باللون الأبيض هي الخطوات التي اتخذها الشريك، وتلك المميزة باللون الأسود يتم إجراؤها من قبل العملاء.

تدفق الشريك: المرحلة 1

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

إنشاء تطبيق

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

ومن ثم لتمكين المصادقة والتخويل، يحتاج الشركاء إلى القيام بما يلي

  1. إنشاء حساب Azure (إذا لم يكن لديك حساب تم إنشاؤه بالفعل.)
  2. إنشاء تطبيق Microsoft Entra متعدد المستأجرين - يتمتع تطبيق Microsoft Entra متعدد المستأجرين كاسم يشير إلى أنه لديه حق الوصول إلى مستأجري عملاء متعددين، إذا كان العملاء قد منحوا موافقة صريحة لتطبيق الشريك (موضح في خطوة تعيين الدور).

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

اتبع الخطوات المتوفرة في تسجيلالتطبيق حتى الخطوة 8 لإنشاء المعلومات التالية:

  1. معرف التطبيق (العميل)
  2. معرف الدليل (المستأجر)
  3. اسم التطبيق

انسخ جميع القيم الثلاث واخزنها كما ستحتاج إليها لإنشاء رمز مميز للوصول.

معرف التطبيق (العميل) الذي تم إنشاؤه يشبه معرف المستخدم للتطبيق، والآن تحتاج إلى إنشاء كلمة مرور التطبيق المقابلة (سر العميل) للتطبيق لتعريف نفسه.

اتبع الخطوات الواردة في إضافة سر عميل لإنشاء سر العميل ونسخ سر العميل الذي تم إنشاؤه.

التسجيل

بمجرد أن يقوم الشريك بإنشاء تطبيق Microsoft Entra متعدد المستأجرين بنجاح، يشارك الشركاء يدويا معرف التطبيق ومعرف الشريك مع مدير البيانات للزراعة عن طريق إرسال اسم مستعار عبر madma@microsoft.com البريد الإلكتروني. باستخدام هذه المعلومات يتحقق مدير البيانات للزراعة مما إذا كان شريكا أصليا وإنشاء هوية شريك (sensorPartnerId) باستخدام واجهات برمجة التطبيقات الداخلية. كجزء من عملية التسجيل، يتم تمكين الشركاء من استخدام معرف شريكهم (sensorPartnerId) أثناء إنشاء عنصر الاستشعار/الأجهزة وأيضا كجزء من بيانات المستشعر التي يدفعونها.

يمثل الحصول على معرف الشريك اكتمال تكامل Partner-Data Manager for Agriculture. الآن، ينتظر الشريك المدخلات من أي من عملاء أجهزة الاستشعار الخاصة بهم لبدء استيعاب البيانات الخاصة بهم في Data Manager for Agriculture.

تدفق العملاء

سيكون العملاء الذين يستخدمون Data Manager للزراعة على دراية بجميع شركاء الاستشعار المدعومين ومعرفات التطبيقات الخاصة بهم. تتوفر هذه المعلومات في الوثائق العامة لجميع عملائنا. استنادا إلى أدوات الاستشعار التي يستخدمها العملاء ومعرف التطبيق الخاص بشريك الاستشعار الخاص بهم، يجب على العميل توفير الوصول إلى الشريك (APP ID) لبدء دفع بيانات المستشعر الخاصة بهم إلى مدير البيانات الخاص بهم لمثيل الزراعة. فيما يلي الخطوات المطلوبة:

تعيين الدور

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

  1. الموافقة - نظرا لأن تطبيق الشريك موجود في مستأجر مختلف ويريد العميل من الشريك الوصول إلى واجهات برمجة تطبيقات معينة في مثيل Data Manager للزراعة، يطلب من العملاء استدعاء نقطة https://login.microsoft.com/common/adminconsent/clientId=[client_id] نهاية محددة واستبدال [client_id] بمعرف تطبيق الشركاء. وهذا يمكن معرف Microsoft Entra الخاص بالعملاء من التعرف على معرف التطبيق هذا كلما استخدموه لتعيين الدور.

  2. إدارة الوصول إلى الهوية (IAM) – كجزء من إدارة الوصول إلى الهوية، يقوم العملاء بإنشاء تعيين دور جديد لمعرف التطبيق أعلاه، والذي تم تقديم الموافقة عليه. يقوم مدير البيانات للزراعة بإنشاء دور جديد يسمى Sensor Partner (بالإضافة إلى أدوار مسؤول والمساهم والقارئ الحالية). يختار العملاء دور شريك المستشعر ويضيفون معرف تطبيق الشريك ويوفرون الوصول.

البدء

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

  1. رابط الموافقة ومعرف المستأجر - في هذه الخطوة، يوفر العميل رابط الموافقة ومعرف المستأجر. يبدو ارتباط التكامل كما هو موضح في المثال:

    fb-resource-name.farmbeats.com/sensor-partners/partnerId/integrations/IntegrationId/:check-consent?key=jgtHTFGDR?api-version=2021-07-31-preview

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

    يتحقق الشركاء من صحة ارتباط الموافقة عن طريق إجراء مكالمة GET على واجهة برمجة تطبيقات رابط التحقق من الموافقة. نظرا لأن الارتباط عبارة عن عنوان URI للطلب مسبق الملء بالكامل كما هو متوقع من قبل مدير البيانات للزراعة. كجزء من استدعاء GET، يتحقق الشركاء من رمز استجابة 200 OK و IntegrationId لتمريره في الاستجابة.

    بمجرد تلقي الاستجابة الصالحة، يتعين على الشركاء تخزين مجموعتين من المعلومات

    • نقطة نهاية واجهة برمجة التطبيقات (يمكن استخراجها من الجزء الأول من ارتباط التكامل)
    • IntegrationId (يتم إرجاعه كجزء من الاستجابة لاستدعاء GET)

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

  2. إضافة أجهزة استشعار/أجهزة - الآن، يعرف الشريك العميل (نقطة نهاية API) الذي يحتاج إلى التكامل معه، ومع ذلك، لا يزال لا يعرف أي أجهزة استشعار يحتاجها لدفع البيانات. ومن ثم، يجمع الشركاء معلومات المستشعر/الجهاز التي تحتاج البيانات إلى دفعها. يمكن جمع هذه البيانات إما يدويا أو من خلال واجهة مستخدم المدخل.

    بعد إضافة أجهزة الاستشعار/الأجهزة، يمكن للعميل توقع تدفق بيانات أجهزة الاستشعار المعنية إلى مثيل Data Manager for Agriculture. تشير هذه الخطوة إلى اكتمال إلحاق العملاء بإحضار بيانات المستشعر.

تدفق الشريك: المرحلة 2

لدى الشريك الآن المعلومات لاستدعاء نقطة نهاية API محددة (مستوى بيانات العملاء)، ولكن لا يزال ليس لديهم معلومات حول أين يحتاجون إلى دفع بيانات تتبع استخدام أداة الاستشعار؟

التكامل

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

curl --location --request GET 'https://login.microsoftonline.com/<customer’s tenant ID> /oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_secret=<Your app secret>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<Your app ID>' \
--data-urlencode 'scope=https://farmbeats.azure.net/.default'

يجب أن تبدو الاستجابة كما يلي:

{
  "token_type": "Bearer",
  "expires_in": "3599",
  "ext_expires_in": "3599",
  "expires_on": "1622530779",
  "not_before": "1622526879",
  "resource": "https://farmbeats.azure.net",
  "access_token": "eyJ0eXAiOiJKV1QiLC......tpZCI6InZhcF9"
}

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

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

دفع البيانات

إنشاء تكامل شريك المستشعر

إنشاء تكامل شريك مستشعر لتوصيل طرف معين بموفر معين. يتم استخدام integrationId لاحقا في إنشاء أداة الاستشعار. وثائق واجهة برمجة التطبيقات: عمليات تكامل شركاء الاستشعار - إنشاء أو تحديث

إنشاء نموذج بيانات المستشعر

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

وثائق واجهة برمجة التطبيقات: نماذج بيانات الاستشعار - إنشاء أو تحديث

القياس عن بعد للعينة

{
	"pressure": 30.45,
	"temperature": 28,
	"name": "sensor-1"
}

نموذج بيانات المستشعر المقابل

{
  "type": "Sensor",
  "manufacturer": "Some sensor manufacturer",
  "productCode": "soil m",
  "measures": {
    "pressure": {
      "description": "measures soil moisture",
      "dataType": "Double",
      "type": "sm",
      "unit": "Bar",
      "properties": {
        "abc": "def",
        "elevation": 5
      }
    },
	"temperature": {
      "description": "measures soil temperature",
      "dataType": "Long",
      "type": "sm",
      "unit": "Celsius",
      "properties": {
        "abc": "def",
        "elevation": 5
      }
    },
	"name": {
      "description": "Sensor name",
      "dataType": "String",
      "type": "sm",
      "unit": "none",
      "properties": {
        "abc": "def",
        "elevation": 5
      }
    }
  },
  "sensorPartnerId": "sensor-partner-1",
  "id": "sdm124",
  "status": "new",
  "createdDateTime": "2022-01-24T06:12:15Z",
  "modifiedDateTime": "2022-01-24T06:12:15Z",
  "eTag": "040158a0-0000-0700-0000-61ee433f0000",
  "name": "my sdm for soil moisture",
  "description": "description goes here",
  "properties": {
    "key1": "value1",
    "key2": 123.45
  }
}

إنشاء أداة استشعار

إنشاء أداة استشعار باستخدام معرف التكامل المقابل ومعرف نموذج بيانات المستشعر. DeviceId و HardwareId هما معلمتان اختياريتان، إذا لزم الأمر، يمكنك استخدام الأجهزة - إنشاء أو تحديث لإنشاء الجهاز.

وثائق واجهة برمجة التطبيقات: أدوات الاستشعار - إنشاء أو تحديث

الحصول على سلسلة الاتصال IoTHub

احصل على سلسلة الاتصال IoTHub لدفع القياس عن بعد لجهاز الاستشعار إلى النظام الأساسي لأداة الاستشعار التي تم إنشاؤها.

وثائق واجهة برمجة التطبيقات: أدوات الاستشعار - الحصول على سلسلة الاتصال

دفع البيانات باستخدام IoT Hub

استخدم IoT Hub Device SDKs لدفع بيانات تتبع الاستخدام باستخدام سلسلة الاتصال.

بالنسبة لجميع أحداث بيانات تتبع استخدام أداة الاستشعار، يعد "الطابع الزمني" خاصية إلزامية ويجب أن يكون بتنسيق ISO 8601 (YYYY-MM-DDTHH:MM:SSZ).

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

{
	"timestamp": "2022-02-11T03:15:00Z",
	"bar": 30.181,
	"bar_absolute": 29.748,
	"bar_trend": 0,
	"et_day": 0.081,
	"humidity": 55,
	"rain_15_min": 0,
	"rain_60_min": 0,
	"rain_24_hr": 0,
	"rain_day": 0,
	"rain_rate": 0,
	"rain_storm": 0,
	"solar_rad": 0,
	"temp_out": 58.8,
	"uv_index": 0,
	"wind_dir": 131,
	"wind_dir_of_gust_10_min": 134,
	"wind_gust_10_min": 0,
	"wind_speed": 0,
	"wind_speed_2_min": 0,
	"wind_speed_10_min": 0
}

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

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