원문·extra 옵션

기본 결과는 이름이 붙은 필드뿐입니다. 두 옵션은 필요할 때만 켜며, 켜도 다른 필드는 바뀌지 않습니다.

요청 파라미터

이름은 Python 기준이고 Java와 Node.js는 camelCase입니다. Node.js는 마지막 인자의 객체로 넘깁니다 ({ includeRaw: true }).

파라미터	타입	필수	기본값	설명
include_raw	boolean	아니오	false	학교 응답 원문을 결과에 담음 (raw_html, raw_json). Java는 authenticateWithRaw, authenticateWithDHCRaw, authenticateWithSISRaw
include_extra	boolean	아니오	false	이름 붙지 않은 나머지 SIS 필드를 extra 맵에 담음. 통합·SIS 인증만. Java는 authenticate(id, pw, false, true)의 마지막 인자

응답 데이터 구조

옵션을 켜면 아래 필드가 채워집니다. 예시는 Python의 snake_case 이름이고 Java와 Node.js는 camelCase(rawHtml, rawJson)입니다.

{
  "student_id": "20000000",
  "name": "홍길동",
  "extra": { "dm_UserInfoSch.FIELD_NAME": "값" },
  "raw_html": "<html>...</html>",
  "raw_json": "{...}"
}

필드	타입	채워지는 조건
raw_html	string 또는 null	원문 옵션을 켰을 때 DHC 페이지. DHC·통합 결과
raw_json	string 또는 null	원문 옵션을 켰을 때 SIS initUserInfo 응답. SIS·통합 결과. SIS가 실패했으면 null
extra	맵 또는 null	extra 옵션을 켰을 때. 아니면 null. DHC 결과에는 없음

원문 옵션

학교가 보낸 응답을 그대로 결과에 담습니다. 디버깅과 파서 점검용입니다.

• 통합 결과는 raw_html과 raw_json이 모두, DHC 결과는 raw_html만, SIS 결과는 raw_json만 채워집니다.
• 추가 요청은 없습니다. 이미 받은 응답을 보관할 뿐입니다.

원문을 외부로 내보내지 마세요

SIS 원문에는 세션 식별자로 보이는 값, 접속 IP, 접속 시각이 들어 있습니다. 외부 클라이언트에 그대로 내려주지 마세요.

extra 옵션

이름 붙인 필드 말고 학교가 주는 나머지 SIS 필드를 {"데이터셋.필드": "값"} 맵으로 받습니다. 학교가 필드를 더해도 새 릴리스 없이 접근할 수 있게 하는 통로입니다.

• 대상 데이터셋은 dm_UserInfoSch, dm_UserInfoGam, dm_UserInfo의 스칼라 필드입니다.

항상 제외되는 키

spec/contract.json의 extraExcludedKeyPattern에 걸리는 키(대소문자 무시)는 extra에 들어가지 않습니다.

(PWD|PASS|JUMIN|RRN|RESI|SSN|BANK|ACNT|ACCT|ACCOUNT|ADDR|ZIP|POST|ALIAS|SESS|TOKEN|SECRET|BIRTH|BRTH|VALID|PHONE|TEL|MOBILE|MAIL|LOGIN|RUNNING|(^|_)IP($|_)|_YN$)

세션 값, 접속 IP, 비밀번호와 계정 상태 플래그, 주민번호, 계좌, 주소, 직원 이름 계열(ALIAS), 전화, 메일, 생년월일 등이 여기에 해당합니다. 다만 이름 패턴으로 거르는 최선의 필터입니다. extra를 외부 클라이언트에 그대로 내려주지 말고, 필요한 키만 골라 쓰세요.

호환성 보장 범위 밖

원문의 키와 구조, extra의 키와 값은 학교가 바꾸면 달라집니다. 앱의 핵심 로직을 여기에 걸지 마세요. 안정적인 접근은 결과 필드의 이름 붙은 필드로 하세요. 정책은 API 안정성에 있습니다.

예시 코드

원문 옵션

Java

SejongAuthResult result = sejongAuthEngine.authenticateWithRaw(studentId, password);
String html = result.getRawHtml();   // DHC 원문
String json = result.getRawJson();   // SIS 원문 (SIS 실패 시 null)

sejongAuthEngine.authenticateWithDHCRaw(studentId, password);   // DHC 결과 + rawHtml
sejongAuthEngine.authenticateWithSISRaw(studentId, password);   // SIS 결과 + rawJson

Python

result = authenticate(student_id, password, include_raw=True)
html, json_text = result.raw_html, result.raw_json

authenticate_dhc(student_id, password, include_raw=True)   # DHC 결과 + raw_html
authenticate_sis(student_id, password, include_raw=True)   # SIS 결과 + raw_json

Node.js

const result = await authenticate(studentId, password, { includeRaw: true });
const { rawHtml, rawJson } = result;

await authenticateDhc(studentId, password, { includeRaw: true });   // DHC 결과 + rawHtml
await authenticateSis(studentId, password, { includeRaw: true });   // SIS 결과 + rawJson

extra 옵션

Java

// 인자: 학번, 비밀번호, 원문 포함 여부, extra 포함 여부
SejongAuthResult result = sejongAuthEngine.authenticate(studentId, password, false, true);
Map<String, String> extra = result.getExtra();

Python

result = authenticate(student_id, password, include_extra=True)
extra = result.extra   # {"데이터셋.필드": "값"}

Node.js

const result = await authenticate(studentId, password, { includeExtra: true });
const { extra } = result;   // { '데이터셋.필드': '값' }