Azure IoT 데이터 프로세서 미리 보기 파이프라인의 직렬화 및 역직렬화 형식

아티클
02/23/2024

Important

Azure IoT 작업 미리 보기 - Azure Arc에서 지원되는 Azure IoT 작업은 현재 미리 보기로 제공됩니다. 프로덕션 환경에서는 이 미리 보기 소프트웨어를 사용하면 안 됩니다.

베타, 미리 보기로 제공되거나 아직 일반 공급으로 릴리스되지 않은 Azure 기능에 적용되는 약관은 Microsoft Azure 미리 보기에 대한 추가 사용 약관을 참조하세요.

데이터 프로세서는 데이터에 구애받지 않는 플랫폼입니다. 데이터 프로세서는 모든 형식으로 데이터를 수집하고, 처리하고, 쓸 수 있습니다.

그러나 일부 파이프라인 단계에서 jq 경로 식을 사용하려면 데이터가 파이프라인 내에서 구조화된 형식이어야 합니다. 데이터를 적절한 구조화된 형식으로 가져오기 위해 역직렬화해야 할 수 있습니다.

일부 파이프라인 대상 또는 단계의 호출은 데이터가 특정 형식이어야 할 수 있습니다. 대상에 적합한 형식으로 데이터를 직렬화해야 할 수 있습니다.

메시지 역직렬화

데이터 프로세서는 기본적으로 파이프라인이 외부 데이터를 읽는 호출 단계와 데이터 원본 단계 모두에서 다양한 형식의 역직렬화를 지원합니다.

원본 단계에서 들어오는 데이터를 역직렬화할 수 있습니다.
호출 단계는 API 응답을 역직렬화할 수 있습니다.

다음과 같은 경우 들어오는 데이터를 역직렬화할 필요가 없습니다.

역직렬화된 데이터가 필요한 단계는 사용하지 않습니다.
메타데이터만 처리하고 있습니다.
들어오는 데이터는 이미 사용 중인 단계와 일치하는 형식입니다.

다음 표에는 역직렬화가 지원되는 형식과 해당 단계가 나와 있습니다.

형식	데이터 원본	호출하기
원시	지원됨	HTTP
JSON	지원됨	HTTP
Protobuf	지원됨	모두(HTTP 및 gRPC)
CSV	지원됨	HTTP
MessagePack	지원됨	HTTP
CBOR	지원됨	HTTP

팁

역직렬화가 필요하지 않은 경우 Raw를 선택합니다. 이 Raw 옵션은 현재 형식으로 데이터를 전달합니다.

메시지 직렬화

데이터 프로세서는 기본적으로 파이프라인이 외부 데이터를 쓰는 대상 및 호출 단계에서 다양한 형식으로 직렬화를 지원합니다.

대상 단계에서는 나가는 데이터를 적절한 형식으로 직렬화할 수 있습니다.
호출 단계는 API 요청에서 전송된 데이터를 직렬화할 수 있습니다.

형식	호출하기	출력 단계
`Raw`	HTTP	Microsoft Fabric을 제외한 모든 항목
`JSON`	HTTP	Microsoft Fabric을 제외한 모든 항목
`Parquet`	지원되지 않음	Microsoft Fabric
`Protobuf`	모두	Microsoft Fabric을 제외한 모든 항목
`CSV`	HTTP	Microsoft Fabric을 제외한 모든 항목
`MessagePack`	HTTP	Microsoft Fabric을 제외한 모든 항목
`CBOR`	HTTP	Microsoft Fabric을 제외한 모든 항목

팁

직렬화가 필요하지 않은 경우 Raw를 선택합니다. 이 Raw 옵션은 현재 형식으로 데이터를 전달합니다.

원시/JSON/MessagePack/CBOR 데이터 형식

원시는 데이터를 역직렬화하거나 직렬화할 필요가 없는 경우에 사용할 수 있는 옵션입니다. 원시는 역직렬화 또는 직렬화가 적용되지 않는 대부분의 단계에서 기본값입니다.

직렬화 또는 역직렬화 구성은 Raw, JSON, MessagePack, CBOR형식에 공통적으로 적용됩니다. 이러한 형식의 경우 다음 구성 옵션을 사용합니다.

다음 구성 옵션을 사용하여 데이터를 역직렬화합니다.

필드	형식	설명	필수 여부	기본값	예시
`type`	`string enum`	역직렬화를 위한 형식	아니요	-	`JSON`
`path`	Path	역직렬화된 데이터가 기록되는 데이터 프로세서 메시지 부분의 경로입니다.	(다음 참고 사항 참조)	`.payload`	`.payload.response`

참고 항목

원본 단계에서 데이터를 역직렬화할 때는 path를 지정할 필요가 없습니다. 역직렬화된 데이터는 메시지 .payload 섹션에 자동으로 배치됩니다.

