애플리케이션 연동

IT 엔지니어개발자

시작하기

기본 개념

애플리케이션에서 파일 전송 기능 실행하기

애플리케이션에서 파일을 처리하는 업무는 파일을 준비하고 전송을 요청한 뒤, 처리 결과에 따라 다음 업무를 진행하는 흐름으로 구성됩니다.

애플리케이션 연동은 파일 전송 기능을 애플리케이션의 요청과 연결해 필요한 시점에 파일 전송을 실행하고, 처리 결과를 애플리케이션의 업무 로직에 활용할 수 있도록 구성합니다.

text
Application
     │
     │ Transfer Request
     ▼
File Transfer
     │
     ├── File Processing
     ├── Progress
     └── Result
             │
             ▼
Application Logic

이를 통해 파일 전송과 결과 처리를 애플리케이션의 업무 기능과 연결할 수 있습니다.

연동 흐름

전송 요청부터 결과 처리까지 하나의 흐름으로 연결하기

애플리케이션에서 파일 전송 요청이 발생하면 전송할 파일과 대상 정보를 기준으로 작업을 실행합니다.

전송 과정의 진행 상태와 응답 정보를 애플리케이션에서 활용하고, 최종 결과에 따라 다음 업무 로직을 이어갈 수 있습니다.

text
파일 전송 요청
      │
      ▼
파일 · 대상 정보 설정
      │
      ▼
전송 작업 실행
      │
      ▼
상태 · 응답 정보 수신
      │
      ▼
최종 결과 확인
      │
      ▼
애플리케이션 로직 처리

하나의 요청을 기준으로 파일 전송과 결과 처리를 연결하면 완료된 작업을 다음 업무와 자연스럽게 이어갈 수 있습니다.

개발 효과

파일 전송 기능을 애플리케이션 업무 흐름에 적용하기

애플리케이션 연동을 통해 파일 전송에 필요한 실행 과정과 결과 처리를 서비스 기능과 연결할 수 있습니다.

구분애플리케이션 연동
전송 실행애플리케이션의 요청을 기준으로 파일 전송 시작
상태 활용진행 상태와 응답 정보를 화면과 업무 로직에 연결
결과 처리최종 결과를 다음 업무 기능에 활용
업무 확장전송 완료 후 저장, 처리, 알림 등 다음 작업 연결

이렇게 구성하면 파일 전송 요청부터 결과 처리까지 애플리케이션의 업무 흐름에 맞춰 활용할 수 있습니다.

IT 엔지니어

애플리케이션 파일 전송 연동을 구성하고 관리하기

연동 구성

애플리케이션과 파일 전송 환경 연결하기

먼저 애플리케이션에서 파일 전송 기능을 사용할 수 있도록 파일 전송 환경과 연동 방식을 구성합니다.

애플리케이션의 요청이 파일 전송 작업으로 연결되고, 실행 상태와 결과 정보를 다시 받을 수 있도록 요청과 응답 경로를 설정합니다.

text
┌─────────────────┐
│   Application   │
└────────┬────────┘
         │
         │ Request / Response
         ▼
┌─────────────────┐
│ Transfer Layer  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Transfer Device │
└─────────────────┘

연동 환경을 구성하면 애플리케이션의 업무 기능과 실제 파일 전송 작업을 연결할 수 있습니다.

요청 구성

전송할 파일과 대상, 실행 조건 정하기

연동된 애플리케이션에서 어떤 요청을 기준으로 파일 전송을 실행할지 구성합니다.

요청에는 전송할 파일과 파일 경로, 대상 위치, 실행에 필요한 조건을 포함할 수 있습니다.

text
Transfer Request
       │
       ├── Source
       │      └── File / Path
       │
       ├── Target
       │      └── Device / Workspace
       │
       └── Options
              │
              ▼
         Transfer Run

구성 항목설정 내용
Source전송할 파일 또는 파일 경로
Target파일을 전송할 장비 또는 작업 공간
Request애플리케이션에서 전달하는 요청 정보
Options파일 처리에 적용할 실행 조건
Flow요청에 따라 실행할 파일 전송 작업

요청 구조를 구성하면 애플리케이션의 업무 조건에 따라 필요한 파일 전송을 실행할 수 있습니다.

응답 처리

