본문 바로 가기

CSE API 매뉴얼

1. 요청과 응답

  • 1) 요청

    · 줌 Cloud Search Engine (이하 CSE) 의 요청은 HTTP 요청방식을 사용합니다.
    · 각 기능에 따라 GET, POST, PUT, DELETE 메소드를 사용합니다. 각 기능에 지정된 메소드만 사용할 수 있습니다.
    · 전달하는 파라미터는 HTML 폼의 기본 인코딩 방식인 application/x-www-form-urlencoded 형태로 인코딩 해야 하며,
      문자열 인코딩은 UTF-8형식을 따릅니다.

  • 2) 응답

    · 줌 CSE API 의 응답은 HTTP 프로토콜 방식을 준수합니다.
    · 성공과 실패는 HTTP 헤더의 Status Code 로 명시합니다. 좀 더 상세한 정보가 필요할 경우 본문에 텍스트로 명시합니다.
      자세한 내용은 각 기능별 응답 항목에서 확인 할 수 있습니다

  • 3) 사용자 등록

    · 줌 CSE API 를 사용하기 위해서는 COLLECTION_IDAPI_KEY 를 발급 받아야 합니다.
      - 사용자 등록은 ‘API 이용 신청’ 을 이용합니다.
    · COLLECTION_ID 는 사용자 별 접근 가능한 문서 콜렉션을 구분합니다.
      - COLLECTION_ID 는 영문과 숫자로 조합된 8자리 문자열로 구성됩니다.
        예) 접근 가능한 콜렉션 리소스 URL -> https://cse.zum.com/v2/abcd1234/docs
    · API_KEY 는 사용자 별 문서 콜렉션에 대한 접근 권한(인증) 확인을 위해 필요합니다.
      - API_KEY 는 md5 hash 형식의 32자리 문자열로 구성됩니다.