다음 구성 옵션을 사용하여 데이터를 직렬화합니다.

필드	형식	설명	필수 여부	기본값	예시
`type`	`string enum`	직렬화의 형식입니다.	예	-	`JSON`
`path`	Path	직렬화해야 하는 데이터 프로세서 메시지 부분의 경로입니다.	(다음 참고 사항 참조)	`.payload`	`.payload.response`

참고 항목

일괄 처리된 데이터를 직렬화할 때는 path를 지정할 필요가 없습니다. 기본 경로는 전체 메시지를 나타내는 .입니다. 일치하지 않는 데이터의 경우 path를 지정해야 합니다.

다음 예제에서는 일괄 처리되지 않은 JSON 데이터를 직렬화하거나 역직렬화하기 위한 구성을 보여줍니다.

{
    "format": {
        "type": "json",
        "path": ".payload"
    }
}

다음 예제에서는 원본 단계에서 JSON 데이터를 역직렬화하거나 일괄 처리된 JSON 데이터를 직렬화하기 위한 구성을 보여줍니다.

{
    "format": {
        "type": "json"
    }
}

프로토콜 버퍼 데이터 형식

다음 구성 옵션을 사용하여 프로토콜 버퍼(protobuf) 데이터를 역직렬화합니다.

필드	형식	설명	필수 여부	기본값	예시
`type`	`string enum`	역직렬화를 위한 형식	예	-	`protobuf`
`descriptor`	`string`	protobuf 정의 파일에 대한 base64로 인코딩된 설명자입니다.	예	-	`Zm9v..`
`package`	`string`	형식이 정의된 설명자에 있는 패키지의 이름입니다.	예	-	`package1..`
`message`	`string`	데이터 형식을 지정하는 데 사용되는 메시지 형식의 이름입니다.	예	-	`message1..`
`path`	Path	역직렬화된 데이터를 작성해야 하는 데이터 프로세서 메시지 부분의 경로입니다.	(다음 참고 사항 참조)	`.payload`	`.payload.gRPCResponse`

참고 항목

원본 단계에서 데이터를 역직렬화할 때는 path를 지정할 필요가 없습니다. 역직렬화된 데이터는 메시지 .payload 섹션에 자동으로 배치됩니다.

다음 구성 옵션을 사용하여 protobuf 데이터를 직렬화합니다.

필드	형식	설명	필수 여부	기본값	예시
`type`	`string enum`	직렬화의 형식입니다.	예	-	`protobuf`
`descriptor`	`string`	protobuf 정의 파일에 대한 base64로 인코딩된 설명자입니다.	예	-	`Zm9v..`
`package`	`string`	형식이 정의된 설명자에 있는 패키지의 이름입니다.	예	-	`package1..`
`message`	`string`	데이터 형식을 지정하는 데 사용되는 메시지 형식의 이름입니다.	예	-	`message1..`
`path`	Path	직렬화할 데이터가 읽혀지는 데이터 프로세서 메시지 부분의 경로입니다.	(다음 참고 사항 참조)	-	`.payload.gRPCRequest`

참고 항목

일괄 처리된 데이터를 직렬화할 때는 path를 지정할 필요가 없습니다. 기본 경로는 전체 메시지를 나타내는 .입니다.

다음 예제에서는 일괄 처리되지 않은 protobuf 데이터를 직렬화하거나 역직렬화하기 위한 구성을 보여줍니다.

{
    "format": {
        "type": "protobuf",
        "descriptor": "Zm9v..",
        "package": "package1",
        "message": "message1",
        "path": ".payload"
    }
}

다음 예제에서는 원본 단계에서 protobuf 데이터를 역직렬화하거나 일괄 처리된 protobuf 데이터를 직렬화하기 위한 구성을 보여줍니다.

{
    "format": {
        "type": "protobuf",
        "descriptor": "Zm9v...", // The full descriptor
        "package": "package1",
        "message": "message1"
    }
}

CSV 데이터 형식

다음 구성 옵션을 사용하여 CSV 데이터를 역직렬화합니다.

필드	형식	설명	필수 여부	기본값	예시
`type`	`string enum`	역직렬화를 위한 형식	예	-	`CSV`
`header`	`boolean`	이 필드는 입력 데이터에 CSV 헤더 행이 있는지 여부를 나타냅니다.	예	-	`true`
`columns`	`array`	읽을 CSV의 스키마 정의입니다.	예	-	(다음 표 참조)
`path`	Path	역직렬화된 데이터를 작성해야 하는 데이터 프로세서 메시지 부분의 경로입니다.	(다음 참고 사항 참조)	-	`.payload`

참고 항목

