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

Мақала
07/25/2023

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.

Совет

Вы можете использовать Postman , чтобы опробовать вызовы REST API, описанные в этой статье. Скачайте коллекцию Postman IoT Central и импортируйте ее в Postman. В коллекции необходимо задать такие переменные, как поддомен приложения и маркер администратора.

Сведения об управлении экспортом данных с помощью пользовательского интерфейса 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 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: для назначения хранилища BLOB-объектов — имя контейнера, в который должны записываться данные.

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

{
    "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 поле для экспорта только сообщений, в которых значение телеметрии акселерометра-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 API, рекомендуем перейти к следующему шагу: Использование REST API IoT Central для управления шаблонами устройств.

Бөлісу құралы:

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

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

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

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

Перечисление назначений

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

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

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

Обогащения

Фильтры

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

Вывод списка определений экспорта

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

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

Дальнейшие действия

Кері байланыс

Кері байланыс

Қосымша ресурстар