전송 상태와 응답 결과를 애플리케이션 로직에 연결하기

파일 전송이 실행되면 시작과 진행, 완료 과정에서 상태와 응답 정보가 생성됩니다.

이 정보를 애플리케이션의 화면과 업무 로직에 연결하면 현재 진행 상황을 표시하고, 각 결과에 맞는 처리 흐름을 구성할 수 있습니다.

text
Transfer Run
     │
     ├── Started
     │
     ├── Progress
     │
     └── Result
            │
       ┌────┼────┐
       ▼    ▼    ▼
    Success Retry Error
       │    │    │
       ▼    ▼    ▼
    Next   Retry Result
    Logic  Run   Handling

전송 정보애플리케이션 활용
Started전송 시작 상태 표시
Progress진행률과 처리 상태 표시
Success다음 업무 로직 실행
Retry재실행 조건에 따라 작업 다시 요청
Error응답 정보를 기준으로 처리 흐름 연결

이 섹션에서 전송 과정의 상태와 최종 응답 결과를 하나의 처리 구조로 관리하므로, 기존의 상태와 이벤트 처리오류 대응에서 반복되던 내용을 통합했습니다.

연동 검증

애플리케이션에서 최종 전송 결과 확인하기

연동 구성이 완료되면 애플리케이션에서 실제 파일 전송 요청을 실행하고 전체 처리 결과를 확인합니다.

요청한 파일이 지정된 대상으로 처리되었는지 확인하고, 애플리케이션에서 받은 결과와 파일 전송 실행 기록을 함께 검증합니다.

text
Application Request
        │
        ▼
   Transfer Run
        │
        ▼
  File Processing
        │
        ▼
  Result Response
        │
   ┌────┴────┐
   ▼         ▼
Application  Run
 Result      Record
   │         │
   └────┬────┘
        ▼
   Final Check

연동 검증에서는 다음 정보를 기준으로 전체 흐름을 확인합니다.

확인 항목확인 내용
요청애플리케이션에서 생성된 전송 요청
실행요청에 따라 생성된 파일 전송 작업
파일처리된 파일과 파일 수, 용량
대상지정된 장비 또는 작업 공간
상태전송 진행 상태와 최종 결과
응답애플리케이션으로 반환된 결과 정보

개발자

업무 애플리케이션에서 전송을 실행하고 진행·제어·결과를 업무 데이터와 연결하기

연동 준비

공통 호출 코드와 상태 값 준비하기

import os
import requests

BASE_URL = os.getenv("INNORIX_BASE_URL", "https://app.innorix.com").rstrip("/")
TOKEN = os.environ["INNORIX_ACCESS_TOKEN"]
WORKSPACE_ID = os.getenv("INNORIX_WORKSPACE_ID")   # optional; falls back to the current workspace

STATUS_COMPLETE = 2
TERMINAL = {2, 4, 5, 9, 99}          # complete / error / cancelled / partial / failed
NOT_SUCCEEDED = {4, 5, 9, 99}


def api(method, path, body=None, params=None):
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    }

    if WORKSPACE_ID:
        headers["x-workspace-id"] = WORKSPACE_ID

    response = requests.request(
        method, BASE_URL + path,
        headers=headers, json=body, params=params, timeout=30,
    )

    payload = response.json() if response.content else {}

    if not response.ok:
        raise RuntimeError(payload.get("message") or f"HTTP {response.status_code}")

    return payload.get("data")


def is_terminal(detail):
    return detail.get("isTerminal", detail.get("status") in TERMINAL)

전송 상태는 아래 값으로 판단합니다. 종료 상태는 다섯 개이고 성공에 해당하는 값은 완료(2)입니다.

상태 값의미종료
2완료
4오류
5취소
9부분 완료
99실패
1 · 6 · 12 · 13시작·전송 중·동기화 중·수신 중아니오

종료 여부와 성공 여부를 나눠 판단합니다. 부분 완료(9)와 취소(5)도 종료 상태이므로, isTerminal만 보고 성공 처리하면 실패가 성공으로 기록됩니다.

사전 검증

전송 전에 경로 유효성 확인하기

경로가 잘못돼도 전송 생성 자체는 성공합니다. 실패는 실행 시점에 드러나고, 그때는 이미 업무 데이터에 진행 중으로 기록된 뒤입니다.

