CreateTopic--日志服务-火山引擎

文档中心

立即注册

导航

CreateTopic

最近更新时间：2024.12.05 11:09:50首次发布时间：2022.05.11 11:26:47

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

使用说明

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

请求说明

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

请求参数

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

Body

参数	类型	是否必选	示例值	描述
TopicName	String	是	`test-topic`	日志主题名称。命名规则请参考资源命名规则。
ProjectId	String	是	`c7***********`	日志主题所属的日志项目 ID。
Ttl	Integer	是	`1300`	日志在日志服务中的总保存时间，超过指定的日志存储时长后，此日志主题中的过期日志会被自动清除。单位为天，默认为 30 天。取值范围为 1～3650，指定为 3650 天表示永久存储。说明设置 `EnableHotTtl` 为 true 后，Ttl 时长需与 HotTtl、ColdTtl 和 ArchiveTtl 总值相同。
ShardCount	Integer	是	`2`	日志分区的数量，默认创建 1 个分区，取值范围为 1～10。每个分区提供的写入能力为 5MiB/s、500 次/s，读取能力为 20 MiB/s、100 次/s。请在创建日志主题时合理规划分区，创建后暂不支持修改分区数量。
AutoSplit	Boolean	否	`true`	是否开启分区的自动分裂功能。 true：当写入的数据量连续 5 分钟超过已有分区服务能力时，日志服务会根据数据量自动分裂分区以满足业务需求，但分裂后的分区数量不可超出最大分裂数。最近 15 分钟内分裂出来的新分区不会自动分裂。 false：不开启分区的自动分裂。
MaxSplitShard	Integer	否	`50`	分区的最大分裂数，即分区分裂后，所有分区的最大数量。取值范围为 1~50，默认为 50。说明仅在开启自动分裂日志分区，即 AutoSplit 为 true 时必选。 MaxSplitShard 必须大于指定的 ShardCount，否则日志服务无法自动分裂分区。
EnableTracking	Boolean	否	`false`	是否开启 WebTracking 功能，开启后，可以通过 WebTracking 快速采集前端埋点数据。 true：开启 WebTracking功能。 false：（默认）关闭 WebTracking 功能。说明为日志主题开启 Web Tracking 后，通过 API 接口 WebTracks 写入数据时无需经过鉴权，相当于面向公网开放了匿名写入权限，可能产生脏数据。详细说明请参考通过 WebTracking 采集日志。
Description	String	否	`This is a test topic.`	日志主题描述信息。不支持 `<>`、`'`、`\`、`\\`、所有 emoji 表情符号。长度为 0~64 个字符。
Tags	Array of Tag	否	`[{"Key":"key1", "Value":"value1"}]`	日志主题标签信息。标签用于云资源的标识与分类，您可以将日志项目、日志主题通过标签进行归类，便于资源的搜索和资源聚合。详细说明请参考标签管理。
LogPublicIP	Boolean	否	`false`	是否开启记录外网 IP 功能。默认为开启状态。开启后日志服务会自动在日志内容中添加以下元数据字段。 `__tag____client_ip__`：日志来源设备的公网 IP 地址。使用日志服务的私网域名写入日志数据时，则记录私网 IP 地址。 `__tag____receive_time__`：日志达到服务端的时间，格式为 10 位的 Unixtime 时间戳。说明通过 Web Tracking 方式写入日志时，日志服务通过 clientAddr 记录来源设备的公网 IP 地址。
EnableHotTtl	Boolean	否	`false`	是否开启分层存储。开启后，日志服务支持标准存储、低频存储和归档存储。设置 HotTtl、ArchiveTtl、ColdTtl 后，如果数据存储时间超过对应时长，那么数据会自动沉降至低频存储、归档存储进行后续保存，直到日志采集到服务端的总时长达到 Ttl 时，被后端服务自动清理。说明分层存储为邀测功能，若有相关业务需求，可联系客户经理开通白名单。 Ttl 时长需与 HotTtl、ColdTtl 和 ArchiveTtl 总值相同。
HotTtl	Integer	否	`30`	标准存储时长。该时长默认为 30 天，取值范围为 7~3650。此参数仅在 EnableHotTtl 为 true 时生效。
ColdTtl	Integer	否	`30`	低频存储时长。该时长取值范围为 30~3650。标准存储时长 7 天及以上可实现低频存储。此参数仅在 EnableHotTtl 为 true 时生效。
ArchiveTtl	Integer	否	`60`	归档存储时长。该时长取值范围为 60~3650。满足如下任一条件时，可实现归档存储。标准存储时长 30 天及以上。标准存储时长 7 天及以上且低频存储时长 30 天及以上。此参数仅在 EnableHotTtl 为 true 时生效。

Tag

参数	类型	是否必选	示例值	描述
Key	String	否	`owner`	标签 Key 的值。设置规则请参考标签设置规则。
Value	String	否	`zhangsan`	标签 Value 的值。设置规则请参考标签设置规则。

返回参数

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

参数	类型	示例值	描述
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": 50,
    "EnableTracking": false,
    "Tags": [
        {
            "Key": "key1",
            "Value": "value1"
        }
    ]
}

返回示例

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

错误码

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

HTTP 状态码	错误码	错误信息	说明
400	InvalidArgument	Invalid argument key %s, value %s, please check argument.	参数不合法。
400	TopicQuotaExceed	Topic Quota Exceed.	超过日志主题限额。
409	TopicAlreadyExist	Topic xxx already exist.	日志主题已存在。
500	InternalServerError	We encountered an unexpected server error, please try again later.	服务器内部错误。