Cloud Search 개요

Cloud Search는 네이버 클라우드 플랫폼의 API Gateway를 통해 API를 제공합니다.
API 인증을 위해서 Access Key, Secret Key가 필요하며,
API Key 생성 및 사용방법은 API Gateway 사용가이드 - API 호출하기을 참고하시기 바랍니다.
Access Key와 Secret Key에 관해서는 공통 가이드 - API 개요을 참고하시기 바랍니다.

Cloud Search는 다양한 API를 제공하고 있으며 Swagger 페이지를 통해서 API 스펙을 확인하고 간단한 테스트를 수행할 수 있습니다. Cloud Search의 Swagger 문서는 아래 과정을 통해서 접근할 수 있습니다.

1. 콘솔 접속
2. Services > API Gateway 서비스 선택
3. Published APIs > CloudSearch > Catalog 선택
4. CloudSearch 선택 후 하단의 API 설명서 선택
   이때 노출되는 화면이 Cloud Search의 Swagger 페이지이며, 페이지 상단에 표시되는 링크인 https://cloudsearch.apigw.ntruss.com/CloudSearch/real이 Cloud Search의 API 주소입니다.

공통 설정

Cloud Search API URL

https://cloudsearch.apigw.ntruss.com/CloudSearch/real

요청 헤더

검색 서비스 생성 예제

본 예제에서는 세계 여러 자동차 모델의 정보를 제공하는 검색 포털 서비스를 만드는 것을 예제로 API 사용법을 설명하겠습니다.
도메인을 생성하기에 앞서, 도메인 생성 시 설정할 검색 설정(Schema)을 정의해보겠습니다.

검색 설정 생성

자동차 모델 각각은 아래의 정보를 가지고 있다고 가정하겠습니다. 검색 엔진에서는 검색의 대상을 나타내는 정보의 묶음을 문서라고 지칭합니다.
즉, 아래 정보의 묶음이 하나의 문서가 됩니다.

• docid : 개별 문서의 key가 되는 항목
• brand : 자동차 브랜드
• name : 자동차명
• price : 가격
• type : 차종

섹션

여기에서 각 항목을 Cloud Search에서는 섹션이라 부릅니다. 그리고, 그 중에 이 문서를 지칭할 수 있는 섹션, 즉 key가 되는
섹션을 메인 섹션이라 부릅니다. 예를 들면, 아래의 json은 하나의 문서이며, 이 문서의 key는 "car-10001"입니다.

{
  "docid": "car-10001",
  "brand": "현대",
  "name": "2018 싼타페",
  "price": "2815",
  "type": "중형"
}

이와 같은 문서를 넣기 위해서는 docid, brand, name, price, type을 섹션으로 추가해야 합니다.

일반 문자열인 경우에는 섹션의 데이터 타입을 생략할 수 있으며, 그렇지 않은 경우에는 float, uint8, uint16, uint32, uint64, int8, int16, int32, int64, string, mstring, muint8, muint32 중의 하나로 지정해야 합니다.

각 섹션에는 다양한 특성을 부여할 수 있는데, price라는 섹션에 대해 dp_price라는 이름을 부여하면 Document 검색의 부가적인 검색 기능에 활용할 수 있습니다.

{
  "docProperties":[
    {
      "type":"uint32",
      "name":"dp_price"
    }
  ],
  "name":"price"
}

색인

자동차를 검색할 때 브랜드명만을 이용해서 검색하는 경우가 있고 브랜드명, 자동차명, 차종을 통틀어서 검색하는 경우가 있습니다. 이와 같이 용도에 따라 검색하는 대상이 되는 섹션이나 검색의 특성을 달리해서 검색하고자 할 때에는 목적에 맞게 각각 색인을 생성해야 합니다. 특별히 이런 구분을 하고 싶지 않다면 모든 섹션을 넣어서 색인을 만들면 됩니다.

아래의 예제는 brand와 name 섹션을 위한 brand_name이라는 색인을 생성합니다.

색인 생성 시 다양한 언어의 형태소 분석기를 설정할 수 있습니다. 본 예제에서는 brand_name 색인에 대해 한글로 형태소 분석기를 지정합니다. 다른 언어의 형태소 분석 지원 여부는 형태소 분석 옵션 조회 - 가능한 언어 목록 통해 확인이 가능합니다.

