开放接口

`/v1/admin/doh-settings`

2 个接口

← 全部分组 · 第一次调用？先看教程：认证、权限、请求与响应、常见失败

方法	路径	摘要	认证
GET	`/v1/admin/doh-settings`	读取 DoH 服务设置	登录会话
PUT	`/v1/admin/doh-settings`	修改 DoH 服务设置	登录会话

契约文件：api/control-doh-settings.openapi.yaml

接口详情

GET `/v1/admin/doh-settings`

读取 DoH 服务设置

operationId

getPlatformDoHSettings

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：system_configuration.read

响应

getPlatformDoHSettings 响应
状态码	说明
`200`	Current settings 字段：`schema: string` `revision: integer(int64)` `value: Settings` `host_site_id: string(uuid) \| null(uuid)` `token_set: boolean` `token_created_at: string(date-time) \| null(date-time)` `token?: string` `nodes_in_range: integer` `nodes_declaring: integer` `updated_at: string(date-time)`
`401`	Unauthenticated
`403`	Permission denied
`500`	Unexpected internal failure
`503`	Settings storage is unavailable

失败时怎么办

401 检查凭据格式、是否过期或被轮换。
403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

PUT `/v1/admin/doh-settings`

修改 DoH 服务设置

operationId

updatePlatformDoHSettings

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：system_configuration.manage

参数

updatePlatformDoHSettings 参数
名称	位置	类型	必填	说明
`If-Match`	header	`string`	是	—
`X-Request-ID`	header	`string`	否	—

请求体

application/json · 必填：是

updatePlatformDoHSettings 请求体
名称	类型	必填	说明
`value`	`Settings`	是	—
`rotate_token`	`boolean`	否	Generate a new access token; required when an auth mode is chosen and none exists.

响应

updatePlatformDoHSettings 响应
状态码	说明
`200`	Saved settings 字段：`schema: string` `revision: integer(int64)` `value: Settings` `host_site_id: string(uuid) \| null(uuid)` `token_set: boolean` `token_created_at: string(date-time) \| null(date-time)` `token?: string` `nodes_in_range: integer` `nodes_declaring: integer` `updated_at: string(date-time)`
`400`	Validation error or invalid If-Match
`401`	Unauthenticated
`403`	Permission denied
`409`	Revision conflict
`500`	Unexpected internal failure
`503`	Settings storage is unavailable

失败时怎么办

400 按字段说明修正参数或请求体再发；不要原样重试。
401 检查凭据格式、是否过期或被轮换。
403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表