接口详情
GET /v1/security-string-sets
列出字符串集合
- operationId
listSecurityStringSets- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires security_policies.read. Tenant identities only: the tenant's own sets (writable) and the platform sets (read only, platform true). Items carry no entries; reference_count counts the tenant's live policies referencing the set.
响应
listSecurityStringSets 响应| 状态码 | 说明 |
|---|
200 | Sets ordered own first, then by name. 字段：items: array<SecurityStringSetSummary> |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/security-string-sets
创建字符串集合
- operationId
createSecurityStringSet- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires security_policies.manage. Entries are trimmed, deduplicated and byte ordered (A-Z lower-cased when not case sensitive); a refused entry is validation_error with details.field entries[i] and a reason (too_long, invalid_utf8, control_character, wildcard_too_many_stars, wildcard_only_wildcards, empty); the set as a whole entries with too_many_entries or too_large. match_mode and case_sensitive cannot change later. At most 200 live sets per scope (422 string_set_limit). Audit security.string_set.create.
参数
createSecurityStringSet 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
createSecurityStringSet 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
name | string | 是 | — |
|---|
description | string | 否 | — |
|---|
match_mode | string: exact / prefix / suffix / contains / wildcard | 是 | Fixed at creation. prefix compares bytes (/api also matches /apiary); wildcard: * any bytes, ? one byte, at most 3 * and 2000 entries. |
|---|
case_sensitive | boolean | 是 | Fixed at creation. When false A-Z are lower-cased (other letters compare as they are). |
|---|
entries | array<string> | 是 | At most 256 KiB together. |
|---|
响应
createSecurityStringSet 响应| 状态码 | 说明 |
|---|
201 | Created, or an identical request replayed. 字段：id: string(uuid) name: string description: string match_mode: string: exact / prefix / suffix / contains / wildcard case_sensitive: boolean entry_count: integer reference_count: integer revision: integer platform: boolean updated_at: string(date-time) entries: array<string> |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
422 | The request is well formed but breaks a business rule (error.code names it). |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/security-string-sets/{set_id}
查看字符串集合
- operationId
getSecurityStringSet- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires security_policies.read. An own or platform set, with its canonical entries.
参数
getSecurityStringSet 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
set_id | path | string(uuid) | 是 | — |
|---|
响应
getSecurityStringSet 响应| 状态码 | 说明 |
|---|
200 | The set. 字段：id: string(uuid) name: string description: string match_mode: string: exact / prefix / suffix / contains / wildcard case_sensitive: boolean entry_count: integer reference_count: integer revision: integer platform: boolean updated_at: string(date-time) entries: array<string> |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
PUT /v1/security-string-sets/{set_id}
替换字符串集合
- operationId
updateSecurityStringSet- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires security_policies.manage and the current revision; match_mode / case_sensitive in the body are refused. Every tenant whose bound WAF policy references the set is republished automatically (system trigger string_set). Audit security.string_set.update.
参数
updateSecurityStringSet 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
set_id | path | string(uuid) | 是 | — |
|---|
请求体
application/json · 必填：是
updateSecurityStringSet 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer | 是 | — |
|---|
name | string | 是 | — |
|---|
description | string | 否 | — |
|---|
entries | array<string> | 是 | — |
|---|
响应
updateSecurityStringSet 响应| 状态码 | 说明 |
|---|
200 | Replaced (revision + 1), or an identical request replayed. 字段：id: string(uuid) name: string description: string match_mode: string: exact / prefix / suffix / contains / wildcard case_sensitive: boolean entry_count: integer reference_count: integer revision: integer platform: boolean updated_at: string(date-time) entries: array<string> |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
DELETE /v1/security-string-sets/{set_id}
删除字符串集合
- operationId
deleteSecurityStringSet- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires security_policies.manage and the current revision. A set any live policy version references is refused (409 string_set_in_use). Audit security.string_set.delete.
参数
deleteSecurityStringSet 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
set_id | path | string(uuid) | 是 | — |
|---|
expected_revision | query | integer | 是 | — |
|---|
响应
deleteSecurityStringSet 响应| 状态码 | 说明 |
|---|
204 | Deleted. |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/security-string-sets/{set_id}/references
列出引用字符串集合的策略
- operationId
listSecurityStringSetReferences- 认证
- API Key：请求头 Authorization: CdncaKey <key_id>.<secret>。有效权限是 Key 的范围与所有者当前权限的交集。
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires security_policies.read. The caller's live policies with a version referencing the set (the platform sees every scope); rule_count is from the latest referencing version.
参数
listSecurityStringSetReferences 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
set_id | path | string(uuid) | 是 | — |
|---|
响应
listSecurityStringSetReferences 响应| 状态码 | 说明 |
|---|
200 | Policies by name. 字段：items: array<SecurityStringSetReference> |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表