Config API

개요

Config API는 Caffeine의 태그(Tag) 설정을 조회하고 일괄 업데이트하는 기능을 제공합니다. 엑셀 Import/Export 기능과 연동하여 대량의 태그 설정을 효율적으로 관리할 수 있습니다.

기본 정보

항목	값
기본 경로	/api/v1.0/config
인증	불필요
버전	v1.0

엔드포인트 요약

메서드	경로	설명
GET	/api/v1.0/config/tags	전체 태그 설정 조회 (Excel Export용)
POST	/api/v1.0/config/tags/bulk	태그 설정 일괄 업데이트 (Excel Import용)

상세 엔드포인트

GET /api/v1.0/config/tags

전체 태그 설정을 조회합니다. 엑셀 Export 기능을 위해 사용됩니다.

요청

파라미터 없음

응답

[
  {
    "tagId": "Motor.Current",
    "driverId": "Equipment-01",
    "address": "DB1.DBD0",
    "dataType": "Float",
    "unit": "A",
    "description": "Motor current",
    "minValue": 0.0,
    "maxValue": 100.0,
    "scalingFactor": 1.0,
    "offset": 0.0
  },
  {
    "tagId": "Temp.Sensor1",
    "driverId": "Equipment-01",
    "address": "DB1.DBD4",
    "dataType": "Float",
    "unit": "°C",
    "description": "Temperature sensor 1",
    "minValue": -50.0,
    "maxValue": 200.0,
    "scalingFactor": 1.0,
    "offset": 0.0
  }
]

응답 코드

코드	설명
200	성공 (빈 배열도 200 반환)
500	서버 내부 오류

---

POST /api/v1.0/config/tags/bulk

태그 설정을 일괄 업데이트합니다. 엑셀 Import 기능을 위해 사용됩니다.

특징:

• Hot Reload: 메모리에 즉시 반영되어 재시작 없이 적용
• 파일 영구화: equipment_model.json 파일에 저장되어 재시작 시에도 유지
• 동시성 제어: SemaphoreSlim을 통한 파일 쓰기 충돌 방지

요청 본문

[
  {
    "tagId": "Motor.Current",
    "driverId": "Equipment-01",
    "address": "DB1.DBD0",
    "dataType": "Float",
    "unit": "A",
    "description": "Motor current",
    "minValue": 0.0,
    "maxValue": 100.0,
    "scalingFactor": 1.0,
    "offset": 0.0
  },
  {
    "tagId": "Motor.Voltage",
    "driverId": "Equipment-01",
    "address": "DB1.DBD8",
    "dataType": "Float",
    "unit": "V",
    "description": "Motor voltage",
    "minValue": 0.0,
    "maxValue": 500.0,
    "scalingFactor": 1.0,
    "offset": 0.0
  }
]

응답

{
  "count": 2,
  "message": "Applied to Memory & Disk"
}

응답 코드

코드	설명
200	태그 업데이트 성공
400	잘못된 요청 (태그 목록 비어있음)
500	서버 내부 오류 (파일 쓰기 실패)

DTO 정의

TagConfig

속성	타입	설명
tagId	string	태그 고유 식별자 (예: "Motor.Current")
driverId	string	드라이버 ID (장비 식별자)
address	string	PLC 주소 (예: "DB1.DBD0")
dataType	string	데이터 타입 (Bool, Int, Float, String)
unit	string	단위 (A, °C, kW 등)
description	string	태그 설명
minValue	double	최솟값 (유효 범위)
maxValue	double	최댓값 (유효 범위)
scalingFactor	double	스케일링 계수 (기본값: 1.0)
offset	double	오프셋 (기본값: 0.0)

설정 파일 위치

태그 설정은 다음 파일에 저장됩니다:

• 환경변수: CAFFEINE_MODEL_PATH 설정 시 해당 경로
• 기본값: {ContentRootPath}/config/equipment_model.json

파일 형식 (equipment_model.json):

{
  "modelName": "Updated-Model",
  "version": "1.1",
  "variables": [
    {
      "tagId": "Motor.Current",
      "driverId": "Equipment-01",
      "address": "DB1.DBD0",
      "dataType": "Float",
      "unit": "A",
      "description": "Motor current",
      "minValue": 0.0,
      "maxValue": 100.0,
      "scalingFactor": 1.0,
      "offset": 0.0
    }
  ]
}

