연결 방식 정하기
제조사 시스템의 직접 API 전송, 또는 Site Agent의 HTTPS GET·MQTT v5 수집 중 현장에 맞는 방식을 정합니다.
제조사·FMS의 직접 전송 API 또는 HTTPS GET·MQTT v5 수집을 연결합니다. 데이터 형식과 연결 환경을 준비하고, 현장 담당자와 연동 담당자가 함께 수집·매핑을 확인합니다.
시연 기준 시각 · 2026-10-04 01:44 UTC
연동 담당자가 출처를 등록하고 Site Agent의 연결을 설정합니다.
AMR-031 · 배터리 잔량 48% · 관측 01:44:00 UTC
접수 → 처리 중 → 처리 완료
접수 01:44:02 UTC · 상태 조회 01:44:03 UTC · 1건AMR-031 · 연결됨 · 운행 중 · 배터리 잔량 48% · 유효 데이터
기존 로봇·장비와 FMS에서 상태·이벤트·미션·센서 데이터를 받습니다. 제조사 추가 인터페이스는 어댑터 확장과 연결 시험으로 적용합니다.
제조사 시스템의 직접 API 전송, 또는 Site Agent의 HTTPS GET·MQTT v5 수집 중 현장에 맞는 방식을 정합니다.
제조사·FMS 문서, 비식별 샘플, 장비 식별 규칙, 시각·단위와 네트워크 조건을 준비합니다. 인증 정보는 승인된 등록 환경에서 별도로 설정합니다.
현장·제조사 담당자는 원본 의미와 연결을 확인하고, 연동 담당자는 필드 매핑과 시험을 진행합니다. 운영 담당자가 수집 상태를 확인한 뒤 적용 범위를 정합니다.
장애와 버퍼 포화는 운영자에게 드러내고, 관측 공백을 정상 데이터처럼 채우지 않습니다.
제조사별 추가 인터페이스는 어댑터 확장으로 적용할 수 있습니다. 데이터 형식·인증·현장 네트워크에 맞춘 연결 시험 후 적용합니다.
HTTPS GET 주기 수집 · JSON 객체/NDJSON · 선택 Bearer 토큰 파일. 제조사 확장 필드와 원본을 보존합니다.
HTTPS GET · JSON/NDJSONMQTT v5 · 고정 topic QoS 1 구독 · TLS · 사용자/비밀번호 파일. 상태·이벤트·미션·텔레메트리 매핑을 지원합니다.
v5 · QoS 1 · TLSREST/MQTT 수집 · 암호화 로컬 버퍼 · 재전송. 콘솔에서 heartbeat·수집 상태·버퍼 사용량을 조회합니다.
수집·버퍼·재전송합성 데이터를 생성해 필드 매핑과 정규화 규칙을 시험합니다. 실제 제조사 SDK 연결 완료를 의미하지 않습니다.
합성 시험현재 구현된 전송 계약을 파일과 합성 예제로 확인하세요. 상태·센서·오류·미션 수신, Receipt 추적, 현재 상태 조회를 연결합니다.
공개 계약은 수신·접수 상태·현재 상태 조회의 6개 operation을 포함합니다. 관리·자격 발급·예측 API는 제공하지 않습니다. 계약 버전 확인: docs/api/openapi.yaml, SHA-256 ab41dd6bd8e19bb94613f19aaa9319fb639ba546368f37a6784a1a9eea67ebc6.
표시 코드와 파일은 같은 데이터이며 manifest에는 파일별 해시가 있습니다. 고정 시각·ID는 문서용입니다. 실제 전송 전 등록값과 실제 측정 시각으로 맞춥니다.
수신·Receipt 조회는 OAuth client_credentials의 ServiceBearer, 로봇 상태·부품 조회는 현재 범위에 할당된 UserBearer를 사용합니다. 고객·사업장 접근 범위를 요청 본문으로 넓힐 수 없습니다.
GET /api/v1/robots/{id}/components
POST /api/v1/robots/{id}/components
PATCH /api/v1/robot-components/{id}BATTERY·MOTOR·LIDAR·OTHER의 모델·일련번호·설치 및 교체 시각을 관리합니다. 변경은 자산 권한과 expectedVersion 검사 대상입니다. 서버 출처 등록은 이 부품 API와도 별개입니다.
시험 base URL과 OIDC token endpoint는 운영자가 지정한 로컬 HTTPS gateway를 사용합니다. 아래 RONIQ_TEST_BASE_URL, RONIQ_SERVICE_TOKEN, RONIQ_USER_TOKEN은 발급된 시험값을 담는 환경변수이며 공개 샌드박스 주소나 실제 토큰이 아닙니다.
상태 예제는 AMR-031의 OEM 보고 SOC 48%입니다. 예상 운용시간이나 위험 점수를 제조사 보고 DTO에 넣지 않습니다. 배치는 1~500항목·전체 1MiB, 원문 항목 decoded 512KiB 이내입니다.
응답의 message는 현재 서버 언어인 한국어를 유지합니다. 오류 코드와 schema는 언어에 따라 바꾸지 않습니다.
POST /ingest/v1/states ingestStates
POST /ingest/v1/telemetry ingestTelemetry
POST /ingest/v1/events ingestEvents
POST /ingest/v1/missions ingestMissions
GET /ingest/v1/receipts/{id} getIngestReceipt{
"connectorId": "connector-demo-031",
"sourceGeneration": 1,
"synthetic": true,
"items": [
{
"eventId": "state-demo-031-001",
"robotExternalId": "AMR-031",
"observedAt": "2026-10-04T01:44:00Z",
"sequence": 31,
"connectivity": "ONLINE",
"operation": "RUNNING",
"batterySoc": 48,
"source": {
"sourceId": "source-demo-states",
"mappingVersion": "mapping-demo-1",
"sourceQuality": "VALID",
"freshnessSeconds": 0
},
"rawPayload": {
"mediaType": "application/json",
"body": "eyJyb2JvdElkIjoiQU1SLTAzMSIsImJhdHRlcnlTb2MiOjQ4fQ==",
"sha256": "c0c2eef3dd6df4fed07b1d5543e9563b4347e814ce2595277691d3ab5673d948"
},
"extensions": {
"ext.sim.source": "SIMULATOR"
}
}
]
}원문은 {"robotId":"AMR-031","batterySoc":48}의 UTF-8 bytes입니다. rawPayload.body는 그 bytes의 base64, sha256은 같은 bytes의 해시입니다. 예제 품질은 명시적 VALID이며 실제 출처의 품질이 없거나 미정이면 UNKNOWN으로 보존합니다.
curl --request POST "$RONIQ_TEST_BASE_URL/ingest/v1/states" \
--header "Authorization: Bearer $RONIQ_SERVICE_TOKEN" \
--header "Idempotency-Key: demo-state-031-001" \
--header "Content-Type: application/json" \
--data-binary @apps/web/public/integration/1.1.6/states.request.json{
"success": true,
"code": "SUCCESS",
"message": "처리되었습니다.",
"data": {
"receiptId": "receipt-demo-031-001",
"acceptedCount": 1,
"status": "RECEIVED",
"receivedAt": "2026-10-04T01:44:02Z",
"synthetic": true,
"payloadRefs": [
"raw-demo-031-001"
],
"checksums": [
"c0c2eef3dd6df4fed07b1d5543e9563b4347e814ce2595277691d3ab5673d948"
]
},
"meta": {
"requestId": "request-demo-031",
"timestamp": "2026-10-04T01:44:02Z"
}
}202는 내구 저장 접수이며 정규화 완료가 아닙니다. data.receiptId로 같은 서비스 범위의 수신증을 조회합니다.
curl "$RONIQ_TEST_BASE_URL/ingest/v1/receipts/<RECEIPT_ID>" \
--header "Authorization: Bearer $RONIQ_SERVICE_TOKEN"
curl "$RONIQ_TEST_BASE_URL/api/v1/robots/<REGISTERED_ROBOT_ID>/state" \
--header "Authorization: Bearer $RONIQ_USER_TOKEN"RECEIVED → PROCESSING → COMPLETED 또는 FAILED로 진행합니다. 아래는 가능한 상태별 예제이며 완료 후 실패로 바뀌었다는 이력이 아닙니다. FAILED 조회도 HTTP 200·success:true이며 data.status로 처리 실패를 구분합니다. 오류 객체는 요청 자체의 거절입니다.
{
"success": true,
"code": "SUCCESS",
"message": "처리되었습니다.",
"data": {
"receiptId": "receipt-demo-031-001",
"acceptedCount": 1,
"status": "PROCESSING",
"receivedAt": "2026-10-04T01:44:02Z",
"synthetic": true,
"payloadRefs": [
"raw-demo-031-001"
],
"checksums": [
"c0c2eef3dd6df4fed07b1d5543e9563b4347e814ce2595277691d3ab5673d948"
]
},
"meta": {
"requestId": "request-demo-031",
"timestamp": "2026-10-04T01:44:02Z"
}
}{
"success": true,
"code": "SUCCESS",
"message": "처리되었습니다.",
"data": {
"receiptId": "receipt-demo-031-001",
"acceptedCount": 1,
"status": "COMPLETED",
"receivedAt": "2026-10-04T01:44:02Z",
"synthetic": true,
"payloadRefs": [
"raw-demo-031-001"
],
"checksums": [
"c0c2eef3dd6df4fed07b1d5543e9563b4347e814ce2595277691d3ab5673d948"
]
},
"meta": {
"requestId": "request-demo-031",
"timestamp": "2026-10-04T01:44:02Z"
}
}{
"success": true,
"code": "SUCCESS",
"message": "처리되었습니다.",
"data": {
"receiptId": "receipt-demo-031-001",
"acceptedCount": 1,
"status": "FAILED",
"receivedAt": "2026-10-04T01:44:02Z",
"synthetic": true,
"payloadRefs": [
"raw-demo-031-001"
],
"checksums": [
"c0c2eef3dd6df4fed07b1d5543e9563b4347e814ce2595277691d3ab5673d948"
]
},
"meta": {
"requestId": "request-demo-031",
"timestamp": "2026-10-04T01:44:02Z"
}
}{
"success": false,
"code": "BUSINESS_RULE_VIOLATION",
"message": "등록되지 않은 원본 출처입니다.",
"data": null,
"meta": {
"requestId": "request-demo-031",
"timestamp": "2026-10-04T01:44:02Z"
}
}{
"success": true,
"code": "SUCCESS",
"message": "처리되었습니다.",
"data": {
"robotId": "robot-demo-031",
"connectivity": "ONLINE",
"operation": "RUNNING",
"healthOem": null,
"batterySoc": 48,
"observedAt": "2026-10-04T01:44:00Z",
"receivedAt": "2026-10-04T01:44:02Z",
"stale": false,
"synthetic": true,
"sourceId": "source-demo-states",
"mappingVersion": "mapping-demo-1",
"freshnessSeconds": 0,
"extensions": {
"ext.sim.source": "SIMULATOR"
}
},
"meta": {
"requestId": "request-demo-031",
"timestamp": "2026-10-04T01:44:03Z"
}
}robotId는 서버 ID이고 AMR-031은 robotExternalId입니다. observedAt은 OEM 관측시각, receivedAt은 서버 수신시각입니다. 정규화 완료 뒤 같은 출처·SOC·매핑 버전인지 대사합니다.
REST adapter는 등록된 HTTPS URL을 GET으로 주기 조회하며 JSON 객체·NDJSON을 읽습니다. 선택 Bearer token은 파일에서 읽고 redirect·환경 proxy를 자동 추종하지 않습니다. JSON 배열은 항목 경계를 정의한 별도 adapter가 필요합니다.
MQTT v5는 현장 broker의 단일 고정 topic을 QoS 1로 구독하며 외부 연결은 TLS와 사용자·비밀번호 파일을 사용합니다. +/# wildcard는 거절합니다. 다음 message와 Source 설정은 같은 합성 출처입니다.
{
"eventId": "state-demo-031-001",
"robotId": "AMR-031",
"observedAt": "2026-10-04T01:44:00Z",
"sequence": 31,
"connectivity": "ONLINE",
"operation": "RUNNING",
"soc": 48,
"quality": "VALID"
}{
"sourceId": "source-demo-states",
"transport": "mqtt",
"kind": "states",
"mappingVersion": "mapping-demo-1",
"mqttTopic": "factory/a/amr-031/state",
"fields": {
"eventId": "eventId",
"robotExternalId": "robotId",
"observedAt": "observedAt",
"sequence": "sequence",
"connectivity": "connectivity",
"operation": "operation",
"batterySoc": "soc",
"sourceQuality": "quality"
}
}{
"agentId": "agent-demo-031",
"tenantId": "tenant-demo",
"customerId": "customer-demo",
"siteId": "site-demo",
"connectorId": "connector-demo-031",
"sourceGeneration": 1,
"synthetic": true,
"bufferCapacityBytes": 1073741824,
"bufferReserveBytes": 67108864,
"heartbeatSeconds": 60,
"sources": [
{
"sourceId": "source-demo-states",
"transport": "rest",
"kind": "states",
"mappingVersion": "mapping-demo-1",
"fields": {
"eventId": "eventId",
"robotExternalId": "robotId",
"observedAt": "observedAt",
"sequence": "sequence",
"connectivity": "connectivity",
"operation": "operation",
"batterySoc": "batterySoc",
"sourceQuality": "quality"
},
"restUrl": "https://oem.example.invalid/state",
"pollSeconds": 10
}
]
}Agent는 원문을 암호화 spool에 commit한 뒤 MQTT ACK를 보냅니다. QoS 1 중복은 가능하며 broker persistent session의 보존 범위를 넘어선 무손실을 보장하지 않습니다. Agent → Core 전송은 같은 HTTPS 수신 API·Receipt 규칙을 따릅니다.
Compose는 합성 OEM REST 서비스의 구성 예제입니다. 실행하려면 별도로 제공받은 RONIQ 저장소의 tools/simulator 소스와 Docker가 필요합니다. 공개 다운로드 파일만으로 실행되는 패키지는 아닙니다. 접근 권한은 담당 운영자와 확인하고, 저장소 루트에서 사용하며 18081 포트가 비어 있어야 합니다.
docker compose --project-directory . \
-f apps/web/public/integration/1.1.6/compose.synthetic.yaml config --quiet
docker compose --project-directory . \
-f apps/web/public/integration/1.1.6/compose.synthetic.yaml up --build simulator
curl http://127.0.0.1:18081/vendor/atlas/states
docker build -t roniq-site-agent:local apps/site-agentAgent 이미지에는 저장소의 apps/site-agent 소스가 필요합니다. 실행 전 운영자에게 등록 범위와 시험용 API/OIDC 환경을 할당받고, 별도 spool 암호키·서비스 secret 파일·UID 10001 볼륨 권한을 준비하세요. 복사·다운로드는 파일을 제공하며 API 실행이나 인증 발급을 대신하지 않습니다. simulator.agent_config의 12개 합성 출처에는 별도 MQTT broker도 필요합니다.
# Set PYTHONPATH=tools/simulator in an isolated Python environment.
python -m simulator.agent_config --help
python -m simulator.agent_config --output <LOCAL_AGENT_JSON> \
--agent-id <REGISTERED_AGENT_ID> --tenant-id <REGISTERED_TENANT_ID> \
--customer-id <REGISTERED_CUSTOMER_ID> --site-id <REGISTERED_SITE_ID> \
--connector-id <REGISTERED_CONNECTOR_ID>아래 방식으로 데이터를 연결할 수 있습니다. 실제 제조사 연결에는 해당 환경의 매핑과 시험이 필요합니다. 작은 화면에서는 표 안에서 좌우로 이동할 수 있습니다.
| 인터페이스 | 데이터 범위 | 연결 전 확인 |
|---|---|---|
| HTTPS REST | 직접 POST: states·telemetry·events·missions. Agent GET: JSON 객체·NDJSON 매핑. | 시험 URL·접근 권한·필드 매핑·단위·관측 시각을 준비하고 접수 상태와 정규화 결과를 대사합니다. |
| MQTT v5 / QoS 1 | 상태·센서·오류·미션의 JSON 객체. 출처별 고정 topic과 명시적 필드 매핑. | 고정 topic·TLS·자격 파일을 준비하고 단절·재연결·중복 수신을 현장 broker에서 확인합니다. |
| Site Agent | REST/MQTT → 암호 spool → HTTPS 수신 → Receipt. 출처·단위·시각·품질 보존. | 소스·등록 범위·비밀 파일·볼륨 권한을 준비하고 매핑·재전송·품질·상태를 시험 환경에서 확인합니다. |
| UserBearer 자산 API | 로봇 상태 조회, BATTERY·MOTOR·LIDAR·OTHER의 모델·일련번호·설치/교체 기록. | 현재 할당 범위·자산 권한·expectedVersion 검사. 수집 서비스 자격과 분리. |
현재 Health·Battery·Anomaly API는 품질·coverage·근거·분석 버전이 있는 시험 관측입니다. 새 예상 운용시간·부품별 고장 위험·누적 카운터·예측 feed는 추가 개발 범위이며 이 공개 계약에 포함하지 않습니다. 기존 Incident 서명 Webhook은 예측 알림과 구분합니다. OEM/FMS의 주행·안전 제어는 유지합니다.
검증은 단위·시각·출처 대사, 중복·순서 변경, 단절·재전송, 잘못된 센서값, 부품 교체와 범위 밖 접근을 확인합니다. 합성 시험·실제 제조사 연결·예측 성능 평가는 각각 기록합니다. 파일·schema의 정적 일치는 실제 연결 성공을 뜻하지 않습니다.
로봇·FMS와 필요한 운영 범위를 알려주세요. 연결 가능한 환경부터 함께 확인합니다.
도입 상담 시작하기