---
title: "Cloud Searchの概要"
slug: "analytics-cloudsearch"
updated: 2026-09-17T09:57:29Z
published: 2026-09-17T09:57:29Z
canonical: "api.ncloud-docs.com/analytics-cloudsearch"
---
> ## 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の概要
Cloud SearchはNAVERクラウドプラットフォームのAPI Gatewayを通じてAPIを提供します。 API認証のためにはAccess KeyとSecret Keyが必要であり、 API Keyの作成および使用方法は[API Gatewayご利用ガイド - APIの呼び出し](https://guide.ncloud-docs.com/docs/ja/apigw-apigw-2-5)をご参照ください。 Access KeyとSecret Keyについては[共通ガイド - APIの概要](/docs/ja/common-ncpapi)を参考にしてください。
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の検索](/docs/ja/analytics-cloudsearch-searchdocument)の付加的な検索機能に活用できます。
```
{
"docProperties":[
{
"type":"uint32",
"name":"dp_price"
}
],
"name":"price"
}
```
### インデックス
自動車を検索する際、ブランド名のみを用いて検索する場合もあれば、ブランド名、自動車名、車種をまとめて検索する場合もあります。このように用途に応じて検索対象となるセクションや検索特性を変えて検索したい場合は、目的に合わせてそれぞれインデックスを作成する必要があります。特にこのような区別を設けない場合は、すべてのセクションを含めてインデックスを作成します。
以下のサンプルでは、brandと nameセクションのための brand_nameというインデックスを作成します。
インデックス作成時には、さまざまな言語の形態素解析ツールを設定できます。本サンプルでは、brand_nameインデックスに対して韓国語の形態素解析ツールを指定します。その他の言語の形態素解析のサポート状況については、[形態素解析オプションの照会 - 利用可能な言語リスト](/docs/ja/analytics-cloudsearch-gettokenizerlist)より確認できます。
以下のようにセクションとインデックスを定義した検索設定、すなわち[Schema](/docs/ja/common-apidatatype-csschema)を[Schemaの検証](/docs/ja/analytics-cloudsearch-checkschemavalidator)リクエストに送信すると、正常かどうかを確認できます。
```
{
"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の作成](/docs/ja/analytics-cloudsearch-createdomain)リクエスト時に作成した検索設定を指定します。
## ドメインの作成
現在はポータルサービスを開発中の段階であるため、car_devというドメインを作成します。Cloud Searchのユーザーが 今後 stage、production環境を構築する際には、car_stage、car_productionというドメインを作成して環境を分離すると、開発・テスト・運用が容易になります。Cloud Searchでは、このように**ドメイン**という概念を用いて環境を分離しています。
上記で使用した検索設定と[Domainの作成](/docs/ja/analytics-cloudsearch-createdomain) 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の照会](/docs/ja/analytics-cloudsearch-getdomain) 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にドキュメントを追加します。[サンプルファイルのダウンロード](https://cdn.document360.io/da0368a0-4444-4862-a528-42f78876f9e6/Images/Documentation/cloudsearch-ex.json?sv=2026-02-06&spr=https&st=2026-10-30T08%3A46%3A54Z&se=2026-10-30T09%3A46%3A54Z&sr=c&sp=r&sig=N07LfZTdi1FX62M%2BR4%2FQy1swz3QQWr26dsSMr2sWvvQ%3D)をご参照ください。 ドキュメントは必要に応じて insert、update、upsert、deleteすることができ、詳しい使用方法は[Documentの管理](/docs/ja/analytics-cloudsearch-managedocument)をご参照ください。 1回のリクエストで複数のドキュメントを追加でき、insert、update、upsert、deleteリクエストを組み合わせて一度にさまざまなリクエストを送信することも可能です。
[Documentの管理](/docs/ja/analytics-cloudsearch-managedocument)にリクエストを送信して、ドキュメントを 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の検索](/docs/ja/analytics-cloudsearch-searchdocument)をご参照ください。
簡単に 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": "ヒョンデ",
"docid": "car-10001",
"name": "2018サンタフェ",
"price": 2815,
"type": "中型"
},
{
"_rank": 2,
"_key": "car-10002",
"_qds": 0.8729686141014099,
"brand": "ヒョンデ",
"docid": "car-10002",
"name": "2018グランジャー",
"price": 2615,
"type": "中型"
}
]
}
}
```
これに加えて、[自動補完の設定](/docs/ja/analytics-cloudsearch-putautocomplete)および[ストップワードポリシーの設定](/docs/ja/analytics-cloudsearch-poststopword)にも対応しています。詳細は、当該ページをご参照ください。