كيفية استخدام واجهة برمجة تطبيقات REST ل IoT Central لإدارة عمليات تصدير البيانات

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

يتطلب كل استدعاء لواجهة برمجة تطبيقات REST ل IoT Central عنوان تخويل. لمعرفة المزيد، راجع كيفية مصادقة مكالمات واجهة برمجة تطبيقات REST المركزية ل IoT وتخويلها.

للحصول على الوثائق المرجعية لواجهة برمجة تطبيقات REST ل IoT Central، راجع مرجع واجهة برمجة تطبيقات REST ل Azure IoT Central.

تلميح

يمكنك استخدام Postman لتجربة استدعاءات واجهة برمجة تطبيقات REST الموضحة في هذه المقالة. قم بتنزيل مجموعة IoT Central Postman واستوردها إلى Postman. في المجموعة، ستحتاج إلى تعيين متغيرات مثل المجال الفرعي للتطبيق والرمز المميز للمسؤول.

لمعرفة كيفية إدارة تصدير البيانات باستخدام واجهة مستخدم IoT Central، راجع تصدير بيانات IoT إلى Blob Storage.

تصدير البيانات

يمكنك استخدام ميزة تصدير بيانات IoT Central لدفق بيانات تتبع الاستخدام وتغييرات الخصائص وأحداث اتصال الجهاز وأحداث دورة حياة الجهاز وأحداث دورة حياة قالب الجهاز إلى وجهات مثل Azure Event Hubs ناقل خدمة Azure وAzure Blob Storage ونقاط نهاية خطاف الويب.

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

إنشاء وجهة أو تحديثها

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

PUT https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

destinationId هو معرف فريد للوجهة.

يوضح المثال التالي نص طلب ينشئ وجهة تخزين كائن ثنائي كبير الحجم:

{
  "displayName": "Blob Storage Destination",
  "type": "blobstorage@v1",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
  "containerName": "central-data"
}

يحتوي نص الطلب على بعض الحقول المطلوبة:

• displayName: اسم العرض للوجهة.
• type: نوع الكائن الوجهة. واحد من: blobstorage@v1، dataexplorer@v1، eventhubs@v1، servicebusqueue@v1، servicebustopic@v1، . webhook@v1
• connectionString: سلسلة الاتصال للوصول إلى مورد الوجهة.
• containerName: بالنسبة لوجهة تخزين كائن ثنائي كبير الحجم، اسم الحاوية حيث يجب كتابة البيانات.

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

الحصول على وجهة حسب المعرف

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

GET https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

قائمة الوجهات

استخدم الطلب التالي لاسترداد قائمة الوجهات من التطبيق الخاص بك:

GET https://{your app subdomain}/api/dataExport/destinations?api-version=2022-10-31-preview

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
    "value": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
            "displayName": "Blob Storage Destination",
            "type": "blobstorage@v1",
            "authorization": {
                "type": "connectionString",
                "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
                "containerName": "central-data"
            },
            "status": "waiting"
        },
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9",
            "displayName": "Webhook destination",
            "type": "webhook@v1",
            "url": "https://eofnjsh68jdytan.m.pipedream.net",
            "headerCustomizations": {},
            "status": "error"
        }
    ]
}

تصحيح وجهة

PATCH https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

يمكنك استخدام هذا الاستدعاء لإجراء تحديث تزايدي لتصدير. يبدو نص طلب العينة مثل المثال التالي الذي يحدث الوجهة connectionString :

{
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net"
}

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "connectionString",
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;EndpointSuffix=core.windows.net",
      "containerName": "central-data"
    },
    "status": "waiting"
}

حذف وجهة

استخدم الطلب التالي لحذف وجهة:

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

إنشاء تعريف تصدير أو تحديثه

استخدم الطلب التالي لإنشاء تعريف تصدير بيانات أو تحديثه:

PUT https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

يوضح المثال التالي نص طلب ينشئ تعريف تصدير لبيانات تتبع استخدام الجهاز:

{
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "8dbcdb53-c6a7-498a-a976-a824b694c150"
        }
    ]
}

يحتوي نص الطلب على بعض الحقول المطلوبة:

• displayName: اسم العرض للتصدير.
• enabled: قم بالتبديل لبدء/إيقاف تصدير من إرسال البيانات.
• source: نوع البيانات المراد تصديرها.
• destinations: قائمة الوجهات التي يجب أن يرسل إليها التصدير البيانات. يجب أن تكون معرفات الوجهة موجودة بالفعل في التطبيق.

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

• enrichments: أجزاء إضافية من المعلومات لتضمينها مع كل رسالة مرسلة. يتم تمثيل البيانات كم مجموعة من أزواج المفاتيح/القيم، حيث يكون المفتاح هو اسم الإثراء الذي سيظهر في رسالة الإخراج وتحدد القيمة البيانات المراد إرسالها.
• filter: استعلام يحدد الأحداث التي يجب تصديرها من المصدر.

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "starting"
}

