DTS API

DTS (Data Traceability Service) API에 대한 소개 페이지입니다.

DTS API 소개

ChainZ API Service의 DTS API는 ERC721 토큰 기반으로 데이터의 접근 상태 내역을 추적할 수 있게 해줍니다.

데이터에 대한 접근 상태 (e.g. CREATED, SENT, RECEIVED, DELETED, ANALYZED, RESULT, CHANGE_STATE) 저장과 데이터의 메타데이터 정보 및 접근 내역 조회 기능을 제공합니다.

DTS API 사용

ChainZ Provider 정보 등록

DTS API를 사용하기 위해서는 먼저 DTS 관리자를 통해 ChainZ provider에 대한 정보를 등록해야 합니다. ChainZ API Service에서 생성한 계정 정보와 Provider가 관리하는 회사 정보(회사 이름 및 회사 관리자의 아이디, 이메일, 닉네임) 를 DTS 관리자에게 전달합니다.

HTTP Request

ChainZ DTS API URL: https://dts-api.chainz.biz

API 에 접근하기 위하여 항상 HTTP Header에 엑세스 토큰과 API 키를 넣어야 합니다.

curl -X POST \
  "https://{DTS API Url}" \
  -H  "accept: application/json" \
  -H  "Authorization: Bearer {엑세스 토큰}" \
  -H  "x-api-key: {API key}" \
  -H 'Content-Type: application/json' \
  -d '{Json Body}'

1. 사용자 생성

DTS 사용자를 생성합니다. 사용자 별 블록체인 계정 및 ID가 발급됩니다. ID는 데이터를 등록하고 접근 내역을 기록할 때 사용합니다. 사용자 생성 API를 호출하거나 회원가입을 통해 사용자 생성이 가능합니다.

1) 사용자 생성 API 호출

URL : https://dts-api.chainz.biz/api/v1/users
Request

{
    "loginId": <로그인 ID>,
    "email": <이메일>,
    "userAlias": <닉네임>,
    "companyId": <소속 회사의 ID>,
    "userType": <사용자 type: PROVIDER>,
    "userRole": <사용자 role: MEMBER>,
    "useYn": <사용여부>
}

Response

{
    "success": true,
    "result": {
        "loginId": <로그인 ID>,
        "userId": <사용자 ID>,
        "userAlias": <닉네임>,
        "companyInfo": {
            "id": <소속 회사의 ID>,
            "name": <소속 회사의 이름>
        },
        "userType": <사용자 type; PROVIDER>,
        "userRole": <사용자 role; MEMBER>,
        "createdAt": <사용자 생성 시간>,
        "useYn": <사용여부>
    }
}

2) 회원가입

사용자가 직접 Data Flow 화면에서 회원가입 할 수 있습니다.

2. 데이터 등록

데이터의 메타데이터를 등록합니다. 데이터 접근 상태는 CREATED 로 저장됩니다.

URL : https://dts-api.chainz.biz/api/v1/data
Request

{
    "fileName": <데이터(파일) 이름>,
    "genTime": <데이터 생성 시간>,
    "providerId": <실제로 데이터를 제공하는 사용자의 ID>,
    "chainId": <블록체인 ID>,
    "hashType": <해시 알고리즘 종류>,
    "hash": <데이터의 해시 값>,
    "expTime": <데이터 만료 시간>,
    "actorId": <실제로 데이터에 접근하는 사용자의 ID>,
    "receiverIds": <데이터를 전달받는 사용자 ID 리스트>,
    "parentDataIds": <부모 데이터 ID 리스트>,
    "fileExtension": <파일 확장자 종류>,
    "fileSize": <파일 크기>,
    "hashSize": <해시 암호화한 파일의 크기>,
    "productInfo": {
        "productId": <산출 ID>,
        "productName": <산출물 이름>,
        "description": <산출물 상세 설명>,
        "tags": <산출물 태그 리스트>,
        "dataType": <산출물의 데이터 타입>,
        "productType": <산출물 타입>,
        "dataFormat": <산출물 데이터의 포맷>,
        "dataSample": <산출물 예시>,
        "license": <산출물 라이센스>,
        "company": <회사 이름>
    }
}

