You need to enable JavaScript to run this app.
导航
日志服务
  • 文档首页
    • /日志服务/API 参考/索引管理/CreateIndex
CreateIndex
最近更新时间：2024.10.21 17:58:20首次发布时间：2022.05.11 11:26:48
我的收藏

调用 CreateIndex 接口创建索引。

使用说明

本接口用于创建日志主题的索引。调用频率限制为 20 次/s，超出频率限制会报错 ExceedQPSLimit。

说明

  • 全文索引与键值索引至少要开启一项，索引关闭时采集的日志数据将无法被检索。
  • 日志服务单词存在 32766 字符限制，对于全文或单词过长的日志，如果未开启分词符，可能导致日志被丢弃。
  • 某个字段开启键值索引但未开启统计时，如果未配置分词符或者包含中文，则字段不分词。
  • 某个字段开启键值索引和统计时，分词符属性不生效。

请求说明

  • 请求方式：POST
  • 请求地址：https://tls-{Region}.ivolces.com/CreateIndex

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Body

参数类型是否必选示例值描述
TopicIdString是4a*********日志主题 ID。

FullText

Object of FullTextInfo

否

/

全文索引配置。

  • 此字段为 null 或者未配置，表示不开启全文索引。
  • 全文索引配置和键值索引配置至少配置一项，即 FullText 和 KeyValue 之间应至少指定一个参数。

KeyValue

Array of KeyValueInfo

否

/

键值索引配置。

  • 此字段数组长度为 0 或者未配置，表示不开启键值索引。
  • 全文索引配置和键值索引配置至少配置一项，即 FullText 和 KeyValue 之间应至少指定一个参数。

UserInnerKeyValue

Array of KeyValueInfo

否

/

预留字段索引配置。

  • 此字段数组长度为 0 或者未配置，表示不开启预留字段索引。
  • 不能同时开启全文索引和预留字段 __content__ 的键值索引，即如果通过 UserInnerKeyValue 参数设置__content__ 索引，则不能同时设置参数 FullText。
  • 预留字段中，目前仅支持为 __content__ 手动开启索引。其他预留字段的索引设置请参考预留字段。

FullTextInfo

参数类型是否必选示例值描述

Delimiter

String

是

, ;/\n\t

全文索引的分词符。

  • 字符串中每个字符代表一个分词符。
  • 长度为 1~256 字节。
  • 仅支持以下字符中的一种或者多种：
    大小写字母、数字以及 !@#%^&*()-_=\\\"', <>/?|;:\n\t\r[]{}.。
  • 支持同时配置包含中文和分词符。

CaseSensitive

Boolean

是

false

是否大小写敏感。

  • true：大小写敏感。
  • false：大小写不敏感。

IncludeChinese

Boolean

否

false

是否包含中文。默认为 false，即不包含。
支持同时配置包含中文和分词符。

KeyValueInfo

参数类型是否必选示例值描述

Key

String

是

"Key": "test-key1"

需要配置键值索引的字段名称，最多添加 100 个字段。

  • 仅支持字母、数字、空格、下划线（_）、连字符（-）和斜线（/），并且不支持以空格开头或结尾。
  • 同一个索引中 key 名称唯一。
  • 长度为 1~128 字符。

说明

对于 JSON 类型键值索引的子字段，需要通过.表示 JSON 字段之间的层级关系，例如 JSON 字段 namelist 中包含 text 类型的子字段 totalcount 和 JSON 类型的 info，info 中又包含字段 name，各个字段名称应分别配置为totalcount 和 info.name。

ValueObject of Value是"Value": { "ValueType": "text", "Delimiter": "", "CaseSensitive": true, "IncludeChinese": false, "SqlFlag": false }需要配置键值索引的字段描述信息。

Value

参数类型是否必选示例值描述

SqlFlag

Boolean

否

false

字段是否开启分析功能。默认为 false。
开启统计分析功能后，支持配置分词符和包含中文。

IndexAllBoolean否false是否为 JSON 字段中所有值为文本的字段创建索引。

JsonKeys

Array of KeyValueInfo

否

