Cloud Search の概要

Cloud Searchは、NAVERクラウドプラットフォームの 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)を定義してみましょう。

検索設定作成

車両モデルはそれぞれ以下の情報を持っているとします。検索エンジンでは、検索の対象を表す情報の束を 文書 と呼びます。
つまり、以下の情報の束が1つの文書となります。

• docid: 個々の文書の keyとなる項目
• brand: 車ブランド
• name: 車名
• price: 値段
• type: 車種

セクション

ここで各項目を Cloud Searchでは セクション と呼びます。そして、その中でこの文書を指すことができるセクション、つまり keyとなる
セクションを メインセクション と呼びます。例えば、下記の jsonは1つの文書であり、この文書の 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管理をご参照ください。
1つのリクエストで複数のドキュメントを追加でき、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": "中型"
      }
    ]
  }
}

これに加え、自動補完設定とストップワードポリシー設定をサポートします。詳しい説明は、当該ページをご参照ください。