调用 CreateTopic 接口创建日志主题。 ## 使用说明 * 创建日志主题之前，请确认已创建日志项目。详细说明请参考 [CreateProject](/docs/6470/112174)。 * 此接口的调用频率限制为 20 次/s，超出频率限制会报错 ExceedQPSLimit。 ## 请求说明 * 请求方式：POST * 请求地址：https://{tls\-endpoint}/CreateTopic ## 请求参数下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见[公共参数](https://www.volcengine.com/docs/6470/112170)。 ### Body |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |TopicName |String |是 |`test-topic` |日志主题名称。命名规则请参考[资源命名规则](/docs/6470/74485#.6LWE5rqQ5ZG95ZCN6ZmQ5Yi2)。 | |ProjectId |String |是 |`c7***********` |日志主题所属的日志项目 ID。 | |Ttl |Integer |是 |`1300` |日志在日志服务中的总保存时间，超过指定的日志存储时长后，此日志主题中的过期日志会被自动清除。单位为天，默认为 30 天。取值范围为 1～3650，指定为 3650 天表示永久存储。|\ | | | | |:::tip|\ | | | | |设置 `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~256，默认为 256。|\ | | | | |:::tip|\ | | | | ||\ | | | | |* 仅在开启**自动分裂日志分区**，即 AutoSplit 为 true 时必选。|\ | | | | |* MaxSplitShard 必须大于指定的 ShardCount，否则日志服务无法自动分裂分区。|\ | | | | ||\ | | | | |:::| |EnableTracking |Boolean |否 |`false` |是否开启 WebTracking 功能，开启后，可以通过 WebTracking 快速采集前端埋点数据。|\ | | | | ||\ | | | | |* true：开启 WebTracking功能。|\ | | | | |* false：（默认）关闭 WebTracking 功能。|\ | | | | ||\ | | | | |:::tip|\ | | | | |为日志主题开启 Web Tracking 后，通过 API 接口 WebTracks 写入数据时无需经过鉴权，相当于面向公网开放了匿名写入权限，可能产生脏数据。详细说明请参考[通过 WebTracking 采集日志](../6470/128972)。|\ | | | | ||\ | | | | |:::| |Description |String |否 |`This is a test topic.` |日志主题描述信息。|\ | | | | ||\ | | | | |* 不支持 `<>`、`'`、`\`、`\\`、所有 emoji 表情符号。|\ | | | | |* 长度为 0~64 个字符。 | |Tags |Array of [Tag](#tag) |否 |`[{"Key":"key1", "Value":"value1"}]` |日志主题标签信息。|\ | | | | | |\ | | | | |标签用于云资源的标识与分类，您可以将日志项目、日志主题通过标签进行归类，便于资源的搜索和资源聚合。详细说明请参考[标签管理](/docs/6470/412530)。 | |LogPublicIP |Boolean |否 |`false` |是否开启记录外网 IP 功能。默认为开启状态。开启后日志服务会自动在日志内容中添加以下元数据字段。|\ | | | | ||\ | | | | |* `__tag____client_ip__`：日志来源设备的公网 IP 地址。使用日志服务的私网域名写入日志数据时，则记录私网 IP 地址。|\ | | | | |* `__tag____receive_time__`：日志达到服务端的时间，格式为 10 位的 Unixtime 时间戳。|\ | | | | ||\ | | | | |:::tip|\ | | | | |通过 Web Tracking 方式写入日志时，日志服务通过 clientAddr 记录来源设备的公网 IP 地址。|\ | | | | ||\ | | | | |:::| |EnableHotTtl |Boolean |否 |`false` |是否开启分层存储。开启后，日志服务支持标准存储、低频存储和归档存储。|\ | | | | |设置 HotTtl、ArchiveTtl、ColdTtl 后，如果数据存储时间超过对应时长，那么数据会自动沉降至低频存储、归档存储进行后续保存，直到日志采集到服务端的总时长达到 Ttl 时，被后端服务自动清理。|\ | | | | |:::tip|\ | | | | |Ttl 时长需与 HotTtl、ColdTtl 和 ArchiveTtl 总值相同。|\ | | | | ||\ | | | | |:::| |HotTtl |Integer |否 |`30` |标准存储时长。该时长默认为 30 天，取值范围为 7~3650。|\ | | | | |此参数仅在 EnableHotTtl 为 true 时生效。 | |ColdTtl |Integer |否 |`30` |低频存储时长。该时长取值范围为 1~3650。|\ | | | | |标准存储时长 7 天及以上可实现低频存储。|\ | | | | |此参数仅在 EnableHotTtl 为 true 时生效。 | |ArchiveTtl |Integer |否 |`60` |归档存储时长。该时长取值范围为 60~3650。|\ | | | | |满足如下任一条件时，可实现归档存储。|\ | | | | ||\ | | | | |* 标准存储时长 30 天及以上。|\ | | | | |* 标准存储时长 7 天及以上且低频存储时长 30 天及以上。|\ | | | | ||\ | | | | |此参数仅在 EnableHotTtl 为 true 时生效。 | |EncryptConf |Object of [EncryptConf](#encryptconf) |否 |`-` |数据加密配置。 | ### Tag |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |Key |String |否 |`owner` |标签 Key 的值。设置规则请参考[标签设置规则](/docs/6470/448874#%E6%A0%87%E7%AD%BE%E8%AE%BE%E7%BD%AE%E8%A7%84%E5%88%99)。 | |Value |String |否 |`zhangsan` |标签 Value 的值。设置规则请参考[标签设置规则](/docs/6470/448874#%E6%A0%87%E7%AD%BE%E8%AE%BE%E7%BD%AE%E8%A7%84%E5%88%99)。 | ### EncryptConf |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |enable |Boolean |否 |`false` |是否启用数据加密。|\ | | | | ||\ | | | | |* true：是|\ | | | | |* false：否 | |encrypt_type |String |否 |`default` |加密算法，只支持 default。 | |user_cmk_info |Object of [EncryptUserCmkConf](#encryptusercmkconf) |否 |`{"trn": "trn:iam::123456789:role/service_role_for_tls", "region_id": "cn-hongkong", "user_cmk_id": "fc227edb-3682-4577-a3b5-xxxxxxxxx"}` |密钥信息。 | ### EncryptUserCmkConf |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |trn |String |否 |trn:iam::123456789:role/service_role_for_tls |IAM 角色的 TRN。 | |region_id |String |否 |cn\-hongkong |主密钥所在的地域 ID。 | |user_cmk_id |String |否 |fc227edb\-3682\-4577\-a3b5\-XXXXXXXXX |主密钥 ID。 | ## 返回参数下表仅列出本接口特有的返回参数。更多信息请参见[返回结构](https://www.volcengine.com/docs/6470/112169)。 |**参数** |**类型** |**示例值** |**描述** | |---|---|---|---| |TopicId |String |`b***********` |日志主题 ID。 | ```JSON POST https://{tls-endpoint}/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" } ] } ``` ```JSON HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "TopicId": "bcb************" } ``` ## 错误码下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见[公共错误码](https://www.volcengine.com/docs/6470/112173)文档。 |**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. |服务器内部错误。 |