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

아티클
10/23/2024

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 참조를 참조하세요.

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",
    "type": "blobstorage@v1",
    "authorization": {
      "type": "systemAssignedManagedIdentity",
      "endpointUri": "https://yourapplication.blob.core.windows.net/",
      "containerName": "central-data"
    }
}

요청 본문에는 다음과 같은 몇 가지 필수 필드가 있습니다.

displayName: 대상의 표시 이름입니다.
type: 대상 개체의 형식입니다. blobstorage@v1, dataexplorer@v1, eventhubs@v1, servicebusqueue@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"
}

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

다음을 통해 공유

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

데이터 내보내기

대상 만들기 또는 업데이트

ID로 대상 가져오기

대상 목록

대상 패치

대상 삭제

내보내기 정의 만들기 또는 업데이트

보강

필터

ID로 내보내기 가져오기

내보내기 정의 목록

내보내기 정의 패치

내보내기 정의 삭제

다음 단계

피드백

추가 리소스