사용 예제

C# (HttpClient)

using System.Net.Http.Json;

var client = new HttpClient { BaseAddress = new Uri("https://localhost:5001") };

// 전체 태그 설정 조회 (Excel Export)
var tags = await client.GetFromJsonAsync<List<TagConfig>>("/api/v1.0/config/tags");
Console.WriteLine($"Total Tags: {tags.Count}");

// 태그 설정 일괄 업데이트 (Excel Import)
var updatedTags = new List<TagConfig>
{
    new TagConfig
    {
        TagId = "Motor.Current",
        DriverId = "Equipment-01",
        Address = "DB1.DBD0",
        DataType = "Float",
        Unit = "A",
        Description = "Motor current (updated)",
        MinValue = 0.0,
        MaxValue = 100.0,
        ScalingFactor = 1.0,
        Offset = 0.0
    }
};

var response = await client.PostAsJsonAsync("/api/v1.0/config/tags/bulk", updatedTags);
if (response.IsSuccessStatusCode)
{
    var result = await response.Content.ReadFromJsonAsync<BulkUpdateResponse>();
    Console.WriteLine($"Updated {result.Count} tags: {result.Message}");
}

curl

# 전체 태그 설정 조회
curl -X GET "https://localhost:5001/api/v1.0/config/tags" > tags.json

# 태그 설정 일괄 업데이트
curl -X POST "https://localhost:5001/api/v1.0/config/tags/bulk" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "tagId": "Motor.Current",
      "driverId": "Equipment-01",
      "address": "DB1.DBD0",
      "dataType": "Float",
      "unit": "A",
      "description": "Motor current",
      "minValue": 0.0,
      "maxValue": 100.0,
      "scalingFactor": 1.0,
      "offset": 0.0
    }
  ]'

JavaScript (Fetch)

// 전체 태그 설정 조회
const tags = await fetch('https://localhost:5001/api/v1.0/config/tags')
  .then(res => res.json());

console.log(`Total Tags: ${tags.length}`);

// 태그 설정 일괄 업데이트
const updatedTags = [
  {
    tagId: 'Motor.Current',
    driverId: 'Equipment-01',
    address: 'DB1.DBD0',
    dataType: 'Float',
    unit: 'A',
    description: 'Motor current (updated)',
    minValue: 0.0,
    maxValue: 100.0,
    scalingFactor: 1.0,
    offset: 0.0
  }
];

const result = await fetch('https://localhost:5001/api/v1.0/config/tags/bulk', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(updatedTags)
}).then(res => res.json());

console.log(`Updated ${result.count} tags: ${result.message}`);

Excel Import/Export 워크플로우

Export 워크플로우

Import 워크플로우

동시성 제어

Config API는 파일 쓰기 충돌을 방지하기 위해 SemaphoreSlim을 사용합니다:

private static readonly SemaphoreSlim _fileLock = new SemaphoreSlim(1, 1);

await _fileLock.WaitAsync();
try
{
    // 메모리 업데이트
    _tagManager.UpdateTags(newTags);

    // 파일 저장
    await File.WriteAllTextAsync(filePath, json);
}
finally
{
    _fileLock.Release();
}

주의사항

• 태그 설정 업데이트는 즉시 적용되지만, 드라이버 재시작이 필요한 경우도 있습니다.
• 대량의 태그를 업데이트할 때는 네트워크 타임아웃에 주의하세요 (권장: 1000개 이하/요청).
• equipment_model.json 파일이 손상되면 시스템 기동이 실패할 수 있으므로, 백업을 권장합니다.
• 동일한 tagId가 중복되면 마지막 항목으로 덮어씁니다.

환경변수 설정

태그 설정 파일 경로를 변경하려면 환경변수를 설정하세요:

# Linux/Mac
export CAFFEINE_MODEL_PATH=/opt/caffeine/config/equipment_model.json

# Windows
set CAFFEINE_MODEL_PATH=C:\Caffeine\config\equipment_model.json

# Docker
docker run -e CAFFEINE_MODEL_PATH=/data/equipment_model.json nexcode/caffeine-engine

관련 API

• Driver API - 드라이버 설정 관리
• License API - 태그 개수 제한 확인