기능 설명

실시간 공역 데이터 보고를 활성화하면 서비스 제공업체로부터 웹훅 URL과 암호화 토큰을 받을 수 있습니다. 입력하고 저장하면, FlightHub API는 실시간 기체 데이터를 제3자에게 푸시할 수 있습니다. 다음은 타사 서비스 제공업체를 위한 통합 가이드입니다.

통합 가이드

데이터 보고 프로토콜

1. 요청 헤더

필드 이름	필드 코드	데이터 유형	설명	필수
데이터 소스	source	정수	1: 기체에서 직접 보고 2: 제조업체 시스템에서 보고 3: 추가 모듈에서 보고 4: 수집 기기에서 보고	예
보고 플랫폼	platform	문자열	플랫폼 이름(예: DJI Fly)	예
프로그램 버전	programVersion	문자열	버전 번호(예: version 1.0)	예
서명	signature	문자열	생성된 요청 서명	예
요청 타임스탬프	timestamp	문자열	요청 Unix 타임스탬프(초)	예
논스	nonce	문자열	무작위로 생성된 문자열	예

서명 생성 프로세스

입력 매개변수

• token: 애플리케이션 키(통합 서비스 제공업체가 제공하며, FlightHub 2에서 사용자가 구성함). 32~64자 길이여야 하며, 문자, 숫자, 특수기호 중 최소 세 가지를 조합해야 합니다.
• timestamp: 요청 타임스탬프(timestamp 요청 헤더에서 가져옴)
• nonce: 무작위 문자열(nonce 요청 헤더에서 가져옴)
• body: 요청 본문의 원시 바이트 데이터(예: JSON으로 직렬화된 RequestBody)

서명 규칙

1. timestamp, nonce, body를 이 순서로 구분자 없이 하나의 문자열로 연결합니다.
2. token을 키로 사용하는 HMAC-SHA256 알고리즘으로 연결된 문자열을 암호화합니다.
3. 암호화된 결과를 소문자 16진수 문자열로 변환합니다.

Go 코드 구현

import (
    "crypto/hmac"
    "crypto/sha256"
    "crypto/subtle"
    "encoding/hex"
)

func GenerateHMACSignature(appKey, timestamp, nonce string, body []byte) string {
    mac := hmac.New(sha256.New, []byte(appKey))
    mac.Write([]byte(timestamp))
    mac.Write([]byte(nonce))
    mac.Write(body)
    return hex.EncodeToString(mac.Sum(nil))
}

서명 검증 프로세스

검증 로직

1. 서버는 요청 헤더에서 다음 정보를 가져옵니다.
   • signature: 클라이언트가 생성한 서명
   • timestamp: 요청 타임스탬프
   • nonce: 무작위 문자열
2. 서버는 동일한 매개변수와 암호 키 appKey를 사용하여 서명을 다시 생성합니다.
3. 클라이언트의 서명이 서버가 생성한 서명과 일치하는지 확인하기 위해 일정 시간 비교 방식을 사용합니다.

Go 코드 구현

func VerifyHMACSignature(appKey, timestamp, nonce string, body []byte, signature string) bool {
    expected := GenerateHMACSignature(appKey, timestamp, nonce, body)
    return subtle.ConstantTimeCompare([]byte(expected), []byte(signature)) == 1
}

2. 요청 본문

JSON 형식

{
  "app_id":"default",
  "flight_hub_organization_id":"xxxx",
  "paths": [
    { /* FlightPath object */ },
    { /* FlightPath object */ }
  ]
}

필드 설명

필드	유형	필수	설명
app_id	string	예	고유한 애플리케이션 식별자입니다. 현재 기본값으로 설정되어 있습니다.
flight_hub_organization_id	string	예	사용자의 FlightHub 조직 ID
paths	FlightPath[]	예	비행경로 데이터 배열(아래 객체 구조 참조)

FlightPathRecord 구조 설명

이 구조는 비행경로 포인트 데이터를 설명하는 데 사용됩니다. 다음은 각 필드의 상세 설명입니다.

번호	필드 이름	필드 코드	데이터 유형	설명	필수
1	비행 기록 ID	order_id	문자열	형식: 제조업체 시리얼 넘버(SN)-8자리 이륙 날짜(YYYYMMDD)-8자리 무작위 코드. 예: 1581F5FHD25G100C1SDN-20240320-owvGyLqe. 동일한 ID가 전체 비행 동안 사용됩니다.	예
2	기체 시리얼 넘버	sn	문자열	제조업체의 기체 생산 SN	예
3	비행 상태	flight_status	문자열	TakeOff: 이륙 지점, Inflight: 비행 중, Land: 착륙 지점	예
4	통합 사회 신용 번호	manufacturer_id	문자열	제조업체의 통합 사회 신용 번호입니다.	예
5	CAAC 실명 등록 번호	uas_id	문자열	등록 번호가 없으면 기본값 UAS-DEFAULT를 사용하십시오.	예
6	현재 타임스탬프	time_stamp	문자열	UTC+8 시간, 형식: yyyyMMddHHmmss. 예: 20240124095001	예
7	제품 모델	uas_model	문자열	문자, 숫자 및/또는 기호의 조합.	예
8	좌표계 유형	coordinate	정수	1: WGS-84 2: CGCS2000 3: GLONASS-PZ90	예
9	경도	longitude	Long	단위: 도(°). 실제 값 = 필드 값 / 10⁷.	예
10	위도	latitude	Long	단위: 도(°). 실제 값 = 필드 값 / 10⁷.	예
11	진고 유형	height_type	정수	1: 이륙 지점 기준 고도(ALT) 2: 현재 위치 기준 고도(AGL)	예
12	진고	height	정수	단위: 미터(m). 실제 값 = 필드 값 / 10.	예
13	고도	altitude	정수	단위: 미터(m). 실제 값 = 필드 값 / 10.	예
14	수직 속도	vs	정수	단위: m/s. 실제 값 = 필드 값 / 10.	예
15	수평 비행 속도	gs	정수	단위: m/s. 실제 값 = 필드 값 / 10.	예
16	코스	course	정수	진북에서 시계 방향 각도(0~360°). 실제 값 = 필드 값 / 10. 데이터가 없는 경우 -999로 채우십시오.	예
17	RID 방송 상태	remote_id_status	정수	0: 비활성화됨   1: 활성화됨	예

본문 예:

{
	"app_id": "default",
	"flight_hub_organization_id": "105ddf05-54ce-4626-a872-cb32b8c98864",
	"paths": [{
		"order_id": "1529F6QAD23CB00A42DP-20251028-89W2aK2W",
		"sn": "1529F6QAD23CB00A42DP",
		"flight_status": "Land",
		"manufacturer_id": "925413007954257495",
		"uas_id": "UAS-DEFAULT",
		"time_stamp": "20251028115000",
		"uas_model": "M3D",
		"coordinate": 1,
		"longitude": 1243579943,
		"latitude": 217931488,
		"height_type": 1,
		"height": 0,
		"altitude": 187,
		"vs": 0,
		"gs": 0,
		"course": 1229,
		"remote_id_status": 1
	}]
}

3. 응답 본문

필드 이름	필드 코드	데이터 유형	설명
상태 코드	code	문자열	0 = 성공, 400 = 실패
결과 설명	result	문자열	자세한 설명(예: success)

응답 예:

{
  "code": "0",
  "result": "success"
}