def validate_paths(source_id, target_id, source_paths, target_path):
    # sourceItems reads filePath, not path
    return api("POST", "/api/transfers/validate-path", {
        "sourceId": source_id,
        "targetId": target_id,
        "sourceItems": [{"filePath": p} for p in source_paths],
        "targetPath": target_path,
    }) or {}


result = validate_paths("device-a", "device-b",
                        ["/data/report.pdf"], "/archive")

if result.get("invalidSourcePaths"):
    raise ValueError(f"missing source paths: {result['invalidSourcePaths']}")

if result.get("validTargetPath") is False:
    raise ValueError("target path not found")
응답 항목내용
validSourcePaths확인된 소스 경로
invalidSourcePaths찾을 수 없는 소스 경로
validTargetPath대상 경로 유효 여부

각 경로는 sourceItemsfilePath에 담아 보냅니다. 사용자가 경로를 직접 입력하는 화면이라면 저장 시점에 이 검증을 적용합니다.

전송 생성

장비와 경로, 처리 기준을 지정해 전송 요청하기

파일 목록을 보낼 때는 sourceItemisDir: false로 명시합니다. sourcePaths는 모든 경로를 폴더로 취급하므로, 파일을 넣으면 서버가 각 파일을 폴더로 스캔하려 해 느려지거나 시간이 초과됩니다.

def create_transfer(source_id, target_id, source_paths, target_path,
                    action="numbering"):
    transfer = api("POST", "/api/transfers/manual", {
        "sourceDevice": source_id,
        "targetDevice": target_id,
        "targetPath": target_path,
        "sourceItem": [{"path": p, "isDir": False} for p in source_paths],
        "sendAllFolder": False,
        "transferOptions": {"target-action": action},
    })

    return transfer["monitorId"]

폴더 단위로 보낼 때는 sourcePathssendAllFolder: True를 씁니다.

api("POST", "/api/transfers/manual", {
    "sourceDevice": source_id,
    "targetDevice": target_id,
    "targetPath": target_path,
    "sourcePaths": ["/data/reports"],
    "sendAllFolder": True,
    "transferOptions": {"target-action": "numbering"},
})

같은 이름의 파일이 대상에 있을 때의 처리는 업무 성격에 따라 정합니다.

동작적합한 업무
numbering번호를 붙여 보존제출본을 회차별로 남기는 업무
overwrite덮어씀최신 상태만 유지하는 업무
nosend이미 있으면 보내지 않고 건너뜀같은 파일을 다시 전송하지 않는 업무

정산 자료를 overwrite로 두면 이전 회차가 사라지므로 기본값을 그대로 쓰지 않고 업무에 맞춰 지정합니다.

nosend으로 건너뛴 파일이 있으면 전송이 성공이 아닌 종료 상태로 끝날 수 있습니다. 완료 판정을 status == 2로만 하면 정상 동작을 실패로 집계하게 되므로, 이 정책을 쓰는 코드에서는 종료 여부와 성공 여부를 따로 다룹니다.

업무 데이터 연결

monitorId를 업무 데이터에 저장해 추적하기

전송 생성이 반환하는 monitorId 하나로 이후 조회와 제어, 재전송이 모두 이뤄집니다. 이 값을 업무 데이터에 저장하지 않으면 이후 추적할 수 없습니다.

def start_order_transfer(order_id, source_id, target_id, paths, target_path):
    validate_paths(source_id, target_id, paths, target_path)

    monitor_id = create_transfer(source_id, target_id, paths, target_path)

    db.execute(
        "UPDATE orders SET monitor_id = %s, transfer_state = %s WHERE id = %s",
        (monitor_id, "transferring", order_id),
    )

    return monitor_id

반대로 monitorId로 업무 데이터를 되찾아야 하는 경우도 있습니다. 운영자가 전송 목록에서 문제를 발견했을 때입니다.

sql
CREATE INDEX idx_orders_monitor_id ON orders (monitor_id);

상태 표시

진행 상태를 화면에 표시하고 종료 여부 판단하기

import time


def describe(monitor_id):
    return api("GET", f"/api/transfers/{monitor_id}")