[ { "Key":"key1", "Value":{ "ValueType":"text", "SqlFlag":true } }, { "Key":"key2", "Value":{ "ValueType":"long", "SqlFlag":true } }, { "Key":"key3.key4.key5", "Value":{ "ValueType":"double", "SqlFlag":true } } ]

当 ValueType 为 json 时，可通过 JsonKeys 字段配置 JSON 子字段键值索引，其值为 KeyValueInfo 数组。

  • JsonKeys 列表中每个元素为 KeyValueInfo，可进一步嵌套定义 text、long、double 类型子字段。
  • 对于 JSON 类型键值索引的子字段，需要通过.表示 JSON 字段之间的层级关系，例如 JSON 字段 namelist 中包含 text 类型的子字段 totalcount 和 JSON 类型的 info，info 中又包含字段 name，各个字段名称应分别配置为totalcount 和 info.name。
  • JsonKeys 中定义的子字段键值索引的 SqlFlag 设置应与其父字段设置保持一致，即需要同时开启或关闭，默认为关闭状态。子字段不支持单独设置 Delimiter、CaseSensitive 和 IncludeChinese，对于 text 类型的字段，CaseSensitive、Delimiter 和 IncludeChinese 固定沿用父字段设置。
  • 仅当 ValueType 为 json 时设置。

Delimiter

String

否

, ;/\n\t

字段的分词符。默认为空（""）。

  • 字符串中每个字符代表一个分词符。
  • 长度为 0~256 字节，长度为 0 时表示不分词。
  • 仅支持以下字符中的一种或者多种：
    大小写字母、数字以及 !@#%^&*()-_=\\\"', <>/?|;:\n\t\r[]{}.。
  • 支持同时配置包含中文和分词符。

ValueType

String

是

text

字段类型。

  • 目前支持 long、double、text 和 json。
  • long 和 double 类型不支持配置分词符、包含中文、大小写敏感。
  • 仅 json 类型支持进一步配置 JsonKeys 子字段。
CaseSensitiveBoolean否true是否区分大小写。默认为 false。

IncludeChinese

Boolean

否

false

是否包含中文。默认为 false，即不包含中文。
支持同时配置包含中文和分词符。

返回参数

下表仅列出本接口特有的返回参数。更多信息请参见返回结构。

参数类型示例值描述
TopicIdString3***********日志主题 ID。

请求示例 1

全文索引示例

POST https://tls-{Region}.ivolces.com/CreateIndex HTTP/1.1
Content-Type: application/json
{
    "TopicId": "3***********",
    "FullText": {
        "Delimiter": ",-;",
        "CaseSensitive": false,
        "IncludeChinese": false
    }
}

返回示例 1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "TopicId": "39**********"
}

请求示例 2

全文索引和键值索引示例

POST https://tls-{Region}.ivolces.com/CreateIndex HTTP/1.1
Content-Type: application/json
{
    "TopicId": "39********",
    "FullText": {
        "Delimiter": ",-;"
    },
    "KeyValue": [
        {
            "Key": "test1",
            "Value": {
                "ValueType": "text",
                "Delimiter": "",
                "CaseSensitive": true,
                "IncludeChinese": false,
                "SqlFlag": false
            }
        },
        {
            "Key": "test2",
            "Value": {
                "ValueType": "long",
                "Delimiter": "",
                "CaseSensitive": false,
                "IncludeChinese": false,
                "SqlFlag": true
            }
        },
        {
            "Key": "test3",
            "Value": {
                "ValueType": "json",
                "Delimiter": "",
                "CaseSensitive": false,
                "IncludeChinese": false,
                "SqlFlag": true,
                "JsonKeys": [
                    {
                        "Key": "key1",
                        "Value": {
                            "ValueType": "text",
                            "SqlFlag": true
                        }
                    },
                    {
                        "Key": "key2",
                        "Value": {
                            "ValueType": "long",
                            "SqlFlag": true
                        }
                    },
                    {
                        "Key": "key3.key4.key5",
                        "Value": {
                            "ValueType": "double",
                            "SqlFlag": true
                        }
                    }
                ]
            }
        }
    ]
}

