Documentation Index

Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt

Use this file to discover all available pages before exploring further.

Cloud Searchの概要

Prev Next

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. コンソールにアクセスし、All Services > API Gatewayサービスを選択
  2. Published APIs > CloudSearch > Catalogを選択
  3. 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

リクエストヘッダ

ヘッダ名 説明
x-ncp-apigw-timestamp 1970年1月1日 00:00:00 協定世界時(UTC)からの経過時間をミリ秒(Millisecond)で表示し、API Gatewayサーバとの時間差が5分以上の場合は無効なリクエストとみなす
x-ncp-apigw-timestamp:{Timestamp}
x-ncp-iam-access-key NAVERクラウドプラットフォームポータルから発行されたAccess Key ID値
x-ncp-iam-access-key:{Sub Account Access Key}
x-ncp-apigw-signature-v2 Access Key ID値とSecret Keyで暗号化した署名
x-ncp-apigw-signature-v2:{API Gateway Signature}
Content-Type Request body content typeは application/jsonに指定
Content-Type: application/json

検索サービスの作成例

本サンプルでは、世界中のさまざまな自動車モデルの情報を提供する検索ポータルサービスの作成を例に、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": "中型"
      }
    ]
  }
}

これに加えて、自動補完の設定およびストップワードポリシーの設定にも対応しています。詳細は、当該ページをご参照ください。

事業者登録番号: 129-86-31394 通信販売業申告番号:第2009-京畿城南-0510号
代表取締役: キム・ユウォン アドレス: 13561 京畿道 城南市 盆唐区 仏亭路6 グリーンファクトリー, 17~26F お客様センターの代表電話: 1544-5876
© NAVER Cloud Corp. All Rights Reserved.