아래와 같이 섹션과 색인을 정의한 검색 설정, 즉 Schema를 Schema 검증 요청에 보내면 정상 여부를 알 수 있습니다.

{
   "document":{
      "primarySectionName":"docid",
      "sections":[
         {
            "name":"docid"
         },
         {
            "name":"brand"
         },
         {
            "name":"name"
         },
         {
            "docProperties":[
               {
                  "type":"uint32",
                  "name":"dp_price"
               }
            ],
            "name":"price"
         },
         {
            "docProperties":[
               {
                  "type":"string",
                  "name":"dp_type"
               }
            ],
            "name":"type"
         }
      ],
      "indexes":[
         {
            "documentTermWeight":"sum_wgt",
            "buildInfos":[
               {
                  "indexProcessors":[
                     {
                        "type":"hanaterm",
                        "method":"sgmt",
                        "option":"+korea +josacat +eomicat"
                     }
                  ],
                  "sectionTermWeight":"1.0 * stw_2p(tf, 0.5, 0.25, 0., length / 128.0)",
                  "sections":[
                     "brand",
                     "name"
                  ],
                  "name":"index_build"
               }
            ],
            "name":"brand_name"
         }
      ]
   }
}

아래와 같이 valid라는 응답이 오지 않는다면 Schema를 수정해야 합니다.

{
  "status": "valid",
  "message": "OK",
  "response": "{\"status\":{\"code\":0,\"message\":\"ok\"}}\n"
}

위 요청에서 valid라는 응답을 받았다면, Domain 생성 요청 시 작성한 검색 설정을 설정해야 합니다.

도메인 생성

아직 포털 서비스를 개발하는 중이므로 car_dev라는 도메인을 생성하겠습니다. Cloud Search 사용자는
추후 stage, production 환경을 구축할 때에는 car_stage, car_production이라는 도메인을 생성하여 환경을 구분한다면 개발, 테스트, 운영이 용이할 것입니다. Cloud Search에서는 이와 같이 도메인이라는 개념을 이용하여 환경을 구분하고 있습니다.

위에서 사용한 검색 설정과 Domain 생성 API를 참고하여 아래 예시와 같이 json으로 parameter를 정의하여 POST로 /v1/domain를 호출하면 car_dev라는 도메인이 생성됩니다.

{
  "name": "car_dev",
  "type": "small",
  "indexerCount": 1,
  "searcherCount": 1,
  "description": "search engine for cars",
  "schema":{
   "document":{
      "primarySectionName":"docid",
      "sections":[
         {
            "name":"docid"
         },
         {
            "name":"brand"
         },
         {
            "name":"name"
         },
         {
            "docProperties":[
               {
                  "type":"uint32",
                  "name":"dp_price"
               }
            ],
            "name":"price"
         },
         {
            "docProperties":[
               {
                  "type":"string",
                  "name":"dp_type"
               }
            ],
            "name":"type"
         }
      ],
      "indexes":[
         {
            "documentTermWeight":"sum_wgt",
            "buildInfos":[
               {
                  "indexProcessors":[
                     {
                        "type":"hanaterm",
                        "method":"sgmt",
                        "option":"+english +revert +korea +josacat +eomicat"
                     }
                  ],
                  "sectionTermWeight":"1.0 * stw_2p(tf, 0.5, 0.25, 0., length / 128.0)",
                  "sections":[
                     "brand",
                     "name"
                  ],
                  "name":"index_build"
               }
            ],
            "name":"brand_name"
         }
      ]
   }
  }
}

도메인 조회

도메인이 생성된 것을 확인하기 위해 Domain 조회 API를 호출하면 아래와 같은 응답을 받을 수 있습니다.
이미 생성된 다른 도메인이 있다면 여러 개의 도메인에 대한 응답을 받습니다.