返回示例 2

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8  
{
    "TopicId": "39**********"
}

请求示例 3

键值索引和预留字段索引示例

POST https://tls-{Region}.ivolces.com/CreateIndex HTTP/1.1
Content-Type: application/json
{
    "TopicId": "39********",
    "KeyValue": [
        {
            "Key": "test1",
            "Value": {
                "ValueType": "text",
                "Delimiter": "",
                "CaseSensitive": true,
                "IncludeChinese": false,
                "SqlFlag": false
            }
        },
        {
            "Key": "test2",
            "Value": {
                "ValueType": "long",
                "Delimiter": "",
                "CaseSensitive": false,
                "IncludeChinese": false,
                "SqlFlag": true
            }
        },
        {
            "Key": "test3",
            "Value": {
                "ValueType": "json",
                "Delimiter": "",
                "CaseSensitive": false,
                "IncludeChinese": false,
                "SqlFlag": true,
                "JsonKeys": [
                    {
                        "Key": "key1",
                        "Value": {
                            "ValueType": "text",
                            "SqlFlag": true
                        }
                    },
                    {
                        "Key": "key2",
                        "Value": {
                            "ValueType": "long",
                            "SqlFlag": true
                        }
                    },
                    {
                        "Key": "key3.key4.key5",
                        "Value": {
                            "ValueType": "double",
                            "SqlFlag": true
                        }
                    }
                ]
            }
        }
    ]，
    "UserInnerKeyValue": [
        {
            "Key": "__content__",
            "Value": {
                "ValueType": "json",
                "Delimiter": ",:-/ ",
                "CaseSensitive": false,
                "IncludeChinese": false,
                "SqlFlag": false,
                "JsonKeys": [
                    {
                        "Key": "name",
                        "Value": {
                            "ValueType": "text",
                            "SqlFlag": false
                        }
                    },
                    {
                        "Key": "age",
                        "Value": {
                            "ValueType": "long",
                            "SqlFlag": false
                        }
                    },
                    {
                        "Key": "education.master.college",
                        "Value": {
                            "ValueType": "text",
                            "SqlFlag": false
                        }
                    }
                ]
            }
        }
    ]
}

返回示例 3

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "TopicId":"39**********"
}

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

HTTP 状态码错误码错误信息说明
400InvalidArgumentInvalid argument key %s, value %s, please check argument.分词符和中分分词不能同时配置。
400InvalidArgumentAt least one of full-text indexing and key-value indexing must be turned on.全文索引与键值索引至少要开启一项。
400InvalidArgumentIndex key value_type:%s conflict with [includeChinese:%t, casSensitive:%t, delimiter:%s], please check argument.long/double 类型不支持配置包含中文、大小写敏感和分词符。
400InvalidIndexJsonKeysNon-JSON field %s configures JsonKeys, please check argument.非 JSON 字段配置子字段
400ConflictIndexJsonKeysJsonKeys %s and %s have conflict prefix, please check argument.JsonKeys 键名存在前缀冲突
400InvalidArgumentIndex key sqlFlag:%t conflict with [includeChinese:%t, delimiter:%s], please check argument.开启统计后，不支持配置包含中文和分词符。
400IndexKeyValueQuotaExceedExceeded index key-value quota.超过键值索引限额。
400IndexKeyDuplicateThe %dth index key name:%s is duplicate, please check argument.索引的键值名称重复。
400InvalidArgumentIndex key delimiter:%s conflict with includeChinese:%t, please check argument.分词符和中分分词不能同时配置。
400IndexKVNULLIndex key value index is open, but the key value list is null, please check argument.键值索引配置的键值个数为 0。
404TopicNotExistTopic does not exist.日志主题不存在。
409IndexAlreadyExistIndex already existIndex 已存在。
500InternalServerErrorWe encountered an unexpected server error, please try again later.服务器内部错误。
400IndexInnerKeyUnSupportkey-value indexing for inner key: %v, doesn't support不支持为 %v 字段设置预留字段索引。
400IndexInnerKeyConflictfull-text indexing and content indexing can't be set together全文索引与__content__索引配置冲突。