2. 문서 추가

  • 1) 문서 추가 기능 설명

    검색 대상이 되는 문서를 추가합니다.

  • 2) 문서 추가 요령 URL(Request URL)

    POST http://cse.zum.com/v2/{collection_id}/docs

    • 호출 메소드 = POST
    • collection_id = 문서콜렉션 식별 값
  • 3) 문서 추가 요청 변수(Request Parameter)
    문서 추가 요청 변수 테이블
    파라메터 필수 설명
    apikey 사용자 인증 키 필수 이용 등록을 통해 받은 apikey를 입력합니다.
    dockey 문서 식별 자 필수 문서를 식별할 수 있는 유일한 값을 입력합니다.
    이 값은 이후 문서에 대한 업데이트, 삭제 시 키 값으로 사용됩니다.
    1024byte까지 입력할 수 있습니다
    force 추가 방식
    - 값 범위=0-1
    - 기본값=0
      문서 추가 방식을 선택합니다.
    0=최대 문서 수 제한을 넘긴 경우 문서를 더 이상 추가하지 않습니다.
    이 경우 실패를 반환합니다.
    1=최대 문서 수 제한을 넘긴 경우 가장 오래된 문서를 삭제하고 추가합니다.
    doc 문서 필수 등록할 문서에 대한 내용을 입력합니다.
    아래 “2.4 문서 추가 요청 변수 상세 (doc)” 항목에 명세 된 프로토콜을
    따라 JSON Object를 사용하여 입력합니다.
    UTF-8 인코딩을 따릅니다.
  • 4) 문서 추가 요청 변수 상세(doc)

    - JSON 형식으로 등록 할 문서의 내용을 전달할 수 있습니다. 사용자가 필요한 필드를 생성하여 사용할 수 있으며, 시스템에서
      미리 정의한 예약 필드가 있습니다.
      예약 필드 중 필수인 필드는 반드시 포함되어야 합니다.
      예약 필드와 사용자 정의 필드 중 icontents 타입(인덱스 문자열타입)의 필드가 반드시 1개이상 포함되어야 합니다.

    - 사용자 필드 생성 규칙
      field_type과 field_name 항목이 있으며 두 항목을 “_”문자로 연결하여 하나의 필드 명으로 사용할 수 있게 됩니다.
      field_type은 아래 표에서 정의된 type(contents|icontents|score)만 사용 가능합니다.
      field_name은 영문과 숫자만 사용 가능합니다.
      시스템에서 미리 정의한 예약 필드가 사용중인 필드 명은 사용할 수 없습니다.

    사용자 필드 생성 규칙 테이블
    형식(format) {field_type}_{field_name}
    항목 상세 field_type=[contents|icontents|score]
    - contents : 문자열타입
    - icontents : 인덱스 문자열타입(문자열타입이며 분석 대상)
    - score : 숫자타입 (정수형 / int64_t)
    field_name = 사용할 필드 명(영문/숫자만 사용)
     

    그 외 이 형식을 따르지 않는 특별한 예약 필드가 있습니다.
    자세한 내용은 아래 "예약 필드" 항목을 참고하세요.

    예시 contents_article → 문자열타입으로 필드 명은 “article”입니다.
    icontents_title → 인덱스 문자열타입으로 필드 명은 “title”입니다.
    score_rate → 숫자타입으로 필드 명은 “rate”입니다.

    - 예약 필드

    문서 추가 요청 변수 테이블
    예약 필드명 Type 필수 설명
    contents_url 문자열   문서 URL
    icontents_title 인덱스 문자열 필수 문서 제목
    icontents_body 인덱스 문자열 필수 문서 본문
    score_regdate 숫자
    UNIXTIMESTAMP
    필수 문서의 등록일 (ex: 1314152189)
    contents_image 문자열   이미지 url (썸네일 생성에 필요)
    categories 카테고리 리스트   카테고리 리스트
    숫자로 구성된 리스트
    ( JSON 숫자 리스트 형식,
    ex: "categories" : [1, 2, 11, 12, 31] )
    • · 위의 표는 요청 변수 doc에 대해 미리 정의된 필드입니다.
    • · 필수 필드는 반드시 입력하여야 하며, 아래 정의된 필드들 외에 필드 생성 규칙에 맞춰 사용자 정의 필드를 생성하여 사용할
        수 있습니다.
    • · 필드는 미리 정의된 필드를 모두 포함하여 최대 35개까지 사용 가능합니다
    • · contents_image 필드는 썸네일을 생성하기 위한 원본 이미지의 URL을 기입하는 필드입니다. 원본 URL을 지정한 썸네일
        크기로 변환하여 ZUM CSE 이미지 서버를 통해 검색 결과에 썸네일 다운로드 주소가 표시됩니다.
    • · 썸네일 크기는 기본값이 130X130 이며, 변경을 원할 경우 계정 생성 요청 시 관리자에게 요청하면 됩니다.
    • · 카테고리 지정 및 필터 기능을 지원하기 위해 특별히 정의된 categories 필드가 존재합니다. JSON의 리스트 형식으로 숫자
        리스트를 지정할 수 있으며 검색 시 포함 또는 제외 필터로 사용할 수 있습니다. 이 필드는 한 문서에 대해 한 번만 사용할 수
        있습니다.

    Example : “doc” 파라미터 JSON

    	{
    		"contents_url":"http://host/sample.html?idx=1",
    		"icontents_title":"예제 타이틀 example title",
    		"icontents_body":"예제 글 내용 example body",
    		"score_regdate":1323838320,
    		"categories":[1,3,7,11,24],
    		"contents_image":"http://host/image.jpg",
    		"score_rate":50
    	}
    	
  • 5) 문서 추가 응답(Response)
    문서 추가 응답 테이블
    HTTP Response Code HTTP Response Body Description
    200   문서 추가 정상적으로 완료
    400 doc is null doc 파라미터가 없거나 값이 NULL
    doc is empty doc 파라미터가 공백
    doc is invalid encoding doc 파라미터가 유효하지 않은 인코딩
    a descriptive error message json 처리시 발생한 오류 설명
    dockey is null dockey 파라미터가 없거나 값이 NULL
    apikey is null apikey 파라미터가 없거나 값이 NULL
    401 apikey is invalid 유효하지 않은 API key
    404 cid is invalid 유효하지 않은 콜렉션 ID
    dockey is invalid 유효하지 않은 dockey
    406 index max reached 색인 가능한 문서량 최대치 초과
    api call limit reached API 호출 최대치 초과
    document is already exists 입력 요청한 문서가 이미 존재
    document is processing 문서 처리 중
    503 database connection fail 데이터베이스 접속 실패
    retrieve user info fail 유저 정보 조회 실패
    document duplication check fail 문서 중복 체크 실패
    retrieve collection info exception 콜렉션 정보 조회 예외 발생
    get new document key fail 입력한 문서에 부여할 새로운 키 발급 실패
    document add task queueing fail 문서 입력 요청을 큐에 넣는 작업이 실패
    document add task queueing exception 문서 입력 요청을 큐에 넣는 작업에서 예외 발생

