본문 바로 가기

CSE API 매뉴얼

1. 요청과 응답

  • 1) 요청

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

  • 2) 응답

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

  • 3) 사용자 등록

    · ZUM Cloud Search Engine 3.0을 사용하기 위해서는 COLLECTION_IDAPI_KEY를 발급받아야 합니다.
      - 사용자 등록은 ZUM 개발자센터(https://dev.zum.com/search/apply)를 이용합니다.
    · 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 이미지 서버를 통해 검색 결과에 썸네일 다운로드 주소가 표시됩니다.
    • · 검색 결과로 표시되는 썸네일 필드의 형식은 다음과 같습니다.

        "archive_thumbnail_tumbnailSize":"http://thumbsup.zumst.com/cse_collectionId/thumbnailSize/thumbnailKey"
        Ex)"archive_thumbnail_130X130":"http://thumbsup.zumst.com/cse_1234abcd/130X130/0123456789abcdefghij01234567
        89abcdefghij0123456789abcdefghij0123456789abcdefghij"

    • · 썸네일 크기는 기본값이 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 Code HTTP Response Body Description
    200   정상적으로 문서 추가 완료
    400 doc is null doc 파라미터가 없거나 값이 NULL
    doc is empty doc 파라미터가 공백
    invalid encoding 유효하지 않은 인코딩
    doc is invalid - incorrect utf-8 string value doc 내 utf-8로 표현 못하는 문자 포함
    doc json parsing fail json 처리시 발생한 오류
    json contains too many fields doc 내 필드가 최대치인 35개 초과
    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 fieldname is invalid doc 내 fieldname 형식 오류
    document category value is invalid doc 내 카테고리 필드 형식 오류
    document date values is too big doc 내 date 필드 형식 오류
    document date values is invalid
    document string field values is invalid doc 내 contents, icontents 필드 형식 오류
    document score values is invalid doc 내 score 필드 형식 오류
    document icontents_title value is empty doc 내 필수 필드 값이 없거나 NULL
    document icontents_body value is empty
    thumbnail key make fail 썸네일 키 생성 실패
    503 document add process fail 색인 추가 실패
    retrieve user info fail 유저 정보 조회 실패
    document duplication check fail 문서 중복 체크 실패
    retrieve collection info exception 컬렉션 정보 조회 예외 발생
    database exception DB 관련 오류
    500 Occur 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 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 파라미터가 유효하지 않은 값
    return type is invalid 정의된 xml, json 외 다른 결과 포맷
    apikey is null apikey 파라미터가 없거나 값이 NULL
    401 apikey is invalid 유효하지 않은 API key
    404 cid is invalid 유효하지 않은 컬렉션 ID
    406 api call limit reached API 호출 최대치 초과
    503 make search result fail 검색 결과 생성 실패
    retrieve collection info exception 컬렉션 정보 조회 예외 발생
    500 Occur Exception 위에 정의된 예외 이외의 오류 발생

    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 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 document delete process fail 색인 문서 삭제 실패
    retrieve collection info exception 컬렉션 정보 조회 예외 발생
    retrieve user info fail 유저 정보 조회 실패
    500 Occur 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 Code HTTP Response Body Description
    200   문서 업데이트 정상적으로 완료
    400 doc is null doc 파라미터가 없거나 값이 NULL
    doc is empty doc 값이 공백
    invalid encoding doc 파라미터가 유효하지 않은 인코딩
    doc is invalid - incorrect utf-8 string value doc 내 utf-8로 표현 못하는 문자 포함
    doc json parsing fail json 처리시 발생한 오류
    json contains too many fields doc 내 필드가 최대치인 35개 초과
    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 호출 최대치 초과
    document fieldname is invalid doc 내 fieldname 형식 오류
    document category value is invalid doc 내 카테고리 필드 형식 오류
    document date values is too big doc 내 date 필드 형식 오류
    document date values is invalid
    document string field values is invalid doc 내 contents, icontents 필드 형식 오류
    document score values is invalid doc 내 score 필드 형식 오류
    document icontents_title value is empty doc 내 필수 필드 값이 없거나 NULL
    document icontents_body value is empty
    thumbnail key make fail 썸네일 키 생성 실패
    503 document update process fail 색인 업데이트 실패
    retrieve user info fail 유저 정보 조회 실패
    retrieve collection info exception 컬렉션 정보 조회 예외 발생
    database exception DB 관련 오류
    500 Occur 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 Code HTTP Response Body Description
    200   필드 업데이트 정상적으로 완료
    400 fieldname is null fieldname 파라미터가 없거나 값이 NULL
    fieldname is empty fieldname 파라미터 값이 공백
    fieldname is invalid 유효하지 않은 fieldname
    fieldvalue is null fieldvalue 파라미터가 없거나 값이 NULL
    fieldvalue is invalid 유효하지 않은 fieldvalue
    fieldtype is invalid 유효하지 않은 fieldtype
    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 retrieve user info fail 유저 정보 조회 실패
    retrieve collection info exception 컬렉션 정보 조회 예외 발생
    document update field process fail 필드 색인 업데이트 실패
    500 Occur 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 Code HTTP Response Body Description
    200 collection status 컬렉션 색인 정보 요청 완료
    400 apikey is null apikey 파라미터가 없거나 값이 NULL
    401 apikey is invalid 유효하지 않은 API key
    404 cid is invalid 유효하지 않은 컬렉션 ID
    503 make status result fail 상태 정보 조회 실패
    500 Occur Exception 위에 정의된 예외 이외의 오류 발생

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

                                
                                    true or false
                                    1572135
                                
                                

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

                                {
                                    “search_status” : “true or false”,
                                    “document_count” : 1572135
                                }
                                

8. 예제 코드

9. 테스트

  • 1) ZUM 개발자센터를 통한 테스트

    · CSE API는 개발자센터 내 'API 테스트' 페이지를 통해 테스트용 사용자 key를 발급받고 자유롭게 테스트해볼 수 있습니다.
    · ZUM 개발자센터 > API 테스트 링크
      https://dev.zum.com/search/api_test