Share via

IoT Central REST API를 사용하여 데이터 내보내기를 관리하는 방법

  • 아티클

IoT Central REST API를 사용하면 IoT Central 애플리케이션과 통합되는 클라이언트 애플리케이션을 개발할 수 있습니다. REST API를 사용하여 IoT Central 애플리케이션에서 데이터 내보내기를 만들고 관리할 수 있습니다.

모든 IoT Central REST API 호출에는 권한 부여 헤더가 필요합니다. 자세히 알아보려면 IoT Central REST API 호출을 인증하고 권한을 부여하는 방법을 참조하세요.

IoT Central REST API에 대한 참조 설명서는 Azure IoT Central REST API 참조를 참조하세요.

팁

Postman을 사용하여 이 문서에 설명된 REST API 호출을 사용해 볼 수 있습니다. IoT Central Postman 컬렉션을 다운로드하고 Postman으로 가져옵니다. 컬렉션에서 앱 하위 도메인 및 관리자 토큰과 같은 변수를 설정해야 합니다.

IoT Central UI를 사용하여 데이터 내보내기를 관리하는 방법을 알아보려면 Blob Storage로 IoT 데이터 내보내기를 참조하세요.

데이터 내보내기

IoT Central 데이터 내보내기 기능을 사용하여 원격 분석, 속성 변경, 디바이스 연결 이벤트, 디바이스 수명 주기 이벤트 및 디바이스 템플릿 수명 주기 이벤트를 Azure Event Hubs, Azure Service Bus, Azure Blob Storage 및 웹후크 엔드포인트와 같은 대상으로 스트리밍할 수 있습니다.

각 데이터 내보내기 정의는 데이터를 하나 이상의 대상으로 보낼 수 있습니다. 내보내기 정의를 만들기 전에 대상 정의를 만듭니다.

대상 만들기 또는 업데이트

다음 요청을 사용하여 대상 정의를 만들거나 업데이트합니다.

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

destinationId는 대상의 고유 ID입니다.

다음 예제에서는 Blob Storage 대상을 만드는 요청 본문을 보여 줍니다.

{
  "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 Storage 대상의 경우 데이터를 작성해야 하는 컨테이너의 이름입니다.

이 요청에 대한 응답은 다음 예제와 같습니다.

{
    "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"
}

ID로 대상 가져오기

다음 요청을 사용하여 애플리케이션에서 대상의 세부 정보를 검색합니다.

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: 내보내기에서 데이터를 보내야 하는 대상 목록입니다. 대상 ID는 애플리케이션에 이미 있어야 합니다.

내보내기에 자세한 내용을 추가하는 데 사용할 수 있는 몇 가지 선택적 필드가 있습니다.

  • 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"
}

ID로 내보내기 가져오기

애플리케이션에서 내보내기 정의의 세부 정보를 검색하려면 다음 요청을 사용합니다.

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로 데이터 내보내기를 관리하는 방법을 배웠으므로 다음 단계는 IoT Central REST API를 사용하여 디바이스 템플릿을 관리하는 방법입니다.