3. 문서 검색

  • 1) 문서 검색 기능 설명

    검색어가 포함된 문서를 검색합니다. 검색어와 함께 다양한 검색 옵션을 사용할 수 있습니다.

  • 2) 문서 검색 요청 URL(Request URL)

    GET http://search.cse.zum.com/v2/{collection_id}/search/{xml|json}

    • 호출 메소드 = GET
    • collection_id = 문서콜렉션 식별 값
    • xml or json = 결과 포맷 값 (xml or json 선택에 따라 검색 결과 포맷을 결정)
  • 3) 문서 검색 요청 변수(Request Parameter)
    문문서 추가 요청 변수 테이블
    파라메터 필수 설명
    apikey 사용자 인증 키 필수 이용 등록을 통해 받은 apikey를 입력합니다.
    q 검색어
    - 길이제한=1024
    필수 검색어를 입력합니다.
    UTF-8 인코딩을 따릅니다
    start 반환되는 첫 번째 문서 위치
    - 값 범위=0-990
    - 기본값=0
      반환되는 검색 결과의 첫 번째 문서 위치를 지정합니다.
    이 파라미터 값이 990인 경우 “len” 파라미터 값은 10으로
    고정됩니다
    len 반환되는 문서 수
    - 값 범위=10-100
    - 기본값=10
      반환되는 검색 결과의 문서 수를 지정합니다.
    ca 검색 대상 카테고리 목록   검색 대상 카테고리를 지정합니다.
    “,”로 구분하여 복수의 카테고리를 지정 할 수 있습니다
    예) 1,3,5
    ex_ca 검색 제외 카테고리 목록   검색 제외 카테고리를 지정합니다.
    “,”로 구분하며 복수의 카테고리를 지정 할 수 있으며
    최대 10개 지정 가능합니다.
    예) 2,4
    sort 정렬 방식
    - 값범위=0-1
    - 기본값=0
      정렬 방식을 지정합니다.
    - 0=정확도순 정렬 (내림차순)
    - 1=최신순 정렬 (내림차순, score_regdate 필드 기준)
    startdate 검색 기간 시작
    - 값범위=UNIXTIMESTAMP
      기간을 지정하여 검색 할 경우 UNIXTIMESTAMP값으로
    시작 값을 지정합니다. (score_regdate 필드 기준)
    enddate 검색 기간 끝
    값범위=UNIXTIMESTAMP
      기간을 지정하여 검색 할 경우 UNIXTIMESTAMP값으로
    끝 값을 지정합니다. (score_regdate 필드 기준)
  • 4) 문서 검색 응답(Response)
    문서 검색 응답 테이블
    HTTP Response Code HTTP Response Body Description
    200 search result 문서 검색 정상적으로 완료
    (Body에 검색 결과 데이터 반환)
    400 q is null q 파라미터가 없거나 값이 NULL
    q is too long (under 1KB) 입력된 검색어가 최대 길이를 초과
    q is invalid encoding 입력된 검색어가 유효하지 않은 인코딩
    ca parameter is invalid ca 파라미터가 유효하지 않은 값
    ex_ca parameter is invalid ex_ca 파라미터가 유효하지 않은 값
    start parameter is invalid start 파라미터가 유효하지 않은 값
    len parameter is invalid len 파라미터가 유효하지 않은 값
    sort parameter is invalid sort 파라미터가 유효하지 않은 값
    startdate parameter is invalid startdate 파라미터가 유효하지 않은 값
    enddate parameter is invalid enddate 파라미터가 유효하지 않은 값
    401 apikey is invalid 유효하지 않은 API key
    404 cid is invalid 유효하지 않은 콜렉션 ID
    406 api call limit reached API 호출 최대치 초과
    503 make search result fail 검색 결과 생성 실패
    database connection fail 데이터베이스 접속 실패

    Example : 검색 결과 200 응답에 대한 body result (XML)

    	
    	    82
    	    1
    	    0
    	    
    	        
    	            <![CDATA[ABC0001]]>
    	            <![CDATA[http://original.image 350X197]]>
    	            <![CDATA[http://img[1-2].omedia.zumst.com/key/thumb_key]]>
    	            <![CDATA[인사이드ZUM]]>
    	            <![CDATA[http://inside.zum.com/brand/]]>           
    	            1350214841
    	            35
    	            <![CDATA[zum은 포털의 본래적 의미인 관문의 역할에 충실하는 개방형 포털입니다.]]>
    	            <![CDATA[zum이란?]]>
    	            
    	                1
    	                2
    	                11
    	                12             
    	            
    	        
    	    
    	
    	
    	

    Example : 검색 결과 200 응답에 대한 body result (JSON)

    	{
    	    "querytime":82
    	    "start":0,
    	    "numfound":1,
    	    "docs":[
    	    {
    	        "dockey" : "ABC0001",
    	        "archive_image_size_list" : "http://original.image  350X197",
    	        "archive_thumbnail" : "http://img[1-2].omedia.zumst.com/key/thumb_key",
    	        "contents_author" : "인사이드ZUM",
    	        "contents_url" : "http://inside.zum.com/brand/",
    	        "score_regdate" : 1350214841,
    	        "score_view" : 35,
    	        "icontents_body" : "zum은 포털의 본래적 의미인 관문의 역할에 충실하는 
    	개방형 포털입니다.",
    	        "icontents_title" : "zum이란?",
    	        "categories" : [1,2,11,12]
    	    }
    	    ]
    	}
    	

4. 문서 삭제

  • 1) 문서 삭제 기능 설명

    문서 추가 시 입력한 Key 값을 이용하여 문서를 삭제합니다.

  • 2) 문서 삭제 요청 URL(Request URL)

    DELETE http://cse.zum.com/v2/{collection_id}/docs

    • 호출 메소드 = DELETE
    • collection_id = 문서콜렉션 식별 값
  • 3) 문서 삭제 요청 변수(Request Parameter)
    문문서 추가 요청 변수 테이블
    파라메터 필수 설명
    apikey 사용자 인증 키 필수 이용 등록을 통해 받은 apikey를 입력합니다.
    dockey 문서 식별 자 필수 문서를 식별할 수 있는 유일한 값을 입력합니다.
    문서 추가 시 입력한 문서 식별 자입니다.
  • 4) 문서 삭제 요청 응답
    문서 삭제 응답 테이블
    HTTP Response Code HTTP Response Body Description
    200   문서 삭제 정상적으로 완료
    400 dockey is null dockey 파라미터가 없거나 값이 NULL
    apikey is null apikey 파라미터가 없거나 값이 NULL
    401 apikey is invalid 유효하지 않은 API key
    404 cid is invalid 유효하지 않은 콜렉션 ID
    dockey is invalid 유효하지 않은 dockey
    406 api call limit reached API 호출 최대치 초과
    503 retrieve collection info check exception 콜렉션 정보 확인 실패
    database connection fail 데이터베이스 접속 실패
    document delete task queueing fail 문서 삭제 요청을 큐에 넣는 작업 실패
    document delete task queueing exception 문서 삭제 요청을 큐에 넣는 작업에서 예외 발생

5. 문서 업데이트

  • 1) 문서 업데이트 기능 설명

    · 문서의 내용을 업데이트 합니다.
    · 형식은 문서 추가 할 때와 같으며, 변경된 필드만이 아닌 등록되어야 할 필드는 모두 입력하여 요청해야 합니다.
      필수 필드가 빠진 경우 오류 응답을 하지만, 그 외에는 해당 필드가 삭제됩니다

  • 2) 문서 업데이트 요청 URL(Request URL)

    PUT http://cse.zum.com/v2/{collection_id}/docs

    • 호출 메소드 = PUT
    • collection_id = 문서콜렉션 식별 값
  • 3) 문서 업데이트 요청 변수(Request Parameter)
    문서 업데이트 요청 변수 테이블
    파라메터 필수 설명
    apikey 사용자 인증 키 필수 이용 등록을 통해 받은 apikey를 입력합니다.
    doc 문서 필수 등록할 문서에 대한 내용을 입력합니다.
    아래 “2.4 문서 추가 요청 변수 상세 (doc)” 항목에 명세 된 프로토콜을 따라
    JSON Object를 사용하여 입력합니다.
    UTF-8 인코딩을 따릅니다.
    dockey 문서 식별 자 필수 문서를 식별할 수 있는 유일한 값을 입력합니다.
    문서 추가 시 입력한 문서 식별 자입니다.
  • 4) 문서 업데이트 요청 변수 상세(doc)

    doc 파라미터 데이터는 변경되는 필드를 포함하여 기존에 있던 모든 데이터도 함께 입력하여야 합니다.

    Example : “doc” 파라미터 JSON

    	{
    		"contents_url":"http://host/sample.html?idx=1",
    		"icontents_title":"예제 타이틀 example title 업데이트 테스트",
    		"icontents_body":"예제 글 내용 example body 업데이트 테스트",
    		"score_regdate":1323838320,
    		"categories":[1,3,7,11,24],
    		"contents_image":"http://host/image.jpg",
    		"score_view":10,
    		"score_rate":100
    	}
    	
  • 5) 문서 업데이트 응답
    문서 업데이트 응답 테이블
    HTTP Response Code HTTP Response Body Description
    200   문서 업데이트 정상적으로 완료
    400 doc is null doc 파라미터가 없거나 값이 NULL
    doc is empty doc 값이 공백
    doc is invalid encoding doc 파라미터가 유효하지 않은 인코딩
    a descriptive error message json 처리시 발생한 오류 설명
    dockey is null dockey 파라미터가 없거나 값이 NULL
    apikey is null apikey 파라미터가 없거나 값이 NULL
    401 apikey is invalid 유효하지 않은 API key
    404 cid is invalid 유효하지 않은 콜렉션 ID
    dockey is invalid 유효하지 않은 dockey
    406 api call limit reached API 호출 최대치 초과
    503 database connection fail 데이터베이스 접속 실패
    retrieve collection info exception 콜렉션 정보 조회 예외 발생
    document update task queueing
    fail
    문서 업데이트 요청을 큐에 넣는 작업이 실패
    document update task queueing
    exception
    문서 업데이트 요청을 큐에 넣는 작업에서
    예외 발생

