Twinreader API 사용하기 2

작성자 이호영 수정일 2023-01-06 11:28

#Twinreader2.0, #API, #이미지분석요청ID, #분석상태체크, #DB정보삭제

아티클 관련 제품: Twinreader2.0

들어가며

기존에 분석 결과가 존재하는 경우 API를 통해 결과가 추출될 때 기존 결과에 overwrite 되기 때문에 별도 경로에 옮긴 후 사용하시기 바랍니다.
Twinreader API 사용하기 1에 이어 API의 종류 중 아래의 3개 항목에 대해 알아보겠습니다.

API 사용 방법

각 요청에 맞는 URL과 data를 넣어서 curl 명령어를 사용하여 호출합니다.

Curl 명령어 전송하기

curl [Server IP]:port / [API URL] \
-- header "Content-Type: application/json" \
--data {
[요청 구조에서 필수 / 선택으로 정의되어 있는 Parameter]
}

이미지 분석 요청 ID 사용

이미지를 png로 변환 후 요청 ID를 통해 callback 처리 가능한 분석 요청 API입니다.

API 형식

Protocol	전송방식	Header	URL
http	Post	{"Content-Type": "application/json"}	/twinreader-mgr-service/api/v1/analysis/inference/reqId
요청 코드
curl http://Server_IP_주소/twinreader-mgr-service/api/v1/analysis/inference/reqId \ --request POST \ --header "Content-Type: application/json" \ --data '{"requestId":"test_request_id", "images": ["/Image_Sample.jpg"]}'

Protocol

전송방식

Header

URL

http

Post

{"Content-Type": "application/json"}

/twinreader-mgr-service/api/v1/analysis/inference/reqId

요청 코드

curl http://Server_IP_주소/twinreader-mgr-service/api/v1/analysis/inference/reqId \

--request POST \

--header "Content-Type: application/json" \

--data '{"requestId":"test_request_id", "images": ["/Image_Sample.jpg"]}'

요청 구조

필수 / 선택	Parameter	타입	설명
필수	requestId	string	분석 요청 구분 ID
선택	callbackUrl	string	분석 완료 시 호출 될 API 주소
			callback methods		POST
			callback body 정보 {
				requestId	분석 요청 ID
				totalCount	요청 이미지 수
				successCount	분석 성공 수
				successPathList	분석 성공 이미지 경로 (Array)
				failInfoList	분석 실패 정보 {
					imagePath : 이미지 경로
					}
				imageName	Image_name_message(실패 사유)
			}
필수	images	Array	이미지 또는 이미지들이 담긴 디렉토리

요청JSON 예시

{
    requestId: "test1",
    callbackUrl: "http://10.222.12.31:80/callback"
    images: [
        "/image_sample.jpg"
    ]
}

결과 구조

Parameter	타입	설명
result	Boolean	요청 성공 여부
message	String \| null	error message

결과 JSON 예시

// 성공시
{
    success: true,
    message: null,
}

//실패시
{
    success: false,
    message: "not exist file or directory || path: test1/image_sample.jpg, test1/",
}

결과 message 종류

Error Message	설명
not exist file or directory \|\| path: dir/테스트.jpg, dir	존재하지 않는 파일/디렉토리를 요청
empty directory can't be converted \|\| path: dir/	파일이 들어있지 않은 빈디렉토리를 요청
requestId empty!	요청 ID 없이 분석 요청
file have an unprocessable extension \|\| path: dir/테스트.avi, dir/테스트.exe	다루지 못하는 확장자 요청

분석 상태 체크 조회

이미지 분석 진행 상태 체크를 하기 위한 API 입니다.

API 형식

Protocol	방식	Header	URL
http	Post	{"Content-Type": "application/json"}	/twinreader-mgr-service/api/v1/analysis/statusCheck
요청 코드
curl http://Server_IP_주소/twinreader-mgr-service/api/v1/analysis/statusCheck \ --header "Content-Type: application/json" \ --data '{"images": ["/Image_Sample.jpg"]}'

Protocol

방식

Header

URL

http

Post

{"Content-Type": "application/json"}

/twinreader-mgr-service/api/v1/analysis/statusCheck

요청 코드

curl http://Server_IP_주소/twinreader-mgr-service/api/v1/analysis/statusCheck \

--header "Content-Type: application/json" \

--data '{"images": ["/Image_Sample.jpg"]}'

요청 구조

필수 / 선택	Parameter	타입	설명
필수	images	Array	디렉토리 인 경우 바로 하위 이미지만 검사

요청JSON 예시

{
    images: [
        "requestImageDir/"
    ]
}

결과 구조

Parameter		타입	설명
1	2	타입	설명
images		Array
	path	String	분석결과 디렉토리, 파일 경로
	success	Boolean	분석 성공(완료) 여부 값 true : 분석 성공 false : 분석 진행 중 or 분석 실패
	message	String	false시 상세 상태 메시지

결과 JSON 예시

//성공시
{
    "path": "/testdir/sampleImage.jpg",
    "success": true,
    "message": ""
}

//실패 or 진행 중
{
    "path": "/dir/진료비영수증.png",
    "success": false,
    "message": "Template Error."
}

결과 message 종류

Error Message	설명
Analyzing	분석 중
Analyzing. Waiting for Another page or Templates.	분석 중이며 다른 페이지의 분석이 기다리거나 템플릿 수행 중
Converting File.	파일 변환 중
File conversion error.	파일 변환 에러
Analysis Error.	model 분석 에러
Plugin Error.	플러그인 에러
Unregistered Templates Error.	템플릿에서 알 수 없는 에러
Other Document Classification Error.	classification에 정의되지 않은 문서 분류
Classification Json Parse Error.	classification 파일을 읽을 수 없음
Templates Json Parse Error.	템플릿 파일을 읽을 수 없음
Common Error	그 밖의 에러

DB 삭제

이미지 분석 DB 정보를 삭제하는 API 입니다.

API 형식

Protocol	전송방식	Header	URL
http	Delete	{"Content-Type": "application/json"}	/twinreader-mgr-service/api/v1/analysis/deleteImageData
요청 코드
curl http://Server_IP_주소/twinreader-mgr-service/api/v1/analysis/deleteImageData \ --request Delete \ --header "Content-Type: application/json" \ --data '{"images": ["/Image_Sample.jpg"]}'

Protocol

전송방식

Header

URL

http

Delete

{"Content-Type": "application/json"}

/twinreader-mgr-service/api/v1/analysis/deleteImageData

요청 코드

curl http://Server_IP_주소/twinreader-mgr-service/api/v1/analysis/deleteImageData \

--request Delete \

--header "Content-Type: application/json" \

--data '{"images": ["/Image_Sample.jpg"]}'

요청 구조

필수 / 선택	Parameter	타입	설명
필수	images	Array	삭제할 이미지 경로

요청JSON 예시

{
    images: [
        "requestImageDir/"
    ]
}

결과 구조

Parameter		타입	설명
1	2	타입	설명
images		Array
	success	Boolean	DB 정보 삭제 성공 / 실패
	count	number	삭제된 DB row수
	message	String	false : Failed to delete image data true : ""

결과 JSON 예시

// 성공시
{
    "success": true,
    "count": 3,
    "message": ""
}

// 실패시
{
    "success": false,
    "count": 0,
    "message": '' Failed to delete image data."
}

마무리

Twinreader API 중 이미지 분석 요청 ID 사용, 분석 문서 분류 조회, DB 정보 삭제에 대해 알아보았습니다.
Template 결과에 대한 API는 Twinreader API 사용하기 3에서 다루어보겠습니다.