Response

{
    "success": true,
    "result": {
        "dataInfo": {
            "dataId": <데이터 ID>,
            "fileName": <데이터(파일) 이름>,
            "hashType": <해시 알고리즘 종류>,
            "hash": <데이터의 해시 값>,
            "genTime": <데이터 생성 시간>,
            "expTime": <데이터 만료 시간>,
            "generation": <데이터의 수직적 계층 중 현 데이터의 위치>,
            "providerId": <실제로 데이터를 제공하는 사용자의 ID>,
            "providerCode": <ChainZ provider 코드>,
            "chainId": <블록체인 ID>,
            "fileExtension": <파일 확장자 종류>,
            "fileSize": <파일 크기>,
            "hashSize": <해시 암호화한 파일의 크기>,
            "actorId": <실제로 데이터에 접근하는 사용자의 ID>,
            "receiverIds": <데이터를 전달받는 사용자 ID 리스트>,
            "parentDataIds": <부모 데이터 ID 리스트>,
            "ownerInfo": {
                "userId": <데이터 소유자(제공자) ID>,
                "userName": <데이터 소유자 이름>,
                "email": <데이터 소유자 이메일>,
                "userRole": <데이터 소유자의 사용자 role>,
            },
            "sharedDepartmentList": [
                {
                    "id": <데이터에 접근할 수 있는 부서의 ID>,
                    "name": <데이터에 접근할 수 있는 부서의 이름>,
                }
            ],
            "dataProduct": <데이터 산출물 정보>,
        "traceInfo": {
            "traceId": <트레이스(내역) ID>,
            "dataId": <데이터 ID>,
            "actionInfo": {
                "actionId": <데이터 접근 상태 ID>,
                "actionCode": <데이터 접근 상태 코드>,
                "actionName": <데이터 접근 상태 이름>,
                "actionImgUrl": <데이터 접근 상태 아이콘의 이미지 URL>,
                "actionBgColor": <데이터 접근 상태 아이콘의 배경 색>,
                "sequence": <데이터 접근 상태의 고유 순서>,
            },
            "accessTime": <데이터 접근 시간>,
            "transactionHash": <블록체인에 트레이스 정보 등록 결과로 받는 트랜잭션의 해시>,
            "blockNumber": <트랙잭션이 포함된 블록체인 블록의 값>,
            "status": <트랜잭션 상태>,
            "accessorId": <실제로 요청을 수행한 클라이언트의 ID>,
            "actorId": <실제로 데이터에 접근하는 사용자의 ID>,
        }
    }
}

3. 데이터 접근 기록 생성

데이터 접근 기록 (트레이스)을 생성합니다. 접근 상태의 종류는 SENT, RECEIVED, DELETED, ANALYZED, CHANGE_STATE 등이 있습니다.

URL : https://dts-api.chainz.biz/api/v1/data/{dataId}/access
Request

{
    "dataAccessType": <데이터 접근 상태 종류>,
    "chainId": <블록체인 ID>,
    "actorId": <실제로 데이터에 접근하는 사용자의 ID>,
    "message": <데이터 접근 상태에 대한 메세지>,
    "messageHash": <메세지의 해시 값>,    
    "toId": <데이터를 전달받는 사용자의 ID - SENT인 경우 필수>,
    "fromId": <데이터를 전송하는 사용자의 ID - RECEIVED인 경우 필수>,
}

Response

{
    "success": true,
    "result": {
        "traceId": <트레이스(내역) ID>,
        "dataId": <데이터 ID>,
        "actionInfo": <데이터 접근 상태 정보>,
        "accessTime": <데이터 접근 시간>,
        "message": <데이터 접근 상태에 대한 메세지>,
        "messageHash": <메세지의 해시 값>,        
        "toId": <데이터를 전달받는 사용자의 ID>,
        "fromId": <데이터를 전송하는 사용자의 ID>,
        "transactionHash": <블록체인에 트레이스 정보 등록 결과로 받는 트랜잭션의 해시>,
        "blockNumber": <트랙잭션이 포함된 블록체인 블록의 값>,
        "status": <트랜잭션 상태>,
        "accessorId": <실제로 요청을 수행한 클라이언트의 ID>,
        "actorId": <실제로 데이터에 접근하는 사용자의 ID>,
        "resultInfo": {
            "resultDataId": <데이터 기반으로 생성된 결과 데이터의 ID>,
            "parents": <결과 데이터의 부모 데이터 리스트>
        }
    }
}

4. 데이터 리스트 조회

데이터 리스트를 조회합니다. 데이터 리스트는 다양한 쿼리 파라미터를 지정하여 조회할 수 있습니다.

URL : https://dts-api.chainz.biz/api/v1/data

Request

Query parameters

- dataID: 데이터 ID
- providerId: 실제로 데이터를 제공하는 사용자의 ID
- providerName: 실제로 데이터를 제공하는 사용자의 이름
- fileName: 데이터(파일) 이름
- hash: 데이터의 해시 값
- fromGenTime: 데이터 생성 시간 조회를 위한 시작 시간
- toGenTime: 데이터 생성 시간 조회를 위한 종료 시간
- fromRecentAccessTime: 데이터 최신 접근 시간 조회를 위한 시작 시간
- toRecentAccessTime: 데이터 최신 접근 시간 조회를 위한 종료 시간
- currentActionId: 최신 데이터 접근 상태의 ID
- offset: 페이징을 위한 Offset 값
- limit: 페이징을 위한 Limit 값

Response

{
    "success": true,
    "result": {    
        "totalElements": <전체 데이터 수>,
        "totalPages": <전체 페이지 수>,
        "content": [
            {
                "dataId": <데이터 ID>,
                "providerId": <실제로 데이터를 제공하는 사용자의 ID>,
                "providerName": <실제로 데이터를 제공하는 사용자의 이름>,
                "fileName": <데이터(파일) 이름>,
                "genTime": <데이터 생성 시간>,
                "providerCode": <ChainZ provider 코드>,
                "chainId": <블록체인 ID>,
                "traceCount": <데이터의 접근 내역 수>,
                "lastTraceTime": <최신 접근 상태 기록 시간>,
                "lastActionInfo": <데이터의 최신 접근 상태 정보>,
                "ownerInfo": {
                   "userId": <데이터 소유자 ID>,
                   "userName": <데이터 소유자 이름>,
                   "email": <데이터 소유자 이메일>,
                   "userRole": <데이터 소유자의 사용자 role>,
                }
            }
        ]
    }
}

5. 데이터 정보 조회

데이터 정보를 조회합니다. 조회하고자 하는 데이터의 ID가 필요합니다.

URL : https://dts-api.chainz.biz/api/v1/data/{dataId}
Request
- Request parameter
  - dataID: 데이터 ID
Response

{
    "success": true,
    "result": {  
        "dataId": <데이터 ID>,
        "fileName": <데이터(파일) 이름>,
        "hashType": <해시 알고리즘 종류>,
        "hash": <데이터의 해시 값>,
        "genTime": <데이터 생성 시간>,
        "expTime": <데이터 만료 시간>,
        "generation": <데이터의 수직적 계층 중 현 데이터의 위치>,
        "providerId": <실제로 데이터를 제공하는 사용자의 ID>,
        "providerCode": <ChainZ provider 코드>,
        "chainId": <블록체인 ID>,
        "fileExtension": <파일 확장자 종류>,
        "fileSize": <파일 크기>,
        "hashSize": <해시 암호화한 파일의 크기>,
        "actorId": <실제로 데이터에 접근하는 사용자의 ID>,
        "receiverIds": <데이터를 전달받는 사용자 ID 리스트>,
        "parentDataIds": <부모 데이터 ID 리스트>,
        "ownerInfo": <데이터 소유자 정보>,
        "sharedDepartmentList": <데이터에 접근할 수 있는 부서 리스트>,
        "dataProduct": <데이터 산출물 정보>
    }
}

6. 데이터 접근 내역 (트레이스) 리스트 조회

데이터의 접근 내역(트레이스) 리스트를 조회합니다. 트레이스 리스트는 다양한 쿼리 파라미터를 지정하여 조회할 수 있습니다.

URL : https://dts-api.chainz.biz/api/v1/traces

Request

Query parameters

- providerId: 실제로 데이터를 제공하는 사용자의 ID
- txHash: 블록체인에 트레이스 정보 등록 결과로 받는 트랜잭션의 해시
- fileName: 데이터(파일) 이름
- dataID: 데이터 ID
- accessorName: 실제로 요청을 수행한 클라이언트의 이름
- actorName: 실제로 데이터에 접근하는 사용자의 이름
- accessActionId: 데이터 접근 상태 ID
- fromAccessTime: 데이터 접근 시간 조회를 위한 시작 시간
- toAccessTime: 데이터 접근 시간 조회를 위한 종료 시간
- offset: 페이징을 위한 Offset 값
- limit: 페이징을 위한 Limit 값

Response

{
    "success": true,
    "result": {    
        "totalElements": <전체 데이터 수>,
        "totalPages": <전체 페이지 수>,
        "content": [
            {
                "traceId": <트레이스(내역) ID>,
                "dataId": <데이터 ID>,
                "actionInfo": <데이터 접근 상태 정보>,
                "accessTime": <데이터 접근 시간>,
                "message": <데이터 접근 상태에 대한 메세지>,
                "messageHash": <메세지의 해시 값>,        
                "toId": <데이터를 전달받는 사용자의 ID>,
                "fromId": <데이터를 전송하는 사용자의 ID>,
                "transactionHash": <블록체인에 트레이스 정보 등록 결과로 받는 트랜잭션의 해시>,
                "blockNumber": <트랙잭션이 포함된 블록체인 블록의 값>,
                "status": <트랜잭션 상태>,
                "dataInfo": {
                    "dataId": <데이터 ID>,
                    "fileName": <데이터(파일) 이름>,
                },
                "actor": {
                    "userId": <실제로 데이터에 접근하는 사용자의 ID>,
                    "userName": <실제로 데이터에 접근하는 사용자의 이름>
                },
                "accessor": {
                    "userId": <실제로 요청을 수행한 클라이언트의 ID>,
                    "userName": <실제로 요청을 수행한 클라이언트의 이름>
                },
                "resultInfo": {
                    "resultDataId": <데이터 기반으로 생성된 결과 데이터의 ID>,
                    "parents": <결과 데이터의 부모 데이터 리스트>
                }
            }
        ]
    }
}

7. 데이터 접근 내역 (트레이스) 정보 조회

데이터의 접근 내역(트레이스) 정보를 조회합니다. 조회하고자 하는 트레이스의 ID가 필요합니다.

URL : https://dts-api.chainz.biz/api/v1/traces/{traceId}
Request
- Request parameter
  - traceID: 트레이스 ID
Response

{
    "success": true,
    "result": {
        "traceId": <트레이스(내역) ID>,
        "dataId": <데이터 ID>,
        "actionInfo": <데이터 접근 상태 정보>,
        "accessTime": <데이터 접근 시간>,
        "message": <데이터 접근 상태에 대한 메세지>,
        "messageHash": <메세지의 해시 값>,        
        "toId": <데이터를 전달받는 사용자의 ID>,
        "fromId": <데이터를 전송하는 사용자의 ID>,
        "transactionHash": <블록체인에 트레이스 정보 등록 결과로 받는 트랜잭션의 해시>,
        "blockNumber": <트랙잭션이 포함된 블록체인 블록의 값>,
        "status": <트랜잭션 상태>,
        "dataInfo": {
            "dataId": <데이터 ID>,
            "fileName": <데이터(파일) 이름>,
        },
        "actor": {
            "userId": <실제로 데이터에 접근하는 사용자의 ID>,
            "userName": <실제로 데이터에 접근하는 사용자의 이름>
        },
        "accessor": {
            "userId": <실제로 요청을 수행한 클라이언트의 ID>,
            "userName": <실제로 요청을 수행한 클라이언트의 이름>
        },
        "resultInfo": {
            "resultDataId": <데이터 기반으로 생성된 결과 데이터의 ID>,
            "parents": <결과 데이터의 부모 데이터 리스트>
        }
    }
}

List of DTS APIs

PreviousNFT API NextMonitoring 소개

Last updated 2 years ago

Was this helpful?