Twinreader Api를 curl 사용하여 호출하는 방법

아티클 관련 제품: TwinReader

이 글을 읽으면

• curl 명령어를 사용하여 문서 분류, 분석 처리 상태, template 결과 추출을 요청하는 방법에 대해 알아보겠습니다.
• 여러 이미지가 존재하는 폴더 내 일부 이미지에 대해서 요청을 할 수 있습니다.
  • 기본 지식
  • 문서 분류 조회 방법
  • 분석 상태 조회 
  • Template 결과 추출 요청 
  • 단일 이미지에 대해 tempate 요청

주의 사항

• 이미 분석을 완료하여 최종 결과가 존재하는 요청의 경우 이전 결과에 overwirte 되기 때문에 별도의 경로에 이전 결과를 저장 후 새로운 분석 요청 할 것을 권장합니다.

기본 지식

• 결과 Directory : Twinreader가 분석을 완료하고 결과 정보를 저장하는 위치입니다.
       ex)  /[Data_home]/Twinreader/output/[이미지 요청 ID]
• 요청 Prameter

문서 분류 조회 방법

    - 문서 분류를 조회하는 방법으로 'analysis/category'을 사용하여 호출합니다. 

1.  요청 code

    curl http:/[Twinreader_server_IP]:[port]/twinreader-mgr-service/api/v1/analysis/category \
   --request POST \
   --header "Content-Type: application/json" \
   --data '{"images": ["image_dir"]}'

2.  요청 Query

   - 문서 이미지가 위치한 directory는 반드시 '/[Data_home]/twinreader/input'의 하위여야 합니다. 

• 문서 이미지가 여러 장일 경우 이미지들이 위치한 directory의 경로를 작성합니다.
• 여러 이미지 중 한 장의 문서 이미지를 요청할 경우 해당 문서 이미지가 위치한 경로를 작성합니다. 

    c. 응답 JSON

{
    "images" : [
        {
              "path" : "[image_path/imageName_1.ext]",
              "pageNumber" : "1",
              "category" : "문서 분류 명",
              "success: true,
              "message" : ""
        },
        {
              "path" : "[image_path/imageName_2.ext]",
              "pageNumber" : "1",
              "category" : "문서 분류 명",
              "success: true,
              "message" : ""
        }
    ]
}

• 여러 장의 이미지 경우 이미지 장마다 상태를 알려줍니다.

분석 상태 조회 

    - Twinreader의 process 진행 상태를 조회할 때 사용하며 'analysis/statusCheck'를 사용하여 호출합니다.

1. 요청 코드

   curl http:/[Twinreader_IP]:[port]/twinreader-mgr-service/api/v1/analysis/statusCheck \
   --header "Content-Type: application/json" \
   --data '{"images": ["image_dir"]}'

2. 요청 Query
   - 문서 분류 조회와 같은 방법으로 요청합니다.
   
   
3. 응답 JSON

   {
       "images" : [
           {
                 "path" : "[image_path/Test_image_name_1.png]",
                 "success: true,
                 "message" : ""
           },
           {
                 "path" : "[image_path/Test_image_name_2.png]",
                 "success: false,
                 "message" : "Analyzing"
           }
       ]
   }    

            - 요청한 시점의 요청 건에 모든 이미지의 상태에 대해 응답합니다. 

       d. 응답 Message
                  - 현재 이미지 분석 상태를 확인 할 수 있습니다.

Template 결과 추출 요청 

• 지정한 template로 분석한 결과를 추출하는 API로 'template/extract/path'를 사용합니다.
• templateName / templateList 구분하여 사용합니다 .

            ① templateName :  분석 데이터에 적용할 template name

            ② templateList : 다중 페이지 처리를 위한 복수 Template name

1. 요청 코드

   curl http:/[Twinreader_server_ip]:[port]/twinreader-mgr-service/api/v1/template/extract/path \
   --request POST \
   --header 'Content-Type: application/json' \
   --data '{"imagePath": "Test_image_sample.jpg"], "templateName": "통원영수증"}'

2. 요청 Query
   - 분석하는 문서 이미지에 따라 templateName / templateList로 구분하여 요청할 수 있습니다.

   {
     "imagePath" : "/[Data_home]/twinreader/input/[image_dir]",
     "templateName" : "지정한 template_name" 
   }
   -------------------------------------------------------------------------
   {
     "imagePath" : "/[Data_home]/twinreader/input/[image_dir]",
     "templateList" : "[지정한 template_name]" 
   }

3. 응답 JSON

   {
       "images" : [
           {
                 "path" : "[/twinreader/output/image_Id/templateJson/Test_image_name_1.json]",
                 "success: true,
                 "message" : ""
           }
       ]
   }    

4. 응답 Message

   Message	Description
   Classification JSON Read Fail	Classification 파일을 읽을 수 없습니다.
   TemplateName is not defined in Classification.json	Classification 파일에 templateName이 정의되지 않았습니다.
   Template Error - Object Create Fail	Template error - 객체 생성에 실패했습니다.

단일 이미지에 대해 tempate 요청

    - Directory 내 하나의 이미지에 대해 template를 요청할 때 사용하는 Api로 'teamplate/templateResult'를 사용합니다.

1.  요청 코드

   curl -G http://10.1.1.70:8080/twinreader-mgr-service/api/v1/template/templateResult --data-urlencode "image=진료비_계산서_type1.jpg"

   
   
2. 요청 Query

   /twinreader-mgr-service/api/v1/template/templateResult?dir=/dir/&image=[image_name.png]

       - 다른 요청들과 달리 'Get' 방식으로 전달됩니다.

   
   
3. 응답 JSON

   {
     result : {
       "Page1" : {
         "metaData" :{
           "imageWidth" : "2341",
                                   "imageHeight" : "1661",
           "template" : "분류문서.json"
         }, {...}, {...},
       }
     },
     message : ""
   }

4. 응답 Message

   Message	Description
   Allow only one or none parameter "dir"	요청 Query에 directory 여러 개 전송한 경우로 없거나 하나만 전송합니다.
   Allow only one parameter "image"	요청 Query에 image 여러 개 전송한 경우로 없거나 하나만 전송합니다.
   Not find directory	분석을 요청한 image가 경로가 없거나 해당 경로가 잘못 입력되었을 경우
   Not find directory or image file	분석 요청한 문서 이미지의 파일 명 / 확장자가 잘못 입력된 경우
   Not find file	분석 파일을 찾지 못한 경우입니다.

마치며

• 전체 Twinreader process가 아닌 일부 process만 사용하는 방법에 대해 알아보았습니다.
• API를 사용하여 directory 내 단일 이미지를 twinreader로 분석 요청하는 방법에 대해 알아보았습니다.