Как использовать REST API в IoT Central для управления экспортом данных

Статья
10/22/2024

REST API IoT Central позволяет разрабатывать клиентские приложения, которые интегрируются с приложениями IoT Central. Rest API можно использовать для создания экспортов данных и управления ими в приложении IoT Central.

Каждому вызову REST API IoT Central требуется заголовок авторизации. Дополнительные сведения см. в разделе Аутентификация и авторизация вызовов REST API IoT Central.

Справочную документацию по REST API IoT Central см. в справочнике по REST API Azure IoT Central.

Сведения об управлении экспортом данных с помощью пользовательского интерфейса IoT Central см. в статье "Экспорт данных Интернета вещей в хранилище BLOB-объектов".

Экспорт данных

Функцию экспорта данных IoT Central можно использовать для потоковой передачи данных телеметрии, изменений свойств, событий подключения устройств, событий жизненного цикла устройства и событий жизненного цикла шаблона устройства в назначениях, таких как Центры событий Azure, Служебная шина Azure, Хранилище BLOB-объектов Azure и конечные точки веб-перехватчика.

Каждое определение экспорта данных может отправлять данные в одно или несколько назначений. Создайте определения назначения перед созданием определения экспорта.

Создание или обновление назначения

Используйте следующий запрос, чтобы создать или обновить определение назначения:

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

destinationId — уникальный идентификатор назначения.

В следующем примере показан текст запроса, создающий назначение хранилища BLOB-объектов:

{
  "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data"
    }
}

Текст запроса содержит некоторые обязательные поля:

displayName: отображаемое имя назначения.
type: тип целевого объекта. Одно из следующих: blobstorage@v1, dataexplorer@v1, servicebusqueue@v1eventhubs@v1, servicebustopic@v1, webhook@v1.
authorization: сведения о авторизации для назначения. Поддерживаемые типы авторизации и systemAssignedManagedIdentity connectionString.

Ответ на этот запрос выглядит так, как показано в следующем примере.

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.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": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.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": "systemAssignedManagedIdentity",
              "endpointUri": "https://yourapplication.blob.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

Этот вызов можно использовать для выполнения добавочного обновления для экспорта. Текст запроса образца выглядит следующим образом, который обновляет containerName целевой объект:

{
  "containerName": "central-data-analysis"
}

Ответ на этот запрос выглядит так, как показано в следующем примере.

{
    "id": "8dbcdb53-c6a7-498a-a976-a824b694c150",
    "displayName": "Blob Storage",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data-analysis"
    },
    "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"
  },
  //...
}

Можно добавить следующие системные свойства:

Свойство	Description
`$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": "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"
}

Перечисление определений экспорта

Используйте следующий запрос, чтобы получить список определений экспорта из приложения:

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 API, предлагаемым шагом является использование REST API IoT Central для управления шаблонами устройств.

Поделиться через

Как использовать REST API в IoT Central для управления экспортом данных

Экспорт данных

Создание или обновление назначения

Получение назначения по идентификатору

Вывод списка назначений

Исправление назначения

Удаление назначения

Создание или обновление определения экспорта

Обогащения

Фильтры

Получение экспорта по идентификатору

Перечисление определений экспорта

Исправление определения экспорта

Удаление определения экспорта

Следующие шаги

Обратная связь

Дополнительные ресурсы