6. 필드 업데이트

  • 1) 필드 업데이트 기능 설명

    · 숫자형식(score)으로 지정된 필드에 대한 개별 업데이트를 쉽게 제공하는 기능입니다.
    · 간단히 1개의 필드에 대해 업데이트가 필요할 때 JSON방식의 전체 문서 정보를 보내지 않고 간단히 업데이트가 가능합니다

  • 2) 필드 업데이트 요청 URL(Request URL)

    PUT http://cse.zum.com/v2/{collection_id}/docs/fields

    • 호출 메소드 = PUT
    • collection_id = 문서콜렉션 식별 값
  • 3) 필드 업데이트 요청 변수(Request Parameter)
    필드 업데이트 요청 변수 테이블
    파라메터 필수 설명
    apikey 사용자 인증 키 필수 이용 등록을 통해 받은 apikey를 입력합니다.
    dockey 문서 식별 자 필수 문서를 식별할 수 있는 유일한 값을 입력합니다.
    문서 추가 시 입력한 문서 식별 자입니다.
    fieldname 필드 이름 필수 필드 이름을 입력합니다.
    fieldvalue 필드 값 필수 필드 값(숫자)을 입력합니다
  • 4) 필드 업데이트 응답
    필드 업데이트 응답 테이블
    HTTP Response Code HTTP Response Body Description
    200   필드 업데이트 정상적으로 완료
    400 fieldname is null fieldname 파라미터가 없거나 값이 NULL
    fieldname is empty fieldname 파라미터 값이 공백
    fieldname is invalid(desc.) 유효하지 않은 fieldname (설명)
    fieldvalue is null fieldvalue 파라미터가 없거나 값이 NULL
    fieldvalue is invalid 유효하지 않은 fieldvalue
    dockey is null dockey 파라미터가 없거나 값이 NULL
    apikey is null apikey 파라미터가 없거나 값이 NULL
    401 apikey is invalid 유효하지 않은 apikey
    404 cid is invalid 유효하지 않은 콜렉션 ID
    dockey is empty dockey 값이 공백
    dockey is invalid 유효하지 않은 dockey
    406 api call limit reached API 호출 최대치 초과
    503 database connection fail 데이터베이스 접속 실패
    retrieve collection info exception 콜렉션 정보 조회 예외 발생
    field update task queueing fail 필드 업데이트 요청을 큐에 넣는 작업이 실패
    field update task queueing
    exception
    필드 업데이트 요청을 큐에 넣는 작업에서
    예외 발생

