API로 결과, 대화 기록, 녹음 가져오기

Results API는 읽기 전용 HTTP API예요. 인터뷰가 끝난 뒤 기관이 묻는 질문에 답해요. 학생마다 결과가 무엇이었는지, 무슨 말을 했는지, 정책이 허용한다면 음성은 어땠는지요. 보고서에 보이는 것과 같은 데이터를 JSON으로 주기 때문에 배지 플랫폼이나 기록 시스템이 누가 내보내기를 누르지 않아도 사본을 유지할 수 있어요.

1. 1

   설정에서 API 접근을 열고 키를 만드세요. 키를 사용할 시스템 이름으로 짓고 읽을 범위를 고르세요. 결과는 항상, 대화 기록과 녹음은 그 시스템에 꼭 필요할 때만이에요. 키는 한 번만 보여주니 바로 그 시스템에 복사하세요.

2. 2

   모든 요청에 키를 bearer 토큰으로 보내세요. Authorization: Bearer viva_sk_… 형식이에요. GET https://www.vivaproof.com/api/v1/me 로 테스트하면 키 이름, 범위, 닿는 수업 수를 돌려줘요.

3. 3

   GET /api/v1/assignments 로 과제 목록을 받고, GET /api/v1/assignments/{id}/results 로 결과를 가져오세요. 각 행이 인터뷰 세션 하나예요. 학생, 상태, 무결성 판정, 점수 또는 항목별 판정, 교수자 성적, 그리고 키가 허용하면 대화 기록과 녹음 링크가 담겨요.

4. 4

   completed_since=<ISO 시각> 으로 가볍게 폴링하세요. 그 시각 이후에 완료된 세션만 돌아와요. 응답의 next_cursor 를 cursor 로 다시 보내면 되고, null이 되면 끝이에요.

결과의 모양

두 기준표 방식에 같은 모양을 써요. 도달 / 미도달 기준표에서는 rubric.mode 가 "competency" 이고 항목마다 판정(met, not_yet, not_assessed), 확신 정도, Viva가 인용한 근거가 담겨요. 교수자의 결정이 있으면 판정을 대체하고 누가 결정했는지 표시돼요. 점수 기준표에서는 항목마다 획득 점수와 만점, 제안 성적이 담기고, scores 에는 실제 총점이 담겨요. 교수자가 조정했다면 조정한 값이에요. 중단된 세션은 상태가 "abandoned" 이고 점수가 없어요. 채점되지 않은 것을 0점으로 보고하는 일은 없어요.

• GET /api/v1/sessions/{id} 는 결과 하나를 돌려주고, 키가 허용하면 대화 기록도 함께 담아요. GET /api/v1/sessions/{id}/transcript 는 발화를 JSON으로, format=text 를 붙이면 일반 텍스트로 줘요.
• GET /api/v1/sessions/{id}/recording 은 10분 동안만 재생되는 링크로 보내고 그 뒤에는 만료돼요. 녹음을 켜고 만든 키가 필요해요. 녹음을 읽을 때마다 설정의 요청 기록에 남으니 무엇이 나갔는지 언제든 볼 수 있어요.
• 개인 키는 본인이 담당, 공동 담당, 조교, 채점자로 속한 수업에 닿아요. 학교 관리자는 학교의 모든 수업에 닿는 학교 전체 키를 만들 수 있어요.
• 키는 분당 120회로 제한돼요. 키를 폐기하면 바로 멈추고 기록은 남아요.