def wait(monitor_id, timeout=1800, interval=3):
    deadline = time.time() + timeout

    while time.time() < deadline:
        detail = describe(monitor_id)

        if is_terminal(detail):
            return detail

        time.sleep(interval)

    raise TimeoutError(monitor_id)


detail = describe(monitor_id)

print(detail["statusLabel"], detail["percent"], "%")
print(detail["transferSize"], "/", detail["totalSize"])
응답 항목화면 활용
statusLabel상태 표시 문자열
percent진행률
transferSize · totalSize전송량
fileCount · folderCount대상 규모
estimateTime남은 시간
sourceDeviceName · targetDeviceName출발지와 도착지

조회 주기를 짧게 잡으면 요청이 과도해집니다. 화면 표시 목적이라면 3초 정도가 적당합니다.

전송 제어

사용자 요청에 따라 일시정지·재개·취소하기

세 동작 모두 본문 없이 호출합니다. 다만 호출이 성공해도 장비까지 지시가 전달되어야 상태가 바뀌므로, 화면을 즉시 갱신하면 이전 상태가 그대로 보입니다.

PAUSED = 3
RUNNING_STATES = {1, 6, 12, 13}
CANCELLED = 5


def control(monitor_id, action, tries=10):
    api("POST", f"/api/transfers/{monitor_id}/{action}", {})

    expected = {
        "pause": {PAUSED},
        "resume": RUNNING_STATES,
        "cancel": {CANCELLED},
    }[action]

    for _ in range(tries):
        time.sleep(1)
        detail = describe(monitor_id)

        if detail.get("status") in expected:
            return detail

    return describe(monitor_id)

화면에서는 버튼을 즉시 비활성화하고 처리 중을 표시한 뒤, 반영이 확인되면 상태를 갱신하는 방식이 자연스럽습니다.

여러 전송을 한 번에 멈춰야 하는 경우에는 다중 취소를 사용합니다.

result = api("POST", "/api/transfers/bulk-cancel", {"monitorIds": monitor_ids})

print(result.get("cancelled"), result.get("failed"))

이미 종료된 전송은 취소할 대상이 없어 취소에 실패하며 응답의 failed에 담깁니다. 오류가 아니라 정상 응답입니다.

결과 확정

전송 결과를 업무 데이터에 확정하고 실패한 파일 재전송하기

def finalize(order_id, monitor_id):
    detail = describe(monitor_id)

    if not is_terminal(detail):
        return None

    status = detail["status"]
    succeeded = status == STATUS_COMPLETE

    db.execute(
        "UPDATE orders SET transfer_state = %s, transfer_status = %s WHERE id = %s",
        ("done" if succeeded else "failed", status, order_id),
    )

    return succeeded

상태 값을 함께 저장해 두면 나중에 실패 유형을 구분할 수 있습니다. 취소(5)와 실패(99)는 후속 대응이 다릅니다.

일부 파일만 실패한 경우에는 해당 파일만 재전송합니다.

def failed_files(monitor_id):
    result = api("GET", f"/api/transfers/{monitor_id}/files", params={
        "state": "any", "size": 500,
    }) or {}

    return [r for r in (result.get("children") or [])
            if r.get("status") in NOT_SUCCEEDED]


def retry_failed(monitor_id):
    rows = failed_files(monitor_id)

    if not rows:
        return 0

    api("POST", f"/api/transfers/{monitor_id}/retry", {
        "filesRetry": [
            {"filePath": r["sourceFilePath"], "isDir": bool(r.get("isFolder"))}
            for r in rows
        ]
    })

    return len(rows)

각 항목에 sourceFilePath, statusName, errorCode가 있어 어느 파일이 왜 실패했는지 그대로 보여 줄 수 있습니다. 재전송은 전송이 종료된 뒤에만 호출할 수 있습니다.

전송 전체를 다시 실행해야 한다면 이전 실행 정보를 조회해 재실행할 수 있습니다.

config = api("GET", f"/api/transfers/{monitor_id}/replay-data")
api("POST", f"/api/transfers/{monitor_id}/replay", {"action": "replay"})
확인 항목확인 내용
요청검증을 통과한 소스와 대상
실행생성된 monitorId
상태진행률과 종료 여부
결과성공 여부와 상태 값
파일실패한 파일과 오류 코드
후속재전송 또는 재실행 결과