7. 색인 정보

  • 1) 색인 정보 기능 설명

    사용자 별 검색 서버 사용 상태 등의 정보를 확인하는 기능입니다. 검색 가능 여부와 입력되어 있는 문서수를 확인할 수 있습니다.

  • 2) 색인 정보 요청 URL(Request URL)

    GET http://cse.zum.com/v2/{collection_id}/status/{xml|json}

    • 호출 메소드 = GET
    • collection_id = 문서콜렉션 식별 값
  • 3) 색인 정보 요청 변수(Request Parameter)
    필드 업데이트 요청 변수 테이블
    파라메터 필수 설명
    apikey 사용자 인증 키 필수 이용 등록을 통해 받은 apikey를 입력합니다.
  • 4) 색인 정보 응답
    필드 업데이트 응답 테이블
    HTTP Response Code HTTP Response Body Description
    200 collection status 콜렉션 색인 정보 요청 완료
    401 apikey is invalid 유효하지 않은 API key
    404 cid is invalid 유효하지 않은 콜렉션 ID
    503 database connection fail 데이터베이스 접속 실패

    Example : 색인 정보 200 응답에 대한 body result (XML)

    	                                    
    	                                        true or false
    	                                        1572135
    	                                    
    	                                    

    Example : 색인 정보 200 응답에 대한 body result (JSON)

    	                                    {
    	                                        "search_status" : "true or false",
    	                                        "document_count" : 1572135
    	                                    }