{
    "name": "car_dev",
    "description": "search engine for cars",
    "domainStatus": "RUNNING",
    "containerChangeable": "ENABLE",
    "schemaChangeable": "ENABLE",
    "autoCompleteChangeable": "ENABLE",
    "type": "small",
    "indexerCount": 1,
    "searcherCount": 1,
    "schema": {
      "document": {
        "primarySectionName": "docid",
        "sections": [
          {
            "name": "docid"
          },
          {
            "name": "brand"
          },
          {
            "name": "name"
          },
          {
            "docProperties": [
              {
                "type": "uint32",
                "name": "dp_price"
              }
            ],
            "name": "price"
          },
          {
            "docProperties": [
              {
                "type": "string",
                "name": "dp_type"
              }
            ],
            "name": "type"
          }
        ],
        "indexes": [
          {
            "documentTermWeight": "sum_wgt",
            "buildInfos": [
              {
                "indexProcessors": [
                  {
                    "type": "hanaterm",
                    "method": "sgmt",
                    "option": "+english +revert +korea +josacat +eomicat"
                  }
                ],
                "sectionTermWeight": "1.0 * stw_2p(tf, 0.5, 0.25, 0., length / 128.0)",
                "sections": [
                  "brand",
                  "name"
                ],
                "name": "index_build"
              }
            ],
            "name": "brand_name"
          }
        ]
      }
    },
    "autocompleteSchema": null,
    "createdDate": "2019-03-05T08:15:11.587Z",
    "updatedDate": "2019-03-05T08:15:18.000Z"
  }

문서 업로드

새로 생성한 도메인 car_dev에 문서를 추가하겠습니다. 예제 파일 다운로드를 참고하시기 바랍니다.
문서는 필요에 따라 insert, update, upsert, delete할 수 있으며 자세한 사용법은 Document 관리를 참고하시기 바랍니다.
하나의 요청으로 여러 개의 문서를 추가할 수 있으며, insert, update, upsert, delete 요청을 조합하여 한꺼번에 여러 가지 요청을 보낼 수도 있습니다.

Document 관리에 요청을 보내서 문서를 insert, update, upsert, delete할 수 있습니다.

다음은 3개의 문서를 추가하기 위한 요청입니다.
car_dev 도메인에 추가할 것이므로 /v1/domain/car_dev/document/manage를 호출하면 됩니다.

{
  "requests": [
    {
      "type": "insert",
      "key": "car-10001",
      "content": {
        "docid": "car-10001",
        "brand": "현대",
        "name": "2018 싼타페",
        "price": "2815",
        "type": "중형"
      }
    },
    {
      "type": "insert",
      "key": "car-10002",
      "content": {
        "docid": "car-10002",
        "brand": "현대",
        "name": "2018 그랜저",
        "price": "2615",
        "type": "중형"
      }
    },
    {
      "type": "insert",
      "key": "car-3",
      "content": {
        "docid": "car-3",
        "brand": "쉐보레",
        "name": "2018 말리부",
        "price": "2388",
        "type": "중형"
      }
    }
  ]
}

검색

이제 car_dev에 추가된 문서를 검색할 수 있습니다. 검색 API에 대한 상세한 설명은 Document 검색을 참고하시기 바랍니다.

간단히 brand명으로 검색을 해보겠습니다. 아래와 같이 요청을 만든 후 POST로 /v1/domain/car_dev/document/search를 호출하면 됩니다.

{
  "search": {
    "brand_name": {
      "main": {
        "query": "현대"
      }
    }
  }
}

아래와 같은 결과를 얻을 수 있습니다.

{
  "type": "response",
  "version": "1.1.3",
  "status": 200,
  "time_zone": "+09:00",
  "elapsed_time": 0.000787,
  "term": {
    "brand_name": {
      "main": {
        "term_count": 1,
        "term_list": [
          "현대"
        ]
      }
    }
  },
  "result": {
    "start": 1,
    "display": 20,
    "ranking": "clous",
    "sort_by": "qds",
    "total_count": 2,
    "removed_count": 0,
    "item_count": 2,
    "items": [
      {
        "_rank": 1,
        "_key": "car-10001",
        "_qds": 0.8729686141014099,
        "brand": "<b>현대</b>",
        "docid": "car-10001",
        "name": "2018 싼타페",
        "price": 2815,
        "type": "중형"
      },
      {
        "_rank": 2,
        "_key": "car-10002",
        "_qds": 0.8729686141014099,
        "brand": "<b>현대</b>",
        "docid": "car-10002",
        "name": "2018 그랜저",
        "price": 2615,
        "type": "중형"
      }
    ]
  }
}

이에 추가적으로 자동 완성 설정 및 불용어 정책 설정을 지원합니다. 자세한 설명은 해당 페이지를 참조해 주십시오.