عمليات الإثراء

هناك ثلاثة أنواع من الإثراء التي يمكنك إضافتها إلى التصدير: السلاسل المخصصة وخصائص النظام والخصائص المخصصة:

يوضح المثال التالي كيفية استخدام العقدة enrichments لإضافة سلسلة مخصصة إلى الرسالة الصادرة:

"enrichments": {
  "My custom string": {
    "value": "My value"
  },
  //...
}

يوضح المثال التالي كيفية استخدام العقدة enrichments لإضافة خاصية نظام إلى الرسالة الصادرة:

"enrichments": {
  "Device template": {
    "path": "$templateDisplayName"
  },
  //...
}

يمكنك إضافة خصائص النظام التالية:

الخاصية	الوصف
$enabled	هل تم تمكين الجهاز؟
$displayName	اسم الجهاز.
$templateDisplayName	اسم قالب الجهاز.
$organizations	المؤسسات التي ينتمي إليها الجهاز.
$provisioned	هل تم توفير الجهاز؟
$simulated	هل تمت محاكاة الجهاز؟

يوضح المثال التالي كيفية استخدام العقدة enrichments لإضافة خاصية مخصصة إلى الرسالة الصادرة. الخصائص المخصصة هي خصائص محددة في قالب الجهاز الذي يرتبط به الجهاز:

"enrichments": {
  "Device model": {
    "target": "dtmi:azure:DeviceManagement:DeviceInformation;1",
    "path": "model"
  },
  //...
}

عوامل التصفية

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

يوضح المثال التالي كيفية استخدام filter الحقل لتصدير الرسائل فقط حيث تكون قيمة القياس عن بعد accelerometer-X أكبر من 0:

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 WHERE accelerometerX > 0",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

يوضح المثال التالي كيفية استخدام filter الحقل لتصدير الرسائل فقط حيث temperature تكون قيمة بيانات تتبع الاستخدام أكبر من الخاصية targetTemperature :

{
  "id": "export-001",
  "displayName": "Enriched Export",
  "enabled": true,
  "source": "telemetry",
  "filter": "SELECT * FROM dtmi:eclipsethreadx:devkit:gsgmxchip;1 AS A, dtmi:contoso:Thermostat;1 WHERE A.temperature > targetTemperature",
  "destinations": [
    {
      "id": "dest-001"
    }
  ],
  "status": "healthy"
}

الحصول على تصدير حسب المعرف

استخدم الطلب التالي لاسترداد تفاصيل تعريف تصدير من التطبيق الخاص بك:

GET https://{your app subdomain}/api/dataExport/exports/{exportId}?api-version=2022-10-31-preview

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage Destination",
    "type": "blobstorage@v1",
    "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=********;EndpointSuffix=core.windows.net",
    "containerName": "central-data",
    "status": "waiting"
}

سرد تعريفات التصدير

استخدم الطلب التالي لاسترداد قائمة بتعريفات التصدير من التطبيق الخاص بك:

GET https://{your app subdomain}/api/dataExport/exports?api-version=2022-10-31-preview

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
  "value": [
    {
      "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "starting"
    },
    {
      "id": "802894c4-33bc-4f1e-ad64-e886f315cece",
      "displayName": "Enriched Export",
      "enabled": true,
      "source": "telemetry",
      "enrichments": {
        "Custom data": {
          "value": "My value"
        }
      },
      "destinations": [
        {
          "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
      ],
      "status": "healthy"
    }
  ]
}

تصحيح تعريف التصدير

PATCH https://{your app subdomain}/dataExport/exports/{exportId}?api-version=2022-10-31-preview

يمكنك استخدام هذا الاستدعاء لإجراء تحديث تزايدي لتصدير. يبدو نص طلب العينة مثل المثال التالي الذي يحدث enrichments إلى تصدير:

{
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    }
}

تبدو الاستجابة لهذا الطلب مثل المثال التالي:

{
    "id": "6e93df53-1ce5-45e4-ad61-3eb0d684b3a5",
    "displayName": "Enriched Export",
    "enabled": true,
    "source": "telemetry",
    "enrichments": {
        "Custom data": {
            "value": "My value 2"
        }
    },
    "destinations": [
        {
            "id": "9742a8d9-c3ca-4d8d-8bc7-357bdc7f39d9"
        }
    ],
    "status": "healthy"
}

حذف تعريف تصدير

استخدم الطلب التالي لحذف تعريف تصدير:

DELETE https://{your app subdomain}/api/dataExport/destinations/{destinationId}?api-version=2022-10-31-preview

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

الآن بعد أن تعلمت كيفية إدارة تصدير البيانات باستخدام واجهة برمجة تطبيقات REST، فإن الخطوة التالية المقترحة هي كيفية استخدام واجهة برمجة تطبيقات REST ل IoT Central لإدارة قوالب الأجهزة.