원본 단계에서 데이터를 역직렬화할 때는 path를 지정할 필요가 없습니다. 역직렬화된 데이터는 메시지 .payload 섹션에 자동으로 배치됩니다.

열 배열의 각 요소는 다음 스키마가 있는 개체입니다.

필드	형식	설명	필수 여부	기본값	예시
`name`	`string`	CSV 헤더에 표시되는 열의 이름입니다.	예	-	`temperature`
`type`	`string enum`	데이터를 구문 분석하는 방법을 결정하는 데 사용되는 열에 보관된 데이터 프로세서 데이터 형식입니다.	아니요	string	`integer`
`path`	Path	열 값을 읽어야 하는 데이터의 각 레코드 내 위치입니다.	아니요	`.{{name}}`	`.temperature`

다음 구성 옵션을 사용하여 CSV 데이터를 직렬화합니다.

필드	형식	설명	필수 여부	기본값	예시
`type`	`string enum`	직렬화의 형식입니다.	예	-	`CSV`
`header`	`boolean`	이 필드는 직렬화된 CSV에 열 이름이 있는 헤더 줄을 포함할지 여부를 나타냅니다.	예	-	`true`
`columns`	`array`	쓸 CSV의 스키마 정의입니다.	예	-	(다음 표 참조)
`path`	Path	직렬화할 데이터가 기록되는 데이터 프로세서 메시지 부분의 경로입니다.	(다음 참고 사항 참조)	-	`.payload`

참고 항목

일괄 처리된 데이터를 직렬화할 때는 path를 지정할 필요가 없습니다. 기본 경로는 전체 메시지를 나타내는 .입니다.

필드	형식	설명	필수 여부	기본값	예시
`name`	`string`	CSV 헤더에 표시되는 열의 이름입니다.	예	-	`temperature`
`path`	Path	열 값을 기록해야 하는 데이터의 각 레코드 내의 위치입니다.	아니요	`.{{name}}`	`.temperature`

다음 예제에서는 일괄 처리되지 않은 CSV 데이터를 직렬화하기 위한 구성을 보여 줍니다.

{
    "format": {
        "type": "csv",
        "header": true,
        "columns": [
            {
                "name": "assetId",
                "path": ".assetId"
            },
            {
                "name": "timestamp",
                "path": ".eventTime"
            },
            {
                "name": "temperature",
                // Path is optional, defaults to the name
            }
        ],
        "path": ".payload"
    }
}

다음 예제에서는 일괄 처리된 CSV 데이터를 직렬화하기 위한 구성을 보여 줍니다. 일괄 처리된 데이터에 대한 최상위 수준 path를 생략합니다.

{
    "format": {
        "type": "csv",
        "header": true,
        "columns": [
            {
                "name": "assetId",
                "path": ".assetId"
            },
            {
                "name": "timestamp",
                "path": ".eventTime"
            },
            {
                "name": "temperature",
                // Path is optional, defaults to .temperature
            }
        ]
    }
}

다음 예제에서는 일괄 처리되지 않은 CSV 데이터를 역직렬화하기 위한 구성을 보여 줍니다.

{
    "format": {
        "type": "csv",
        "header": false,
        "columns": [
            {
                "name": "assetId",
                "type": "string",
                "path": ".assetId"
            },
            {
                "name": "timestamp",
                // Type is optional, defaults to string
                "path": ".eventTime"
            },
            {
                "name": "temperature",
                "type": "float"
                // Path is optional, defaults to .temperature
            }
        ],
        "path": ".payload"
    }
}

다음 예제에서는 원본 단계에서 일괄 처리된 CSV 데이터를 역직렬화하는 구성을 보여 줍니다.

{
    "format": {
        "type": "csv",
        "header": false,
        "columns": [
            {
                "name": "assetId",
                "type": "string",
                "path": ".assetId"
            },
            {
                "name": "timestamp",
                // Type is optional, defaults to string
                "path": ".eventTime"
            },
            {
                "name": "temperature",
                "type": "float",
                // Path is optional, defaults to .temperature
            }
        ]
    }
}

다음을 통해 공유

Azure IoT 데이터 프로세서 미리 보기 파이프라인의 직렬화 및 역직렬화 형식

메시지 역직렬화

메시지 직렬화

원시/JSON/MessagePack/CBOR 데이터 형식

프로토콜 버퍼 데이터 형식

CSV 데이터 형식

추가 리소스

다음을 통해 공유

Azure IoT 데이터 프로세서 미리 보기 파이프라인의 직렬화 및 역직렬화 형식

메시지 역직렬화

메시지 직렬화

원시/JSON/MessagePack/CBOR 데이터 형식

프로토콜 버퍼 데이터 형식

CSV 데이터 형식

관련 콘텐츠

추가 리소스