You need to enable JavaScript to run this app.
导航

CreateTopic

最近更新时间2023.12.21 18:00:24

首次发布时间2022.05.11 11:26:47

调用 CreateTopic 接口创建日志主题。

使用说明

本接口用于创建日志主题。

  • 创建日志主题之前,请确认已创建日志项目。详细说明请参考 CreateProject
  • 此接口的调用频率限制为 20 次/s,超出频率限制会报错 ExceedQPSLimit。

URI

请求方法
POST

URI

https://tls-{Region}.ivolces.com/CreateTopic

传输协议

HTTPS

请求参数

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

说明

TopicName

String

必选

test-topic

日志主题名称。

  • 同一个日志项目下,日志主题名称不可重复。
  • 只能包括小写字母、中文、数字、连字符(-)。
  • 必须以小写字母、中文、数字开头或结尾。
  • 长度为 3~63 字符。

ProjectId

String

必选

c7***********

日志主题所属的日志项目 ID。

Ttl

Integer

必选

1300

日志在日志服务中的保存时间,超过指定的日志存储时长后,此日志主题中的过期日志会被自动清除。 单位为天,默认为 30 天。取值范围为 1~3650,指定为 3650 天表示永久存储。

ShardCount

Integer

必选

2

日志分区的数量,默认创建 1 个分区,取值范围为 1~10。 每个分区提供的写入能力为 5MiB/s、500 次/s,读取能力为 5 MiB/s、100 次/s。请在创建日志主题时合理规划分区,创建后暂不支持修改分区数量。

AutoSplit

Boolean

可选

true

是否开启分区的自动分裂功能。

  • true:(默认)当写入的数据量连续 5 分钟超过已有分区服务能力时,日志服务会根据数据量自动分裂分区以满足业务需求,但分裂后的分区数量不可超出最大分裂数。最近 15 分钟内分裂出来的新分区不会自动分裂。
  • false:不开启分区的自动分裂。

MaxSplitShard

Integer

可选

10

分区的最大分裂数,即分区分裂后,所有分区的最大数量。取值范围为 1~50,默认为 50。

说明

  • 仅在开启自动分裂日志分区,即 AutoSplit 为 true 时必选。
  • MaxSplitShard 必须大于指定的 ShardCount,否则日志服务无法自动分裂分区。

EnableTracking

Boolean

可选

false

是否开启 WebTracking 功能,开启后,可以通过 WebTracking 快速采集前端埋点数据。

  • true:开启 WebTracking功能。
  • false:(默认)关闭 WebTracking 功能。

说明

为日志主题开启 Web Tracking 后,通过 API 接口 WebTracks 写入数据时无需经过鉴权,相当于面向公网开放了匿名写入权限,可能产生脏数据。详细说明请参考通过 WebTracking 采集日志

TimeKey

String

可选

request_time

日志时间字段的字段名称。长度限制为 1~128 哥字符,包括英文字母、数字、和特殊字符(-_./),且不能以下划线开头。
如果将日志中的指定时间字段作为日志时间戳,则需要同时指定 TimeKey 和 TimeFormat。

TimeFormat

String

可选

%Y-%m-%dT%H:%M:%S,%f

时间字段的解析格式。长度限制为 1 ~ 128 个字符。

  • 如何配置时间格式,请参考时间格式
  • 如果将日志中的指定时间字段作为日志时间戳,则需要同时指定 TimeKey 和 TimeFormat。

Description

String

可选

This is a test topic.

日志主题描述信息。

  • 不支持 <>'\\\、所有 emoji 表情符号。
  • 长度为 0~64 个字符。

Tags

Array of TagInfo

可选

[{"Key":"key1",
"Value":"value1"}]

日志主题标签信息,详细信息请参考TagInfo
标签用于云资源的标识与分类,您可以将日志项目、日志主题通过标签进行归类,便于资源的搜索和资源聚合。详细说明请参考标签管理

LogPublicIP

Boolean

可选

false

是否开启记录外网 IP 功能。默认为开启状态。开启后日志服务会自动在日志内容中添加以下元数据字段。

  • __tag____client_ip__:日志来源设备的公网 IP 地址。使用日志服务的私网域名写入日志数据时,则记录私网 IP 地址。
  • __tag____receive_time__:日志达到服务端的时间,格式为 10 位的 Unixtime 时间戳。

说明

通过 Web Tracking 方式写入日志时,日志服务通过 clientAddr 记录来源设备的公网 IP 地址。

EnableHotTtl

Boolean

可选

false

是否开启低频存储。开启后,标准存储的数据在标准存储保存一段时间之后自动转化为低频存储类型。

说明

低频存储为邀测功能,若有相关业务需求,可联系客户经理开通白名单。

HotTtl

Integer

可选

7

此参数用于在开启低频存储后,设置数据在标准存储的保留时长,超过该时长后,数据会自动沉降至低频存储进行后续保存,直到日志采集到服务端的总时长达到日志存储时长时,被后端服务自动清理。
该时长默认为 30 天,取值范围为 7~3650,且不可大于 Ttl。
此参数仅在 EnableHotTtl 为 true 时生效。

响应参数

参数
类型
示例值
描述

TopicId

String

b***********

日志主题 ID。

示例

请求示例

POST https://tls-{Region}.ivolces.com/CreateTopic HTTP/1.1
Content-Type: application/json
...
{
    "ProjectId":"c7************",
    "TopicName":"test-topic",
    "Ttl":30,
    "Description":"xxxxxx",
    "ShardCount":1,
    "AutoSplit":true,
    "MaxSplitShard":10,
    "EnableTracking":false,
    "TimeKey": "request_time",
    "TimeFormat": "%Y-%m-%dT%H:%M:%S,%f",
    "Tags":[
        {
            "Key":"key1",
            "Value":"value1"
        }
    ]
}

响应示例

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

错误码

错误码(Code)
HTTP 状态码
错误信息(Message)
说明

InvalidArgument

400

Invalid argument key %s, value %s, please check argument.

参数不合法。

TopicQuotaExceed

400

Topic Quota Exceed.

超过日志主题限额。

TopicAlreadyExist

409

Topic xxx already exist

日志主题已存在。

InternalServerError

500

We encountered an unexpected server error, please try again later.

服务器内部错误。

更多信息,请参考通用错误码