From a16105f716107c148c54a6fe06bc479972ce368f Mon Sep 17 00:00:00 2001 From: flashduty-ai-sre Date: Thu, 3 Sep 2026 09:41:16 +0000 Subject: [PATCH] api-review: add RUM remote-config (5 ops) + schedule by-person; member_id filter on /member/list Registry drift vs committed specs (fc-pgy api_test.go lines 931, 1187-1191): - POST /rum/application/remote-config/{get,update,preview,history/list,history/revert} (fc-rum #204, registered 2026-08-31) - POST /schedule/by-person (fc-oncall #266 aae1eab, registered 2026-09-01) Schema drift: POST /member/list gains optional member_id (uint64) filter (fc-pgy bb7f8e39). Nav (docs.json) and api-catalog.mdx reconciled: On-call 192->193, RUM 36->41, total 336->342. Split + consolidated specs updated in EN and ZH; openapi.legacy.zh.json untouched. --- api-reference/on-call.openapi.en.json | 165 +++ api-reference/on-call.openapi.zh.json | 165 +++ api-reference/openapi.en.json | 1693 +++++++++++++++++++----- api-reference/openapi.zh.json | 1693 +++++++++++++++++++----- api-reference/platform.openapi.en.json | 5 + api-reference/platform.openapi.zh.json | 5 + api-reference/rum.openapi.en.json | 851 ++++++++++++ api-reference/rum.openapi.zh.json | 851 ++++++++++++ docs.json | 16 +- en/openapi/api-catalog.mdx | 12 +- zh/openapi/api-catalog.mdx | 12 +- 11 files changed, 4788 insertions(+), 680 deletions(-) diff --git a/api-reference/on-call.openapi.en.json b/api-reference/on-call.openapi.en.json index 6c7dfaa6..55d97f5d 100644 --- a/api-reference/on-call.openapi.en.json +++ b/api-reference/on-call.openapi.en.json @@ -17322,6 +17322,95 @@ } } } + }, + "/schedule/by-person": { + "post": { + "operationId": "scheduleByPerson", + "summary": "Get member on-call status", + "description": "Get a member's current and next on-call shifts and every enabled schedule they participate in.", + "tags": [ + "On-call/Schedules" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- `current` carries the shift in progress with its true start time; `next` is the upcoming shift, absent when nothing is scheduled within the lookup window.\n- Disabled schedules are not listed.", + "href": "/en/api-reference/on-call/schedules/schedule-by-person", + "metadata": { + "sidebarTitle": "Get member on-call status" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ScheduleByPersonResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "current": { + "schedule_id": 2539108069860, + "schedule_name": "Open Source Q&A", + "start_at": 1773446400, + "end_at": 1773532799 + }, + "next": { + "schedule_id": 2539108069860, + "schedule_name": "Open Source Q&A", + "start_at": 1773532800, + "end_at": 1773619199 + }, + "schedules": [ + { + "schedule_id": 2539108069860, + "schedule_name": "Open Source Q&A" + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScheduleByPersonRequest" + }, + "example": { + "person_id": 2476444212131 + } + } + } + } + } } }, "components": { @@ -33346,6 +33435,82 @@ "title": "a_unack", "description": "Detail payload for `a_unack` (historical). No fields.", "properties": {} + }, + "ScheduleByPersonRequest": { + "type": "object", + "description": "Member on-call status request", + "properties": { + "person_id": { + "type": "integer", + "description": "Member ID whose on-call status is returned.", + "format": "int64" + } + }, + "required": [ + "person_id" + ] + }, + "ScheduleByPersonResponse": { + "type": "object", + "description": "The member's on-call status: the shift in progress, the next one, and every enabled schedule they participate in.", + "properties": { + "current": { + "$ref": "#/components/schemas/MemberOncallInterval" + }, + "next": { + "$ref": "#/components/schemas/MemberOncallInterval" + }, + "schedules": { + "type": "array", + "description": "All enabled schedules the member participates in.", + "items": { + "$ref": "#/components/schemas/MemberScheduleItem" + } + } + }, + "required": [ + "schedules" + ] + }, + "MemberScheduleItem": { + "type": "object", + "description": "An enabled schedule the member participates in.", + "properties": { + "schedule_id": { + "type": "integer", + "description": "Schedule ID.", + "format": "int64" + }, + "schedule_name": { + "type": "string", + "description": "Schedule name." + } + } + }, + "MemberOncallInterval": { + "type": "object", + "description": "One on-call shift interval of a member.", + "properties": { + "schedule_id": { + "type": "integer", + "description": "Owning schedule ID.", + "format": "int64" + }, + "schedule_name": { + "type": "string", + "description": "Owning schedule name." + }, + "start_at": { + "type": "integer", + "description": "Unix timestamp in seconds - when the shift starts.", + "format": "int64" + }, + "end_at": { + "type": "integer", + "description": "Unix timestamp in seconds - when the shift ends. Absent while the shift is ongoing.", + "format": "int64" + } + } } } } diff --git a/api-reference/on-call.openapi.zh.json b/api-reference/on-call.openapi.zh.json index 7c6cfed1..2756711f 100644 --- a/api-reference/on-call.openapi.zh.json +++ b/api-reference/on-call.openapi.zh.json @@ -17322,6 +17322,95 @@ } } } + }, + "/schedule/by-person": { + "post": { + "operationId": "scheduleByPerson", + "summary": "查看成员值班状态", + "description": "查看某成员正在值班的班次、下一次值班以及其参与的全部启用排班。", + "tags": [ + "On-call/值班排班" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |\n\n## 使用说明\n\n- `current` 为正在值班的班次（含真实开始时间）；`next` 为下一次值班，查询窗口内没有排班时缺省。\n- 已禁用的排班不会出现在列表中。", + "href": "/zh/api-reference/on-call/schedules/schedule-by-person", + "metadata": { + "sidebarTitle": "查看成员值班状态" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ScheduleByPersonResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "current": { + "schedule_id": 2539108069860, + "schedule_name": "Open Source Q&A", + "start_at": 1773446400, + "end_at": 1773532799 + }, + "next": { + "schedule_id": 2539108069860, + "schedule_name": "Open Source Q&A", + "start_at": 1773532800, + "end_at": 1773619199 + }, + "schedules": [ + { + "schedule_id": 2539108069860, + "schedule_name": "Open Source Q&A" + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScheduleByPersonRequest" + }, + "example": { + "person_id": 2476444212131 + } + } + } + } + } } }, "components": { @@ -33346,6 +33435,82 @@ "title": "a_unack", "description": "`a_unack` 的详情数据（历史），无字段。", "properties": {} + }, + "ScheduleByPersonRequest": { + "type": "object", + "description": "成员值班状态查询请求", + "properties": { + "person_id": { + "type": "integer", + "description": "要查询值班状态的成员 ID。", + "format": "int64" + } + }, + "required": [ + "person_id" + ] + }, + "ScheduleByPersonResponse": { + "type": "object", + "description": "成员的值班状态：正在值班的班次、下一次值班，以及其参与的全部启用排班。", + "properties": { + "current": { + "$ref": "#/components/schemas/MemberOncallInterval" + }, + "next": { + "$ref": "#/components/schemas/MemberOncallInterval" + }, + "schedules": { + "type": "array", + "description": "该成员参与的全部启用排班。", + "items": { + "$ref": "#/components/schemas/MemberScheduleItem" + } + } + }, + "required": [ + "schedules" + ] + }, + "MemberScheduleItem": { + "type": "object", + "description": "该成员参与的一个启用中的排班。", + "properties": { + "schedule_id": { + "type": "integer", + "description": "排班 ID。", + "format": "int64" + }, + "schedule_name": { + "type": "string", + "description": "排班名称。" + } + } + }, + "MemberOncallInterval": { + "type": "object", + "description": "成员的一个值班班次区间。", + "properties": { + "schedule_id": { + "type": "integer", + "description": "所属排班 ID。", + "format": "int64" + }, + "schedule_name": { + "type": "string", + "description": "所属排班名称。" + }, + "start_at": { + "type": "integer", + "description": "Unix 时间戳（秒）—— 班次开始时间。", + "format": "int64" + }, + "end_at": { + "type": "integer", + "description": "Unix 时间戳（秒）—— 班次结束时间。值班进行中时缺省。", + "format": "int64" + } + } } } } diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 2ebeee20..abb6d5f5 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -30814,6 +30814,602 @@ } } } + }, + "/schedule/by-person": { + "post": { + "operationId": "scheduleByPerson", + "summary": "Get member on-call status", + "description": "Get a member's current and next on-call shifts and every enabled schedule they participate in.", + "tags": [ + "On-call/Schedules" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- `current` carries the shift in progress with its true start time; `next` is the upcoming shift, absent when nothing is scheduled within the lookup window.\n- Disabled schedules are not listed.", + "href": "/en/api-reference/on-call/schedules/schedule-by-person", + "metadata": { + "sidebarTitle": "Get member on-call status" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ScheduleByPersonResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "current": { + "schedule_id": 2539108069860, + "schedule_name": "Open Source Q&A", + "start_at": 1773446400, + "end_at": 1773532799 + }, + "next": { + "schedule_id": 2539108069860, + "schedule_name": "Open Source Q&A", + "start_at": 1773532800, + "end_at": 1773619199 + }, + "schedules": [ + { + "schedule_id": 2539108069860, + "schedule_name": "Open Source Q&A" + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScheduleByPersonRequest" + }, + "example": { + "person_id": 2476444212131 + } + } + } + } + } + }, + "/rum/application/remote-config/get": { + "post": { + "operationId": "rum-application-remote-config-read-get", + "summary": "Get remote config detail", + "description": "Retrieve the live remote configuration of a RUM application and the version it is stored under.", + "tags": [ + "RUM/Applications" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Version `0` means the application has never been configured; SDKs then run entirely on their init values.\n- A change reaches a client when its next session starts unless activation is set to `immediate`.", + "href": "/en/api-reference/rum/applications/rum-application-remote-config-read-get", + "metadata": { + "sidebarTitle": "Get remote config detail" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/GetRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "version": 7, + "updated_at": 1773398630657 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o" + } + } + } + } + } + }, + "/rum/application/remote-config/update": { + "post": { + "operationId": "rum-application-remote-config-write-update", + "summary": "Update remote config", + "description": "Publish a complete new remote configuration version for a RUM application.", + "tags": [ + "RUM/Applications" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- The client sends the complete object, not a patch: rule order is the priority, so a partial update has no unambiguous interpretation.\n- Each call allocates a new version and records a history row in the same transaction as the write.\n- Call `POST /rum/application/remote-config/preview` first to check what clients would receive.", + "href": "/en/api-reference/rum/applications/rum-application-remote-config-write-update", + "metadata": { + "sidebarTitle": "Update remote config" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/UpdateRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "version": 8 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "reason": "Tighten replay sampling for the Q4 launch" + } + } + } + } + } + }, + "/rum/application/remote-config/preview": { + "post": { + "operationId": "rum-application-remote-config-read-preview", + "summary": "Preview remote config", + "description": "Evaluate a draft remote configuration against a client context without publishing it.", + "tags": [ + "RUM/Applications" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Runs the same matcher as the engine, so the result matches what production clients receive.\n- Omit `config` to preview the currently live configuration.", + "href": "/en/api-reference/rum/applications/rum-application-remote-config-read-preview", + "metadata": { + "sidebarTitle": "Preview remote config" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/PreviewRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "values": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + }, + "hit_rule_index": 0 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreviewRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "env": "production", + "app_version": "2.14.3", + "sdk": "web@2.4.1" + } + } + } + } + } + }, + "/rum/application/remote-config/history/list": { + "post": { + "operationId": "rum-application-remote-config-read-history-list", + "summary": "List remote config history", + "description": "List published remote configuration versions of a RUM application.", + "tags": [ + "RUM/Applications" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Newest first by default (`orderby=updated_at`, `asc=false`).\n- `content_hash` and `equivalent_to` identify versions whose content is identical, so the console can say \"this is an earlier version's content\" instead of showing a false difference.", + "href": "/en/api-reference/rum/applications/rum-application-remote-config-read-history-list", + "metadata": { + "sidebarTitle": "List remote config history" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ListRemoteConfigHistoryResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "total": 3, + "has_next_page": false, + "items": [ + { + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "version": 8, + "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", + "reason": "Tighten replay sampling for the Q4 launch", + "updated_by": 4441703362131, + "updated_by_name": "Alice Zhang", + "updated_at": 1773398630657 + }, + { + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "version": 7, + "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", + "reason": "", + "updated_by": 4441703362131, + "updated_by_name": "Alice Zhang", + "updated_at": 1772398630657 + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListRemoteConfigHistoryRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "p": 0, + "limit": 20, + "orderby": "updated_at", + "asc": false + } + } + } + } + } + }, + "/rum/application/remote-config/history/revert": { + "post": { + "operationId": "rum-application-remote-config-write-history-revert", + "summary": "Revert remote config", + "description": "Republish an earlier remote configuration version's content as a new version.", + "tags": [ + "RUM/Applications" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- History is never rewritten: the revert publishes the earlier version's content under a NEW version number.\n- An empty `reason` is filled in by the console as `rolled back to vN`.", + "href": "/en/api-reference/rum/applications/rum-application-remote-config-write-history-revert", + "metadata": { + "sidebarTitle": "Revert remote config" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/RevertRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "version": 9 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevertRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "version": 7, + "reason": "Rolled back after the Q4 launch incident" + } + } + } + } + } } }, "components": { @@ -46763,6 +47359,11 @@ "format": "uint64", "description": "Filter by role ID. Get role IDs from `POST /role/list` (built-in roles: 2=Admin, 6=Responder, 8=Viewer)" }, + "member_id": { + "type": "integer", + "format": "uint64", + "description": "Filter by member ID. Return only the member with this ID." + }, "p": { "type": "integer", "minimum": 1, @@ -60124,502 +60725,922 @@ } } }, - "FeedDetailAlertMerge": { + "FeedDetailAlertMerge": { + "type": "object", + "title": "a_merge", + "description": "Detail payload for `a_merge`: an alert merged into an incident.", + "properties": { + "comment": { + "type": "string", + "description": "Comment recorded with the merge. Omitted when empty." + }, + "target_incident": { + "$ref": "#/components/schemas/IncidentShort", + "description": "Incident the alerts were merged into. Omitted when not recorded." + }, + "source_alerts": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AlertShort" + }, + "description": "Source alerts merged into the target incident. Omitted when empty." + }, + "owner_id": { + "type": "integer", + "format": "int64", + "description": "New owner member ID set on the target incident. Omitted when unchanged." + }, + "title": { + "type": "string", + "description": "New title set on the target incident. Omitted when unchanged." + } + } + }, + "AlertShort": { + "type": "object", + "description": "Brief alert reference.", + "properties": { + "alert_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "Alert ID (ObjectID hex string)." + }, + "title": { + "type": "string", + "description": "Alert title, resolved at read time. Omitted when empty." + } + } + }, + "EventGroup": { + "type": "object", + "description": "Alert event merge configuration. When enabled, repeated incoming events of the same alert are merged into the existing alert within the time window instead of creating new alerts.", + "properties": { + "is_enabled": { + "type": "boolean", + "description": "When true, repeated events merge into the existing alert; when false, every event creates a separate alert. Defaults to true." + }, + "time_window": { + "type": "integer", + "minimum": 1, + "description": "Merge window in minutes, 1-1440 (24 h); accounts with the extended limit may use up to 10080 (7 days). Defaults to 1440." + } + } + }, + "StatusPageInfoResponse": { + "type": "object", + "description": "Status page detail returned by `GET /status-page/info`: the full page configuration plus feature flags.", + "allOf": [ + { + "$ref": "#/components/schemas/StatusPageItem" + }, + { + "type": "object", + "properties": { + "managed_domain_feature_enabled": { + "type": "boolean", + "description": "Whether the managed custom-domain feature is enabled for this page. `true` for public pages, always `false` for internal pages." + } + }, + "required": [ + "managed_domain_feature_enabled" + ] + } + ] + }, + "StatusPagePreDefinedTemplate": { + "type": "object", + "description": "A predefined event template: a reusable draft of an event's title, type, status, and description. In `POST /status-page/template/upsert`, omit `template_id` to create and supply it to update; on update only non-empty fields are applied.", + "properties": { + "template_id": { + "type": "string", + "description": "Template ID. Omit to create a new template; supply to update an existing one." + }, + "title": { + "type": "string", + "description": "Template title." + }, + "type": { + "type": "string", + "enum": [ + "incident", + "maintenance" + ], + "description": "Change type the template applies to: `incident` unplanned incident, `maintenance` planned maintenance." + }, + "status": { + "type": "string", + "enum": [ + "investigating", + "identified", + "monitoring", + "resolved", + "scheduled", + "ongoing", + "completed" + ], + "description": "Change status the template maps to. Incidents use `investigating`/`identified`/`monitoring`/`resolved`; maintenances use `scheduled`/`ongoing`/`completed`." + }, + "description": { + "type": "string", + "description": "Template body text (Markdown)." + } + } + }, + "StatusPageMessageTemplate": { + "type": "object", + "description": "A message template: per-status notification texts for one change type. In `POST /status-page/template/upsert`, omit `template_id` to create and supply it to update; on update only non-empty fields are applied.", + "properties": { + "template_id": { + "type": "string", + "description": "Template ID. Omit to create a new template; supply to update an existing one." + }, + "title": { + "type": "string", + "description": "Template title." + }, + "type": { + "type": "string", + "enum": [ + "incident", + "maintenance" + ], + "description": "Change type the template applies to: `incident` unplanned incident, `maintenance` planned maintenance." + }, + "messages": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Notification text (Markdown) per event status. Keys are change statuses valid for the template's `type` (for example `investigating` or `resolved` for incidents); the value is the text used when the event reaches that status." + } + } + }, + "ListStatusPageTemplatesResponse": { + "type": "object", + "description": "Event template list. Item shape depends on the requested `type`: predefined event templates for `pre_defined`, message templates for `message`.", + "required": [ + "items" + ], + "properties": { + "items": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/StatusPagePreDefinedTemplate" + }, + { + "$ref": "#/components/schemas/StatusPageMessageTemplate" + } + ] + }, + "description": "Templates of the requested category." + } + } + }, + "FeedDetailAlertUpdate": { + "type": "object", + "title": "a_update", + "description": "Detail payload for `a_update`: severity/status after the update.", + "properties": { + "severity": { + "$ref": "#/components/schemas/FeedSeverity" + }, + "status": { + "$ref": "#/components/schemas/FeedSeverity" + } + } + }, + "FeedDetailAlertMuteBySilence": { + "type": "object", + "title": "a_m_silence", + "description": "Detail payload for `a_m_silence`: the alert was muted by a silence rule.", + "properties": { + "rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "Silence rule ID that muted the alert. Omitted when empty." + }, + "rule_name": { + "type": "string", + "description": "Silence rule name, resolved at read time. Omitted when empty." + } + } + }, + "FeedDetailAlertMuteByInhibit": { "type": "object", - "title": "a_merge", - "description": "Detail payload for `a_merge`: an alert merged into an incident.", + "title": "a_m_inhibit", + "description": "Detail payload for `a_m_inhibit`: the alert was inhibited by an inhibit rule because of a source alert.", "properties": { - "comment": { + "rule_id": { "type": "string", - "description": "Comment recorded with the merge. Omitted when empty." + "pattern": "^[0-9a-fA-F]{24}$", + "description": "Inhibit rule ID that muted the alert. Omitted when empty." }, - "target_incident": { - "$ref": "#/components/schemas/IncidentShort", - "description": "Incident the alerts were merged into. Omitted when not recorded." + "rule_name": { + "type": "string", + "description": "Inhibit rule name, resolved at read time. Omitted when empty." }, - "source_alerts": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AlertShort" - }, - "description": "Source alerts merged into the target incident. Omitted when empty." + "source_alert_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "ID of the source alert that triggered the inhibition. Omitted when empty." }, - "owner_id": { + "source_alert_title": { + "type": "string", + "description": "Title of the source alert, resolved at read time. Omitted when empty." + } + } + }, + "FeedDetailAlertMuteByFlapping": { + "type": "object", + "title": "a_m_flapping", + "description": "Detail payload for `a_m_flapping` (historical): the alert was muted by flapping detection.", + "properties": { + "max_changes": { "type": "integer", - "format": "int64", - "description": "New owner member ID set on the target incident. Omitted when unchanged." + "description": "State-change count threshold that triggered flapping detection. Omitted when zero." }, - "title": { - "type": "string", - "description": "New title set on the target incident. Omitted when unchanged." + "in_secs": { + "type": "integer", + "description": "Window in seconds over which the state changes were counted. Omitted when zero." + }, + "mute_secs": { + "type": "integer", + "description": "Mute duration in seconds. Omitted when zero." } } }, - "AlertShort": { + "FeedDetailAlertAck": { "type": "object", - "description": "Brief alert reference.", + "title": "a_ack", + "description": "Detail payload for `a_ack` (historical). No fields.", + "properties": {} + }, + "FeedDetailAlertUnack": { + "type": "object", + "title": "a_unack", + "description": "Detail payload for `a_unack` (historical). No fields.", + "properties": {} + }, + "DSTencentCLSConfig": { + "type": "object", + "description": "Tencent CLS (Cloud Log Service) credential configuration.", + "required": [ + "secret_id" + ], "properties": { - "alert_id": { + "secret_id": { "type": "string", - "pattern": "^[0-9a-fA-F]{24}$", - "description": "Alert ID (ObjectID hex string)." + "description": "Tencent Cloud API SecretId. Always required (create and update). Supports `${env:VAR}` references resolved on the edge." }, - "title": { + "secret_key": { "type": "string", - "description": "Alert title, resolved at read time. Omitted when empty." + "description": "Tencent Cloud API SecretKey. Required on create; on update, omit to keep the stored key. Supports `${env:VAR}` references. Never returned by read APIs: responses carry an empty string unless the stored value is an `${env:...}` reference." } } }, - "EventGroup": { + "SLSProject": { "type": "object", - "description": "Alert event merge configuration. When enabled, repeated incoming events of the same alert are merged into the existing alert within the time window instead of creating new alerts.", + "description": "An Aliyun SLS project.", + "required": [ + "projectName", + "description", + "status", + "owner", + "region", + "createTime", + "lastModifyTime" + ], "properties": { - "is_enabled": { - "type": "boolean", - "description": "When true, repeated events merge into the existing alert; when false, every event creates a separate alert. Defaults to true." + "projectName": { + "type": "string", + "description": "Project name." }, - "time_window": { - "type": "integer", - "minimum": 1, - "description": "Merge window in minutes, 1-1440 (24 h); accounts with the extended limit may use up to 10080 (7 days). Defaults to 1440." + "description": { + "type": "string", + "description": "Project description." + }, + "status": { + "type": "string", + "description": "Project status, e.g. `Normal`." + }, + "owner": { + "type": "string", + "description": "Owner Aliyun account ID; empty when not returned by SLS." + }, + "region": { + "type": "string", + "description": "Region ID, e.g. `cn-shanghai`." + }, + "createTime": { + "type": "string", + "description": "Creation time, Unix seconds rendered as a string, e.g. `\"1524539357\"`." + }, + "lastModifyTime": { + "type": "string", + "description": "Last modification time, Unix seconds rendered as a string." + }, + "dataRedundancyType": { + "type": "string", + "enum": [ + "LRS", + "ZRS" + ], + "description": "Data redundancy type: `LRS` = locally redundant storage, `ZRS` = zone-redundant storage. Omitted when not set." + }, + "location": { + "type": "string", + "description": "Storage location, e.g. `cn-beijing-b`. Omitted when not set." } } }, - "StatusPageInfoResponse": { + "StringMapPatch": { "type": "object", - "description": "Status page detail returned by `GET /status-page/info`: the full page configuration plus feature flags.", - "allOf": [ - { - "$ref": "#/components/schemas/StatusPageItem" - }, - { + "description": "Partial update for a map field: keys in `set` are inserted or replaced, keys in `delete` are removed, all other keys are preserved.", + "properties": { + "set": { "type": "object", - "properties": { - "managed_domain_feature_enabled": { - "type": "boolean", - "description": "Whether the managed custom-domain feature is enabled for this page. `true` for public pages, always `false` for internal pages." - } + "additionalProperties": { + "type": "string" }, - "required": [ - "managed_domain_feature_enabled" - ] + "description": "Keys to insert or replace." + }, + "delete": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Keys to remove." } - ] + } }, - "StatusPagePreDefinedTemplate": { + "TargetInventoryServiceMapCapability": { "type": "object", - "description": "A predefined event template: a reusable draft of an event's title, type, status, and description. In `POST /status-page/template/upsert`, omit `template_id` to create and supply it to update; on update only non-empty fields are applied.", + "description": "ServiceMap capability and live status of a target's host.", + "required": [ + "enabled", + "status", + "snapshot_ready", + "authoritative", + "graph_available", + "node_count", + "edge_count" + ], "properties": { - "template_id": { + "enabled": { + "type": "boolean", + "description": "Whether ServiceMap collection is enabled on the agent." + }, + "status": { "type": "string", - "description": "Template ID. Omit to create a new template; supply to update an existing one." + "enum": [ + "active", + "degraded", + "stale", + "initializing", + "disabled", + "unsupported", + "no_data" + ], + "description": "ServiceMap collection status of the host.\n\n| Value | Meaning |\n|---|---|\n| `active` | Collection healthy: a fresh snapshot exists with no degradation. |\n| `degraded` | Collecting but quality is impaired: health reports are newer than the snapshot, the snapshot is truncated/degraded, or collection is failing. |\n| `stale` | A snapshot exists but is outdated (no update within 2x the report interval). |\n| `initializing` | The agent reported the capability but the first snapshot is not ready yet. |\n| `disabled` | Topology collection is disabled on this host. |\n| `unsupported` | The agent or kernel does not support collection. |\n| `no_data` | No snapshot or health data received yet. |" }, - "title": { + "capability_status": { "type": "string", - "description": "Template title." + "description": "Agent-reported capability status, e.g. `running`, `disabled`, `starting`, `failed`, `unsupported`. Omitted when the agent has not reported one." + }, + "capture_mode": { + "type": "string", + "description": "Capture mode, e.g. `ebpf` or `polling`. Omitted when unknown." + }, + "report_interval_ms": { + "type": "integer", + "format": "int64", + "description": "Configured reporting interval in milliseconds. Omitted when unknown." + }, + "snapshot_ready": { + "type": "boolean", + "description": "True if the agent has produced at least one full snapshot." + }, + "authoritative": { + "type": "boolean", + "description": "True if the current status derives from an authoritative graph snapshot." + }, + "graph_available": { + "type": "boolean", + "description": "True if a current graph can be fetched for this host right now." + }, + "freshness_status": { + "type": "string", + "enum": [ + "fresh", + "stale", + "unknown" + ], + "description": "Freshness classification of the host's graph. `fresh` = the latest snapshot was received within 2x the report interval; `stale` = no new snapshot within that window; `unknown` = not yet classified. Omitted when unknown." + }, + "max_age_ms": { + "type": "integer", + "format": "int64", + "description": "Maximum snapshot age in milliseconds tolerated before it counts as stale. Omitted when not applicable." + }, + "observed_at_ms": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in milliseconds when the agent last observed graph generation. Omitted when unknown." + }, + "received_at_ms": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp in milliseconds when the server last received a snapshot. Omitted when unknown." }, - "type": { - "type": "string", - "enum": [ - "incident", - "maintenance" - ], - "description": "Change type the template applies to: `incident` unplanned incident, `maintenance` planned maintenance." + "node_count": { + "type": "integer", + "description": "Number of nodes in the host's current graph." }, - "status": { - "type": "string", - "enum": [ - "investigating", - "identified", - "monitoring", - "resolved", - "scheduled", - "ongoing", - "completed" - ], - "description": "Change status the template maps to. Incidents use `investigating`/`identified`/`monitoring`/`resolved`; maintenances use `scheduled`/`ongoing`/`completed`." + "edge_count": { + "type": "integer", + "description": "Number of edges in the host's current graph." }, - "description": { + "reason_codes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Machine-readable codes explaining the current capability status. Omitted when empty." + }, + "error_code": { "type": "string", - "description": "Template body text (Markdown)." + "description": "Set to `status_unavailable` when the live status could not be read; other fields then fall back to inventory-derived values. Omitted otherwise." } } }, - "StatusPageMessageTemplate": { + "TargetInventoryServiceMapCoverage": { "type": "object", - "description": "A message template: per-status notification texts for one change type. In `POST /status-page/template/upsert`, omit `template_id` to create and supply it to update; on update only non-empty fields are applied.", + "description": "ServiceMap status-fetch coverage for a targets page.", + "required": [ + "requested", + "succeeded", + "failed", + "partial" + ], "properties": { - "template_id": { - "type": "string", - "description": "Template ID. Omit to create a new template; supply to update an existing one." + "requested": { + "type": "integer", + "description": "Items on this page that carry ServiceMap data." }, - "title": { - "type": "string", - "description": "Template title." + "succeeded": { + "type": "integer", + "description": "Items whose live ServiceMap status was read successfully." }, - "type": { - "type": "string", - "enum": [ - "incident", - "maintenance" - ], - "description": "Change type the template applies to: `incident` unplanned incident, `maintenance` planned maintenance." + "failed": { + "type": "integer", + "description": "Items whose live ServiceMap status read failed (`servicemap.error_code` set)." }, - "messages": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "Notification text (Markdown) per event status. Keys are change statuses valid for the template's `type` (for example `investigating` or `resolved` for incidents); the value is the text used when the event reaches that status." + "partial": { + "type": "boolean", + "description": "True when at least one item's status read failed." } } }, - "ListStatusPageTemplatesResponse": { + "RoleDeleteRequest": { "type": "object", - "description": "Event template list. Item shape depends on the requested `type`: predefined event templates for `pre_defined`, message templates for `message`.", "required": [ - "items" + "role_id" ], + "description": "Request to delete a role.", "properties": { - "items": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/StatusPagePreDefinedTemplate" - }, - { - "$ref": "#/components/schemas/StatusPageMessageTemplate" - } - ] - }, - "description": "Templates of the requested category." + "role_id": { + "type": "integer", + "format": "uint64", + "description": "Role ID to delete. Get IDs from `POST /role/list` (built-in roles: 2=Admin, 6=Responder, 8=Viewer)." + }, + "is_force": { + "type": "boolean", + "default": false, + "description": "When false (default), deletion fails with a `ReferenceExist` error listing the members that still hold the role in `data.refs`. When true, the role is first revoked from all holders and then deleted." } } }, - "FeedDetailAlertUpdate": { + "ScheduleByPersonRequest": { "type": "object", - "title": "a_update", - "description": "Detail payload for `a_update`: severity/status after the update.", + "description": "Member on-call status request", "properties": { - "severity": { - "$ref": "#/components/schemas/FeedSeverity" + "person_id": { + "type": "integer", + "description": "Member ID whose on-call status is returned.", + "format": "int64" + } + }, + "required": [ + "person_id" + ] + }, + "ScheduleByPersonResponse": { + "type": "object", + "description": "The member's on-call status: the shift in progress, the next one, and every enabled schedule they participate in.", + "properties": { + "current": { + "$ref": "#/components/schemas/MemberOncallInterval" }, - "status": { - "$ref": "#/components/schemas/FeedSeverity" + "next": { + "$ref": "#/components/schemas/MemberOncallInterval" + }, + "schedules": { + "type": "array", + "description": "All enabled schedules the member participates in.", + "items": { + "$ref": "#/components/schemas/MemberScheduleItem" + } } - } + }, + "required": [ + "schedules" + ] }, - "FeedDetailAlertMuteBySilence": { + "MemberScheduleItem": { "type": "object", - "title": "a_m_silence", - "description": "Detail payload for `a_m_silence`: the alert was muted by a silence rule.", + "description": "An enabled schedule the member participates in.", "properties": { - "rule_id": { - "type": "string", - "pattern": "^[0-9a-fA-F]{24}$", - "description": "Silence rule ID that muted the alert. Omitted when empty." + "schedule_id": { + "type": "integer", + "description": "Schedule ID.", + "format": "int64" }, - "rule_name": { + "schedule_name": { "type": "string", - "description": "Silence rule name, resolved at read time. Omitted when empty." + "description": "Schedule name." } } }, - "FeedDetailAlertMuteByInhibit": { + "MemberOncallInterval": { "type": "object", - "title": "a_m_inhibit", - "description": "Detail payload for `a_m_inhibit`: the alert was inhibited by an inhibit rule because of a source alert.", + "description": "One on-call shift interval of a member.", "properties": { - "rule_id": { - "type": "string", - "pattern": "^[0-9a-fA-F]{24}$", - "description": "Inhibit rule ID that muted the alert. Omitted when empty." + "schedule_id": { + "type": "integer", + "description": "Owning schedule ID.", + "format": "int64" }, - "rule_name": { + "schedule_name": { "type": "string", - "description": "Inhibit rule name, resolved at read time. Omitted when empty." + "description": "Owning schedule name." }, - "source_alert_id": { - "type": "string", - "pattern": "^[0-9a-fA-F]{24}$", - "description": "ID of the source alert that triggered the inhibition. Omitted when empty." + "start_at": { + "type": "integer", + "description": "Unix timestamp in seconds - when the shift starts.", + "format": "int64" }, - "source_alert_title": { - "type": "string", - "description": "Title of the source alert, resolved at read time. Omitted when empty." + "end_at": { + "type": "integer", + "description": "Unix timestamp in seconds - when the shift ends. Absent while the shift is ongoing.", + "format": "int64" } } }, - "FeedDetailAlertMuteByFlapping": { + "UpdateRemoteConfigRequest": { "type": "object", - "title": "a_m_flapping", - "description": "Detail payload for `a_m_flapping` (historical): the alert was muted by flapping detection.", + "description": "Publish a whole new remote configuration version. The client sends the complete object, not a patch: rule order carries meaning.", "properties": { - "max_changes": { - "type": "integer", - "description": "State-change count threshold that triggered flapping detection. Omitted when zero." + "application_id": { + "type": "string", + "description": "RUM application ID." }, - "in_secs": { - "type": "integer", - "description": "Window in seconds over which the state changes were counted. Omitted when zero." + "config": { + "$ref": "#/components/schemas/RemoteConfig" }, - "mute_secs": { + "reason": { + "type": "string", + "description": "Operator's note on why this version was published. Stored verbatim.", + "maxLength": 255 + } + }, + "required": [ + "application_id", + "config" + ] + }, + "UpdateRemoteConfigResponse": { + "type": "object", + "description": "Version allocated to the published configuration.", + "properties": { + "version": { "type": "integer", - "description": "Mute duration in seconds. Omitted when zero." + "description": "New published version number." } } }, - "FeedDetailAlertAck": { + "ListRemoteConfigHistoryResponse": { "type": "object", - "title": "a_ack", - "description": "Detail payload for `a_ack` (historical). No fields.", - "properties": {} + "description": "Remote configuration history page.", + "properties": { + "total": { + "type": "integer", + "description": "Total number of versions." + }, + "has_next_page": { + "type": "boolean", + "description": "Whether more pages remain." + }, + "items": { + "type": "array", + "description": "Version items, newest first by default.", + "items": { + "$ref": "#/components/schemas/RemoteConfigHistoryItem" + } + } + } }, - "FeedDetailAlertUnack": { + "RevertRemoteConfigResponse": { "type": "object", - "title": "a_unack", - "description": "Detail payload for `a_unack` (historical). No fields.", - "properties": {} + "description": "Version created by the revert.", + "properties": { + "version": { + "type": "integer", + "description": "New version number created by the revert." + } + } }, - "DSTencentCLSConfig": { + "RemoteConfigValues": { "type": "object", - "description": "Tencent CLS (Cloud Log Service) credential configuration.", - "required": [ - "secret_id" - ], + "description": "The SDK knobs a configuration can set. Every field is optional: a value absent from both rule and default is omitted from the SDK response, which tells the SDK to keep its init value.", "properties": { - "secret_id": { - "type": "string", - "description": "Tencent Cloud API SecretId. Always required (create and update). Supports `${env:VAR}` references resolved on the edge." + "sessionSampleRate": { + "type": [ + "integer", + "null" + ], + "description": "Session sampling rate (0-100).", + "minimum": 0, + "maximum": 100 }, - "secret_key": { - "type": "string", - "description": "Tencent Cloud API SecretKey. Required on create; on update, omit to keep the stored key. Supports `${env:VAR}` references. Never returned by read APIs: responses carry an empty string unless the stored value is an `${env:...}` reference." + "sessionReplaySampleRate": { + "type": [ + "integer", + "null" + ], + "description": "Session Replay sampling rate (0-100).", + "minimum": 0, + "maximum": 100 + }, + "traceSampleRate": { + "type": [ + "integer", + "null" + ], + "description": "Trace sampling rate (0-100): which sessions inject trace headers into their requests.", + "minimum": 0, + "maximum": 100 + }, + "defaultPrivacyLevel": { + "type": [ + "string", + "null" + ], + "description": "How Session Replay masks a page by default.", + "enum": [ + "mask", + "mask-user-input", + "allow" + ] } } }, - "SLSProject": { + "RemoteConfigHistoryItem": { "type": "object", - "description": "An Aliyun SLS project.", - "required": [ - "projectName", - "description", - "status", - "owner", - "region", - "createTime", - "lastModifyTime" - ], + "description": "One published remote configuration version.", "properties": { - "projectName": { - "type": "string", - "description": "Project name." + "config": { + "$ref": "#/components/schemas/RemoteConfig" }, - "description": { - "type": "string", - "description": "Project description." + "version": { + "type": "integer", + "description": "Version number, unique within the application." }, - "status": { + "content_hash": { "type": "string", - "description": "Project status, e.g. `Normal`." + "description": "Hash of the configuration content; lets the console identify versions with identical content." }, - "owner": { + "equivalent_to": { + "type": "integer", + "description": "Earliest version carrying the same content, when that is not this version itself." + }, + "reason": { "type": "string", - "description": "Owner Aliyun account ID; empty when not returned by SLS." + "description": "Operator's note left when the version was published. Empty when none was given." }, - "region": { + "updated_by": { + "type": "integer", + "description": "ID of the member who published the version.", + "format": "int64" + }, + "updated_by_name": { "type": "string", - "description": "Region ID, e.g. `cn-shanghai`." + "description": "Name of the member who published the version." }, - "createTime": { + "updated_at": { + "type": "integer", + "description": "Unix timestamp in milliseconds - when the version was published.", + "format": "int64" + } + } + }, + "PreviewRemoteConfigRequest": { + "type": "object", + "description": "Preview request. Omit `config` to preview the currently live configuration.", + "properties": { + "application_id": { "type": "string", - "description": "Creation time, Unix seconds rendered as a string, e.g. `\"1524539357\"`." + "description": "RUM application ID." }, - "lastModifyTime": { + "config": { + "$ref": "#/components/schemas/RemoteConfig" + }, + "env": { "type": "string", - "description": "Last modification time, Unix seconds rendered as a string." + "description": "Environment the simulated client reports." }, - "dataRedundancyType": { + "app_version": { "type": "string", - "enum": [ - "LRS", - "ZRS" - ], - "description": "Data redundancy type: `LRS` = locally redundant storage, `ZRS` = zone-redundant storage. Omitted when not set." + "description": "App version the simulated client reports." }, - "location": { + "sdk": { "type": "string", - "description": "Storage location, e.g. `cn-beijing-b`. Omitted when not set." + "description": "SDK name and version the simulated client reports, e.g. `web@2.4.1`." } - } + }, + "required": [ + "application_id" + ] }, - "StringMapPatch": { + "RemoteConfigRule": { "type": "object", - "description": "Partial update for a map field: keys in `set` are inserted or replaced, keys in `delete` are removed, all other keys are preserved.", + "description": "One targeting rule: when `match` holds, `set` overrides `default`. The first matching rule wins and evaluation stops there - rule order is the priority.", "properties": { - "set": { + "match": { "type": "object", + "description": "Key/value conditions the SDK's config request must equal. Keys are limited to `env`, `app_version` and `sdk`; values are at most 256 bytes.", + "minProperties": 1, "additionalProperties": { - "type": "string" - }, - "description": "Keys to insert or replace." + "type": "string", + "maxLength": 256 + } }, - "delete": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Keys to remove." + "set": { + "$ref": "#/components/schemas/RemoteConfigValues" } - } + }, + "required": [ + "match", + "set" + ] }, - "TargetInventoryServiceMapCapability": { + "GetRemoteConfigRequest": { "type": "object", - "description": "ServiceMap capability and live status of a target's host.", + "description": "Get remote config request", + "properties": { + "application_id": { + "type": "string", + "description": "RUM application ID." + } + }, "required": [ - "enabled", - "status", - "snapshot_ready", - "authoritative", - "graph_available", - "node_count", - "edge_count" - ], + "application_id" + ] + }, + "RemoteConfig": { + "type": "object", + "description": "The whole per-application remote configuration. A change reaches an SDK asynchronously and is applied when that SDK creates its next session, so a running session never flips a decision mid-flight.", "properties": { "enabled": { "type": "boolean", - "description": "Whether ServiceMap collection is enabled on the agent." + "description": "Kill switch. When false the engine reports no values at all and SDKs fall back to their init values." }, - "status": { + "activation": { "type": "string", + "description": "How a change lands on a client that is already running. Empty means `next_session`.", "enum": [ - "active", - "degraded", - "stale", - "initializing", - "disabled", - "unsupported", - "no_data" + "next_session", + "immediate" ], - "description": "ServiceMap collection status of the host.\n\n| Value | Meaning |\n|---|---|\n| `active` | Collection healthy: a fresh snapshot exists with no degradation. |\n| `degraded` | Collecting but quality is impaired: health reports are newer than the snapshot, the snapshot is truncated/degraded, or collection is failing. |\n| `stale` | A snapshot exists but is outdated (no update within 2x the report interval). |\n| `initializing` | The agent reported the capability but the first snapshot is not ready yet. |\n| `disabled` | Topology collection is disabled on this host. |\n| `unsupported` | The agent or kernel does not support collection. |\n| `no_data` | No snapshot or health data received yet. |" - }, - "capability_status": { - "type": "string", - "description": "Agent-reported capability status, e.g. `running`, `disabled`, `starting`, `failed`, `unsupported`. Omitted when the agent has not reported one." - }, - "capture_mode": { - "type": "string", - "description": "Capture mode, e.g. `ebpf` or `polling`. Omitted when unknown." - }, - "report_interval_ms": { - "type": "integer", - "format": "int64", - "description": "Configured reporting interval in milliseconds. Omitted when unknown." + "default": "next_session" }, - "snapshot_ready": { + "refresh_on_foreground": { "type": "boolean", - "description": "True if the agent has produced at least one full snapshot." + "description": "Let clients re-check the configuration when they return to the foreground instead of waiting for the next poll." }, - "authoritative": { - "type": "boolean", - "description": "True if the current status derives from an authoritative graph snapshot." + "default": { + "$ref": "#/components/schemas/RemoteConfigValues" }, - "graph_available": { - "type": "boolean", - "description": "True if a current graph can be fetched for this host right now." + "rules": { + "type": "array", + "description": "Targeting rules, evaluated in order; at most 20 per application.", + "maxItems": 20, + "items": { + "$ref": "#/components/schemas/RemoteConfigRule" + } }, - "freshness_status": { + "custom": { + "type": "object", + "description": "Application-defined pass-through values handed to the host app verbatim. At most 5 keys, each key up to 64 bytes, each value up to 4 KB of JSON nested at most 3 levels, 16 KB in total. Anyone holding the public client token can read it.", + "maxProperties": 5, + "additionalProperties": {} + } + } + }, + "RevertRemoteConfigRequest": { + "type": "object", + "description": "Republish an earlier version's content under a new version number.", + "properties": { + "application_id": { "type": "string", - "enum": [ - "fresh", - "stale", - "unknown" - ], - "description": "Freshness classification of the host's graph. `fresh` = the latest snapshot was received within 2x the report interval; `stale` = no new snapshot within that window; `unknown` = not yet classified. Omitted when unknown." - }, - "max_age_ms": { - "type": "integer", - "format": "int64", - "description": "Maximum snapshot age in milliseconds tolerated before it counts as stale. Omitted when not applicable." - }, - "observed_at_ms": { - "type": "integer", - "format": "int64", - "description": "Unix timestamp in milliseconds when the agent last observed graph generation. Omitted when unknown." + "description": "RUM application ID." }, - "received_at_ms": { + "version": { "type": "integer", - "format": "int64", - "description": "Unix timestamp in milliseconds when the server last received a snapshot. Omitted when unknown." + "description": "History version to republish.", + "minimum": 1 }, - "node_count": { - "type": "integer", - "description": "Number of nodes in the host's current graph." + "reason": { + "type": "string", + "description": "Operator's note. The console fills in `rolled back to vN` when left empty.", + "maxLength": 255 + } + }, + "required": [ + "application_id", + "version" + ] + }, + "PreviewRemoteConfigResponse": { + "type": "object", + "description": "Values the simulated client would receive.", + "properties": { + "values": { + "$ref": "#/components/schemas/RemoteConfigValues" }, - "edge_count": { + "hit_rule_index": { "type": "integer", - "description": "Number of edges in the host's current graph." - }, - "reason_codes": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Machine-readable codes explaining the current capability status. Omitted when empty." - }, - "error_code": { - "type": "string", - "description": "Set to `status_unavailable` when the live status could not be read; other fields then fall back to inventory-derived values. Omitted otherwise." + "description": "0-based index of the rule that decided the result, or -1 when only the default applied." } } }, - "TargetInventoryServiceMapCoverage": { + "GetRemoteConfigResponse": { "type": "object", - "description": "ServiceMap status-fetch coverage for a targets page.", - "required": [ - "requested", - "succeeded", - "failed", - "partial" - ], + "description": "Live remote configuration and its version.", "properties": { - "requested": { - "type": "integer", - "description": "Items on this page that carry ServiceMap data." + "config": { + "$ref": "#/components/schemas/RemoteConfig" }, - "succeeded": { + "version": { "type": "integer", - "description": "Items whose live ServiceMap status was read successfully." + "description": "Version the live configuration is stored under. 0 means the application has never been configured." }, - "failed": { + "updated_at": { "type": "integer", - "description": "Items whose live ServiceMap status read failed (`servicemap.error_code` set)." - }, - "partial": { - "type": "boolean", - "description": "True when at least one item's status read failed." + "description": "Unix timestamp in milliseconds - when the current version was published. 0 when never configured.", + "format": "int64" } } }, - "RoleDeleteRequest": { + "ListRemoteConfigHistoryRequest": { "type": "object", - "required": [ - "role_id" - ], - "description": "Request to delete a role.", + "description": "Remote configuration history request. Newest first by default.", "properties": { - "role_id": { + "application_id": { + "type": "string", + "description": "RUM application ID." + }, + "p": { "type": "integer", - "format": "uint64", - "description": "Role ID to delete. Get IDs from `POST /role/list` (built-in roles: 2=Admin, 6=Responder, 8=Viewer)." + "description": "Zero-based page index; offset is p multiplied by limit.", + "minimum": 0, + "maximum": 100000, + "default": 0 }, - "is_force": { + "limit": { + "type": "integer", + "description": "Page size. Default 20, max 100.", + "default": 20, + "maximum": 100 + }, + "orderby": { + "type": "string", + "description": "Sort field. Default: `updated_at`.", + "enum": [ + "updated_at", + "version" + ], + "default": "updated_at" + }, + "asc": { "type": "boolean", - "default": false, - "description": "When false (default), deletion fails with a `ReferenceExist` error listing the members that still hold the role in `data.refs`. When true, the role is first revoked from all holders and then deleted." + "description": "Ascending order. Default: false (descending)." } - } + }, + "required": [ + "application_id" + ] } } } diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 16fd93a4..bc3284ac 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -30814,6 +30814,602 @@ } } } + }, + "/schedule/by-person": { + "post": { + "operationId": "scheduleByPerson", + "summary": "查看成员值班状态", + "description": "查看某成员正在值班的班次、下一次值班以及其参与的全部启用排班。", + "tags": [ + "On-call/值班排班" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |\n\n## 使用说明\n\n- `current` 为正在值班的班次（含真实开始时间）；`next` 为下一次值班，查询窗口内没有排班时缺省。\n- 已禁用的排班不会出现在列表中。", + "href": "/zh/api-reference/on-call/schedules/schedule-by-person", + "metadata": { + "sidebarTitle": "查看成员值班状态" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ScheduleByPersonResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "current": { + "schedule_id": 2539108069860, + "schedule_name": "Open Source Q&A", + "start_at": 1773446400, + "end_at": 1773532799 + }, + "next": { + "schedule_id": 2539108069860, + "schedule_name": "Open Source Q&A", + "start_at": 1773532800, + "end_at": 1773619199 + }, + "schedules": [ + { + "schedule_id": 2539108069860, + "schedule_name": "Open Source Q&A" + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScheduleByPersonRequest" + }, + "example": { + "person_id": 2476444212131 + } + } + } + } + } + }, + "/rum/application/remote-config/get": { + "post": { + "operationId": "rum-application-remote-config-read-get", + "summary": "查看远程配置详情", + "description": "获取 RUM 应用当前生效的远程配置及其版本号。", + "tags": [ + "RUM/应用管理" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `version` 为 `0` 表示该应用从未配置过远程配置，SDK 完全沿用初始化值。\n- 变更在客户端下一次会话开始时生效（`activation` 为 `immediate` 时立即生效）。", + "href": "/zh/api-reference/rum/applications/rum-application-remote-config-read-get", + "metadata": { + "sidebarTitle": "查看远程配置详情" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/GetRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "version": 7, + "updated_at": 1773398630657 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o" + } + } + } + } + } + }, + "/rum/application/remote-config/update": { + "post": { + "operationId": "rum-application-remote-config-write-update", + "summary": "更新远程配置", + "description": "为 RUM 应用发布一个全新的远程配置版本。", + "tags": [ + "RUM/应用管理" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 必须提交完整配置对象而非增量补丁——规则顺序即优先级，部分更新没有无歧义的解释。\n- 每次调用都会分配新版本号，并在同一事务中写入历史记录。\n- 发布前可先调用 `POST /rum/application/remote-config/preview` 验证客户端将拿到的值。", + "href": "/zh/api-reference/rum/applications/rum-application-remote-config-write-update", + "metadata": { + "sidebarTitle": "更新远程配置" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/UpdateRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "version": 8 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "reason": "Q4 上线前收紧回放采样" + } + } + } + } + } + }, + "/rum/application/remote-config/preview": { + "post": { + "operationId": "rum-application-remote-config-read-preview", + "summary": "预览远程配置", + "description": "在不发布的情况下评估一份草稿远程配置在给定客户端上下文下的效果。", + "tags": [ + "RUM/应用管理" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用与引擎完全相同的匹配逻辑，结果与生产客户端实际获取一致。\n- 省略 `config` 时预览当前生效配置。", + "href": "/zh/api-reference/rum/applications/rum-application-remote-config-read-preview", + "metadata": { + "sidebarTitle": "预览远程配置" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/PreviewRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "values": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + }, + "hit_rule_index": 0 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreviewRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "env": "production", + "app_version": "2.14.3", + "sdk": "web@2.4.1" + } + } + } + } + } + }, + "/rum/application/remote-config/history/list": { + "post": { + "operationId": "rum-application-remote-config-read-history-list", + "summary": "查询远程配置历史列表", + "description": "查询 RUM 应用已发布的远程配置版本列表。", + "tags": [ + "RUM/应用管理" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 默认按更新时间倒序（`orderby=updated_at`，`asc=false`）。\n- 内容相同的版本通过 `content_hash` 与 `equivalent_to` 标识，控制台据此提示\"这是某历史版本的相同内容\"。", + "href": "/zh/api-reference/rum/applications/rum-application-remote-config-read-history-list", + "metadata": { + "sidebarTitle": "查询远程配置历史列表" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ListRemoteConfigHistoryResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "total": 3, + "has_next_page": false, + "items": [ + { + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "version": 8, + "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", + "reason": "Q4 上线前收紧回放采样", + "updated_by": 4441703362131, + "updated_by_name": "Alice Zhang", + "updated_at": 1773398630657 + }, + { + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "version": 7, + "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", + "reason": "", + "updated_by": 4441703362131, + "updated_by_name": "Alice Zhang", + "updated_at": 1772398630657 + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListRemoteConfigHistoryRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "p": 0, + "limit": 20, + "orderby": "updated_at", + "asc": false + } + } + } + } + } + }, + "/rum/application/remote-config/history/revert": { + "post": { + "operationId": "rum-application-remote-config-write-history-revert", + "summary": "回滚远程配置版本", + "description": "将某个历史版本的远程配置内容重新发布为新版本。", + "tags": [ + "RUM/应用管理" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 回滚不会重写历史：旧版本内容会以新的版本号发布。\n- `reason` 留空时控制台会自动填入\"rolled back to vN\"。", + "href": "/zh/api-reference/rum/applications/rum-application-remote-config-write-history-revert", + "metadata": { + "sidebarTitle": "回滚远程配置版本" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/RevertRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "version": 9 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevertRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "version": 7, + "reason": "Q4 上线故障后回滚" + } + } + } + } + } } }, "components": { @@ -46763,6 +47359,11 @@ "format": "uint64", "description": "按角色 ID 过滤，角色 ID 可通过 `POST /role/list` 获取（内置角色：2=Admin、6=Responder、8=Viewer）" }, + "member_id": { + "type": "integer", + "format": "uint64", + "description": "按成员 ID 过滤，仅返回该成员。" + }, "p": { "type": "integer", "minimum": 1, @@ -60124,502 +60725,922 @@ } } }, - "FeedDetailAlertMerge": { + "FeedDetailAlertMerge": { + "type": "object", + "title": "a_merge", + "description": "`a_merge` 的详情数据：告警被合并到故障。", + "properties": { + "comment": { + "type": "string", + "description": "合并时记录的评论。为空时不返回。" + }, + "target_incident": { + "$ref": "#/components/schemas/IncidentShort", + "description": "告警合并到的目标故障。未记录时不返回。" + }, + "source_alerts": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AlertShort" + }, + "description": "被合并进目标故障的源告警。为空时不返回。" + }, + "owner_id": { + "type": "integer", + "format": "int64", + "description": "目标故障被设置的新负责人成员 ID。未变更时不返回。" + }, + "title": { + "type": "string", + "description": "目标故障被设置的新标题。未变更时不返回。" + } + } + }, + "AlertShort": { + "type": "object", + "description": "告警简要引用。", + "properties": { + "alert_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "告警 ID（ObjectID 十六进制字符串）。" + }, + "title": { + "type": "string", + "description": "告警标题，读取时解析填充。为空时不返回。" + } + } + }, + "EventGroup": { + "type": "object", + "description": "告警事件合并配置。启用后，同一告警的重复事件会在时间窗口内并入已有告警，而不是新建告警。", + "properties": { + "is_enabled": { + "type": "boolean", + "description": "为 true 时，重复事件并入已有告警；为 false 时，每个事件都单独生成告警。默认为 true。" + }, + "time_window": { + "type": "integer", + "minimum": 1, + "description": "合并窗口，单位分钟，范围 1-1440（24 小时）；开通扩展额度的账号最大可设 10080（7 天）。默认 1440。" + } + } + }, + "StatusPageInfoResponse": { + "type": "object", + "description": "`GET /status-page/info` 返回的状态页详情：完整页面配置及特性开关。", + "allOf": [ + { + "$ref": "#/components/schemas/StatusPageItem" + }, + { + "type": "object", + "properties": { + "managed_domain_feature_enabled": { + "type": "boolean", + "description": "该页面是否启用托管自定义域名特性。公开页面为 `true`，内部页面恒为 `false`。" + } + }, + "required": [ + "managed_domain_feature_enabled" + ] + } + ] + }, + "StatusPagePreDefinedTemplate": { + "type": "object", + "description": "预定义事件模板：可复用的事件草稿（标题、类型、状态、描述）。在 `POST /status-page/template/upsert` 中，省略 `template_id` 表示创建，提供则表示更新；更新时仅应用非空字段。", + "properties": { + "template_id": { + "type": "string", + "description": "模板 ID。省略表示创建新模板；提供表示更新已有模板。" + }, + "title": { + "type": "string", + "description": "模板标题。" + }, + "type": { + "type": "string", + "enum": [ + "incident", + "maintenance" + ], + "description": "模板适用的事件类型：`incident` 故障，`maintenance` 计划维护。" + }, + "status": { + "type": "string", + "enum": [ + "investigating", + "identified", + "monitoring", + "resolved", + "scheduled", + "ongoing", + "completed" + ], + "description": "模板对应的事件状态。故障事件支持 `investigating`/`identified`/`monitoring`/`resolved`；维护事件支持 `scheduled`/`ongoing`/`completed`。" + }, + "description": { + "type": "string", + "description": "模板正文（Markdown）。" + } + } + }, + "StatusPageMessageTemplate": { + "type": "object", + "description": "消息模板：某一事件类型下、按状态划分的通知文案。在 `POST /status-page/template/upsert` 中，省略 `template_id` 表示创建，提供则表示更新；更新时仅应用非空字段。", + "properties": { + "template_id": { + "type": "string", + "description": "模板 ID。省略表示创建新模板；提供表示更新已有模板。" + }, + "title": { + "type": "string", + "description": "模板标题。" + }, + "type": { + "type": "string", + "enum": [ + "incident", + "maintenance" + ], + "description": "模板适用的事件类型：`incident` 故障，`maintenance` 计划维护。" + }, + "messages": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "按事件状态划分的通知文案（Markdown）。键为与模板 `type` 匹配的事件状态（如故障事件的 `investigating`、`resolved`），值为事件进入该状态时使用的文本。" + } + } + }, + "ListStatusPageTemplatesResponse": { + "type": "object", + "description": "事件模板列表。条目结构取决于请求的 `type`：`pre_defined` 为预定义事件模板，`message` 为消息模板。", + "required": [ + "items" + ], + "properties": { + "items": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/StatusPagePreDefinedTemplate" + }, + { + "$ref": "#/components/schemas/StatusPageMessageTemplate" + } + ] + }, + "description": "所请求类别的模板列表。" + } + } + }, + "FeedDetailAlertUpdate": { + "type": "object", + "title": "a_update", + "description": "`a_update` 的详情数据：更新后的严重程度/状态。", + "properties": { + "severity": { + "$ref": "#/components/schemas/FeedSeverity" + }, + "status": { + "$ref": "#/components/schemas/FeedSeverity" + } + } + }, + "FeedDetailAlertMuteBySilence": { + "type": "object", + "title": "a_m_silence", + "description": "`a_m_silence` 的详情数据：告警被静默规则收敛。", + "properties": { + "rule_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "收敛该告警的静默规则 ID。为空时不返回。" + }, + "rule_name": { + "type": "string", + "description": "静默规则名称，读取时解析填充。为空时不返回。" + } + } + }, + "FeedDetailAlertMuteByInhibit": { "type": "object", - "title": "a_merge", - "description": "`a_merge` 的详情数据：告警被合并到故障。", + "title": "a_m_inhibit", + "description": "`a_m_inhibit` 的详情数据：告警因源告警被抑制规则收敛。", "properties": { - "comment": { + "rule_id": { "type": "string", - "description": "合并时记录的评论。为空时不返回。" + "pattern": "^[0-9a-fA-F]{24}$", + "description": "收敛该告警的抑制规则 ID。为空时不返回。" }, - "target_incident": { - "$ref": "#/components/schemas/IncidentShort", - "description": "告警合并到的目标故障。未记录时不返回。" + "rule_name": { + "type": "string", + "description": "抑制规则名称，读取时解析填充。为空时不返回。" }, - "source_alerts": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AlertShort" - }, - "description": "被合并进目标故障的源告警。为空时不返回。" + "source_alert_id": { + "type": "string", + "pattern": "^[0-9a-fA-F]{24}$", + "description": "触发抑制的源告警 ID。为空时不返回。" }, - "owner_id": { + "source_alert_title": { + "type": "string", + "description": "源告警标题，读取时解析填充。为空时不返回。" + } + } + }, + "FeedDetailAlertMuteByFlapping": { + "type": "object", + "title": "a_m_flapping", + "description": "`a_m_flapping` 的详情数据（历史）：告警被抖动检测收敛。", + "properties": { + "max_changes": { "type": "integer", - "format": "int64", - "description": "目标故障被设置的新负责人成员 ID。未变更时不返回。" + "description": "触发抖动检测的状态变化次数阈值。为 0 时不返回。" }, - "title": { - "type": "string", - "description": "目标故障被设置的新标题。未变更时不返回。" + "in_secs": { + "type": "integer", + "description": "统计状态变化的时间窗口（秒）。为 0 时不返回。" + }, + "mute_secs": { + "type": "integer", + "description": "静默时长（秒）。为 0 时不返回。" } } }, - "AlertShort": { + "FeedDetailAlertAck": { "type": "object", - "description": "告警简要引用。", + "title": "a_ack", + "description": "`a_ack` 的详情数据（历史），无字段。", + "properties": {} + }, + "FeedDetailAlertUnack": { + "type": "object", + "title": "a_unack", + "description": "`a_unack` 的详情数据（历史），无字段。", + "properties": {} + }, + "DSTencentCLSConfig": { + "type": "object", + "description": "腾讯云日志服务（CLS）凭证配置。", + "required": [ + "secret_id" + ], "properties": { - "alert_id": { + "secret_id": { "type": "string", - "pattern": "^[0-9a-fA-F]{24}$", - "description": "告警 ID（ObjectID 十六进制字符串）。" + "description": "腾讯云 API SecretId，创建和更新时均必填。支持 `${env:VAR}` 引用（在 edge 侧解析）。" }, - "title": { + "secret_key": { "type": "string", - "description": "告警标题，读取时解析填充。为空时不返回。" + "description": "腾讯云 API SecretKey。创建时必填；更新时省略则保留已存储的密钥。支持 `${env:VAR}` 引用。读取接口永不返回该值：响应中为空字符串，除非存储的值是 `${env:...}` 引用。" } } }, - "EventGroup": { + "SLSProject": { "type": "object", - "description": "告警事件合并配置。启用后，同一告警的重复事件会在时间窗口内并入已有告警，而不是新建告警。", + "description": "一个阿里云 SLS 项目。", + "required": [ + "projectName", + "description", + "status", + "owner", + "region", + "createTime", + "lastModifyTime" + ], "properties": { - "is_enabled": { - "type": "boolean", - "description": "为 true 时，重复事件并入已有告警；为 false 时，每个事件都单独生成告警。默认为 true。" + "projectName": { + "type": "string", + "description": "项目名称。" }, - "time_window": { - "type": "integer", - "minimum": 1, - "description": "合并窗口，单位分钟，范围 1-1440（24 小时）；开通扩展额度的账号最大可设 10080（7 天）。默认 1440。" + "description": { + "type": "string", + "description": "项目描述。" + }, + "status": { + "type": "string", + "description": "项目状态，例如 `Normal`。" + }, + "owner": { + "type": "string", + "description": "项目属主的阿里云账户 ID；SLS 未返回时为空。" + }, + "region": { + "type": "string", + "description": "地域 ID，例如 `cn-shanghai`。" + }, + "createTime": { + "type": "string", + "description": "创建时间，以字符串表示的 Unix 秒，例如 `\"1524539357\"`。" + }, + "lastModifyTime": { + "type": "string", + "description": "最后修改时间，以字符串表示的 Unix 秒。" + }, + "dataRedundancyType": { + "type": "string", + "enum": [ + "LRS", + "ZRS" + ], + "description": "数据冗余类型：`LRS` = 本地冗余存储，`ZRS` = 同城冗余存储。未设置时不返回。" + }, + "location": { + "type": "string", + "description": "存储位置，例如 `cn-beijing-b`。未设置时不返回。" } } }, - "StatusPageInfoResponse": { + "StringMapPatch": { "type": "object", - "description": "`GET /status-page/info` 返回的状态页详情：完整页面配置及特性开关。", - "allOf": [ - { - "$ref": "#/components/schemas/StatusPageItem" - }, - { + "description": "map 字段的增量更新：`set` 中的键会被插入或覆盖，`delete` 中的键会被删除，其余键保持不变。", + "properties": { + "set": { "type": "object", - "properties": { - "managed_domain_feature_enabled": { - "type": "boolean", - "description": "该页面是否启用托管自定义域名特性。公开页面为 `true`，内部页面恒为 `false`。" - } + "additionalProperties": { + "type": "string" }, - "required": [ - "managed_domain_feature_enabled" - ] + "description": "要插入或覆盖的键值对。" + }, + "delete": { + "type": "array", + "items": { + "type": "string" + }, + "description": "要删除的键。" } - ] + } }, - "StatusPagePreDefinedTemplate": { + "TargetInventoryServiceMapCapability": { "type": "object", - "description": "预定义事件模板：可复用的事件草稿（标题、类型、状态、描述）。在 `POST /status-page/template/upsert` 中，省略 `template_id` 表示创建，提供则表示更新；更新时仅应用非空字段。", + "description": "目标主机的 ServiceMap 采集能力与实时状态。", + "required": [ + "enabled", + "status", + "snapshot_ready", + "authoritative", + "graph_available", + "node_count", + "edge_count" + ], "properties": { - "template_id": { + "enabled": { + "type": "boolean", + "description": "agent 是否启用了 ServiceMap 采集。" + }, + "status": { "type": "string", - "description": "模板 ID。省略表示创建新模板；提供表示更新已有模板。" + "enum": [ + "active", + "degraded", + "stale", + "initializing", + "disabled", + "unsupported", + "no_data" + ], + "description": "主机的 ServiceMap 采集状态。\n\n| 值 | 含义 |\n|---|---|\n| `active` | 采集正常：有新鲜快照且无降级。 |\n| `degraded` | 采集在进行但质量受损：健康上报晚于快照、快照被截断/降级，或采集报错。 |\n| `stale` | 有快照但已过期（超过 2× 上报间隔未更新）。 |\n| `initializing` | Agent 已上报采集能力，但首个快照尚未就绪。 |\n| `disabled` | 该主机的拓扑采集被禁用。 |\n| `unsupported` | Agent 或内核不支持该采集。 |\n| `no_data` | 未收到任何快照或健康数据。 |" }, - "title": { + "capability_status": { "type": "string", - "description": "模板标题。" + "description": "agent 上报的能力状态，例如 `running`、`disabled`、`starting`、`failed`、`unsupported`。agent 未上报时不返回。" + }, + "capture_mode": { + "type": "string", + "description": "采集模式，例如 `ebpf` 或 `polling`。未知时不返回。" + }, + "report_interval_ms": { + "type": "integer", + "format": "int64", + "description": "配置的上报间隔（毫秒）。未知时不返回。" + }, + "snapshot_ready": { + "type": "boolean", + "description": "agent 是否已产出至少一份完整快照。" + }, + "authoritative": { + "type": "boolean", + "description": "当前状态是否来自权威（authoritative）图快照。" + }, + "graph_available": { + "type": "boolean", + "description": "当前是否可以拉取到该主机的实时拓扑图。" + }, + "freshness_status": { + "type": "string", + "enum": [ + "fresh", + "stale", + "unknown" + ], + "description": "主机拓扑图的新鲜度分类。`fresh` = 最新快照在 2× 上报间隔内收到；`stale` = 超过该窗口未收到新快照；`unknown` = 尚未分类。未知时不返回。" + }, + "max_age_ms": { + "type": "integer", + "format": "int64", + "description": "快照被视为过期前可容忍的最大年龄（毫秒）。不适用时不返回。" + }, + "observed_at_ms": { + "type": "integer", + "format": "int64", + "description": "agent 最近一次观测到图生成的时间，Unix 毫秒时间戳。未知时不返回。" + }, + "received_at_ms": { + "type": "integer", + "format": "int64", + "description": "服务端最近一次收到快照的时间，Unix 毫秒时间戳。未知时不返回。" }, - "type": { - "type": "string", - "enum": [ - "incident", - "maintenance" - ], - "description": "模板适用的事件类型：`incident` 故障，`maintenance` 计划维护。" + "node_count": { + "type": "integer", + "description": "该主机当前拓扑图中的节点数。" }, - "status": { - "type": "string", - "enum": [ - "investigating", - "identified", - "monitoring", - "resolved", - "scheduled", - "ongoing", - "completed" - ], - "description": "模板对应的事件状态。故障事件支持 `investigating`/`identified`/`monitoring`/`resolved`；维护事件支持 `scheduled`/`ongoing`/`completed`。" + "edge_count": { + "type": "integer", + "description": "该主机当前拓扑图中的边数。" }, - "description": { + "reason_codes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "解释当前能力状态的机器可读原因码。为空时不返回。" + }, + "error_code": { "type": "string", - "description": "模板正文（Markdown）。" + "description": "实时状态读取失败时置为 `status_unavailable`，此时其余字段回退为清单侧的值。否则不返回。" } } }, - "StatusPageMessageTemplate": { + "TargetInventoryServiceMapCoverage": { "type": "object", - "description": "消息模板：某一事件类型下、按状态划分的通知文案。在 `POST /status-page/template/upsert` 中，省略 `template_id` 表示创建，提供则表示更新；更新时仅应用非空字段。", + "description": "某一页目标的 ServiceMap 状态拉取覆盖情况。", + "required": [ + "requested", + "succeeded", + "failed", + "partial" + ], "properties": { - "template_id": { - "type": "string", - "description": "模板 ID。省略表示创建新模板；提供表示更新已有模板。" + "requested": { + "type": "integer", + "description": "本页携带 ServiceMap 数据的条目数。" }, - "title": { - "type": "string", - "description": "模板标题。" + "succeeded": { + "type": "integer", + "description": "实时 ServiceMap 状态读取成功的条目数。" }, - "type": { - "type": "string", - "enum": [ - "incident", - "maintenance" - ], - "description": "模板适用的事件类型：`incident` 故障，`maintenance` 计划维护。" + "failed": { + "type": "integer", + "description": "实时 ServiceMap 状态读取失败的条目数（`servicemap.error_code` 已设置）。" }, - "messages": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "按事件状态划分的通知文案（Markdown）。键为与模板 `type` 匹配的事件状态（如故障事件的 `investigating`、`resolved`），值为事件进入该状态时使用的文本。" + "partial": { + "type": "boolean", + "description": "至少一个条目状态读取失败时为 true。" } } }, - "ListStatusPageTemplatesResponse": { + "RoleDeleteRequest": { "type": "object", - "description": "事件模板列表。条目结构取决于请求的 `type`：`pre_defined` 为预定义事件模板，`message` 为消息模板。", "required": [ - "items" + "role_id" ], + "description": "删除角色请求。", "properties": { - "items": { - "type": "array", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/StatusPagePreDefinedTemplate" - }, - { - "$ref": "#/components/schemas/StatusPageMessageTemplate" - } - ] - }, - "description": "所请求类别的模板列表。" + "role_id": { + "type": "integer", + "format": "uint64", + "description": "要删除的角色 ID。可通过 `POST /role/list` 获取（内置角色：2=Admin，6=Responder，8=Viewer）。" + }, + "is_force": { + "type": "boolean", + "default": false, + "description": "为 false（默认）时，若仍有成员持有该角色，删除失败并返回 `ReferenceExist` 错误，`data.refs` 中列出持有成员；为 true 时先从所有持有成员解除该角色，再删除角色。" } } }, - "FeedDetailAlertUpdate": { + "ScheduleByPersonRequest": { "type": "object", - "title": "a_update", - "description": "`a_update` 的详情数据：更新后的严重程度/状态。", + "description": "成员值班状态查询请求", "properties": { - "severity": { - "$ref": "#/components/schemas/FeedSeverity" + "person_id": { + "type": "integer", + "description": "要查询值班状态的成员 ID。", + "format": "int64" + } + }, + "required": [ + "person_id" + ] + }, + "ScheduleByPersonResponse": { + "type": "object", + "description": "成员的值班状态：正在值班的班次、下一次值班，以及其参与的全部启用排班。", + "properties": { + "current": { + "$ref": "#/components/schemas/MemberOncallInterval" }, - "status": { - "$ref": "#/components/schemas/FeedSeverity" + "next": { + "$ref": "#/components/schemas/MemberOncallInterval" + }, + "schedules": { + "type": "array", + "description": "该成员参与的全部启用排班。", + "items": { + "$ref": "#/components/schemas/MemberScheduleItem" + } } - } + }, + "required": [ + "schedules" + ] }, - "FeedDetailAlertMuteBySilence": { + "MemberScheduleItem": { "type": "object", - "title": "a_m_silence", - "description": "`a_m_silence` 的详情数据：告警被静默规则收敛。", + "description": "该成员参与的一个启用中的排班。", "properties": { - "rule_id": { - "type": "string", - "pattern": "^[0-9a-fA-F]{24}$", - "description": "收敛该告警的静默规则 ID。为空时不返回。" + "schedule_id": { + "type": "integer", + "description": "排班 ID。", + "format": "int64" }, - "rule_name": { + "schedule_name": { "type": "string", - "description": "静默规则名称，读取时解析填充。为空时不返回。" + "description": "排班名称。" } } }, - "FeedDetailAlertMuteByInhibit": { + "MemberOncallInterval": { "type": "object", - "title": "a_m_inhibit", - "description": "`a_m_inhibit` 的详情数据：告警因源告警被抑制规则收敛。", + "description": "成员的一个值班班次区间。", "properties": { - "rule_id": { - "type": "string", - "pattern": "^[0-9a-fA-F]{24}$", - "description": "收敛该告警的抑制规则 ID。为空时不返回。" + "schedule_id": { + "type": "integer", + "description": "所属排班 ID。", + "format": "int64" }, - "rule_name": { + "schedule_name": { "type": "string", - "description": "抑制规则名称，读取时解析填充。为空时不返回。" + "description": "所属排班名称。" }, - "source_alert_id": { - "type": "string", - "pattern": "^[0-9a-fA-F]{24}$", - "description": "触发抑制的源告警 ID。为空时不返回。" + "start_at": { + "type": "integer", + "description": "Unix 时间戳（秒）—— 班次开始时间。", + "format": "int64" }, - "source_alert_title": { - "type": "string", - "description": "源告警标题，读取时解析填充。为空时不返回。" + "end_at": { + "type": "integer", + "description": "Unix 时间戳（秒）—— 班次结束时间。值班进行中时缺省。", + "format": "int64" } } }, - "FeedDetailAlertMuteByFlapping": { + "UpdateRemoteConfigRequest": { "type": "object", - "title": "a_m_flapping", - "description": "`a_m_flapping` 的详情数据（历史）：告警被抖动检测收敛。", + "description": "发布一个全新的远程配置版本。客户端需提交完整对象而非增量补丁：规则顺序承载语义。", "properties": { - "max_changes": { - "type": "integer", - "description": "触发抖动检测的状态变化次数阈值。为 0 时不返回。" + "application_id": { + "type": "string", + "description": "RUM 应用 ID。" }, - "in_secs": { - "type": "integer", - "description": "统计状态变化的时间窗口（秒）。为 0 时不返回。" + "config": { + "$ref": "#/components/schemas/RemoteConfig" }, - "mute_secs": { + "reason": { + "type": "string", + "description": "操作者留下的发布说明，原样保存。", + "maxLength": 255 + } + }, + "required": [ + "application_id", + "config" + ] + }, + "UpdateRemoteConfigResponse": { + "type": "object", + "description": "本次发布分配到的版本号。", + "properties": { + "version": { "type": "integer", - "description": "静默时长（秒）。为 0 时不返回。" + "description": "新发布的版本号。" } } }, - "FeedDetailAlertAck": { + "ListRemoteConfigHistoryResponse": { "type": "object", - "title": "a_ack", - "description": "`a_ack` 的详情数据（历史），无字段。", - "properties": {} + "description": "远程配置历史分页结果。", + "properties": { + "total": { + "type": "integer", + "description": "版本总数。" + }, + "has_next_page": { + "type": "boolean", + "description": "是否还有下一页。" + }, + "items": { + "type": "array", + "description": "版本列表，默认最新在前。", + "items": { + "$ref": "#/components/schemas/RemoteConfigHistoryItem" + } + } + } }, - "FeedDetailAlertUnack": { + "RevertRemoteConfigResponse": { "type": "object", - "title": "a_unack", - "description": "`a_unack` 的详情数据（历史），无字段。", - "properties": {} + "description": "回滚创建的版本。", + "properties": { + "version": { + "type": "integer", + "description": "回滚生成的新的版本号。" + } + } }, - "DSTencentCLSConfig": { + "RemoteConfigValues": { "type": "object", - "description": "腾讯云日志服务（CLS）凭证配置。", - "required": [ - "secret_id" - ], + "description": "配置可设置的 SDK 参数。每个字段都是可选的：规则与默认值都未设置的字段不会出现在 SDK 响应中，SDK 将沿用初始化值。", "properties": { - "secret_id": { - "type": "string", - "description": "腾讯云 API SecretId，创建和更新时均必填。支持 `${env:VAR}` 引用（在 edge 侧解析）。" + "sessionSampleRate": { + "type": [ + "integer", + "null" + ], + "description": "会话采样率（0-100）。", + "minimum": 0, + "maximum": 100 }, - "secret_key": { - "type": "string", - "description": "腾讯云 API SecretKey。创建时必填；更新时省略则保留已存储的密钥。支持 `${env:VAR}` 引用。读取接口永不返回该值：响应中为空字符串，除非存储的值是 `${env:...}` 引用。" + "sessionReplaySampleRate": { + "type": [ + "integer", + "null" + ], + "description": "Session Replay 采样率（0-100）。", + "minimum": 0, + "maximum": 100 + }, + "traceSampleRate": { + "type": [ + "integer", + "null" + ], + "description": "Trace 采样率（0-100）：哪些会话会在请求中注入 Trace 头。", + "minimum": 0, + "maximum": 100 + }, + "defaultPrivacyLevel": { + "type": [ + "string", + "null" + ], + "description": "Session Replay 默认的页面脱敏方式。", + "enum": [ + "mask", + "mask-user-input", + "allow" + ] } } }, - "SLSProject": { + "RemoteConfigHistoryItem": { "type": "object", - "description": "一个阿里云 SLS 项目。", - "required": [ - "projectName", - "description", - "status", - "owner", - "region", - "createTime", - "lastModifyTime" - ], + "description": "一个已发布的远程配置版本。", "properties": { - "projectName": { - "type": "string", - "description": "项目名称。" + "config": { + "$ref": "#/components/schemas/RemoteConfig" }, - "description": { - "type": "string", - "description": "项目描述。" + "version": { + "type": "integer", + "description": "版本号，在应用内唯一。" }, - "status": { + "content_hash": { "type": "string", - "description": "项目状态，例如 `Normal`。" + "description": "配置内容的哈希；控制台用它识别内容相同的版本。" }, - "owner": { + "equivalent_to": { + "type": "integer", + "description": "与本版本内容相同的最早版本号（当不是本版本自身时返回）。" + }, + "reason": { "type": "string", - "description": "项目属主的阿里云账户 ID；SLS 未返回时为空。" + "description": "发布该版本时操作者留下的说明，未填写则为空。" }, - "region": { + "updated_by": { + "type": "integer", + "description": "发布该版本的成员 ID。", + "format": "int64" + }, + "updated_by_name": { "type": "string", - "description": "地域 ID，例如 `cn-shanghai`。" + "description": "发布该版本的成员名称。" }, - "createTime": { + "updated_at": { + "type": "integer", + "description": "Unix 时间戳（毫秒）—— 版本发布时间。", + "format": "int64" + } + } + }, + "PreviewRemoteConfigRequest": { + "type": "object", + "description": "预览请求。省略 `config` 时预览当前生效配置。", + "properties": { + "application_id": { "type": "string", - "description": "创建时间，以字符串表示的 Unix 秒，例如 `\"1524539357\"`。" + "description": "RUM 应用 ID。" }, - "lastModifyTime": { + "config": { + "$ref": "#/components/schemas/RemoteConfig" + }, + "env": { "type": "string", - "description": "最后修改时间，以字符串表示的 Unix 秒。" + "description": "模拟客户端上报的环境。" }, - "dataRedundancyType": { + "app_version": { "type": "string", - "enum": [ - "LRS", - "ZRS" - ], - "description": "数据冗余类型：`LRS` = 本地冗余存储，`ZRS` = 同城冗余存储。未设置时不返回。" + "description": "模拟客户端上报的应用版本。" }, - "location": { + "sdk": { "type": "string", - "description": "存储位置，例如 `cn-beijing-b`。未设置时不返回。" + "description": "模拟客户端上报的 SDK 名称与版本，如 `web@2.4.1`。" } - } + }, + "required": [ + "application_id" + ] }, - "StringMapPatch": { + "RemoteConfigRule": { "type": "object", - "description": "map 字段的增量更新：`set` 中的键会被插入或覆盖，`delete` 中的键会被删除，其余键保持不变。", + "description": "单条定向规则：当 `match` 条件满足时，`set` 覆盖 `default`。规则按顺序评估，第一条命中的规则生效——规则顺序即优先级。", "properties": { - "set": { + "match": { "type": "object", + "description": "SDK 配置请求必须相等的键值对。键仅支持 `env`、`app_version`、`sdk`；值最长 256 字节。", + "minProperties": 1, "additionalProperties": { - "type": "string" - }, - "description": "要插入或覆盖的键值对。" + "type": "string", + "maxLength": 256 + } }, - "delete": { - "type": "array", - "items": { - "type": "string" - }, - "description": "要删除的键。" + "set": { + "$ref": "#/components/schemas/RemoteConfigValues" } - } + }, + "required": [ + "match", + "set" + ] }, - "TargetInventoryServiceMapCapability": { + "GetRemoteConfigRequest": { "type": "object", - "description": "目标主机的 ServiceMap 采集能力与实时状态。", + "description": "获取远程配置请求", + "properties": { + "application_id": { + "type": "string", + "description": "RUM 应用 ID。" + } + }, "required": [ - "enabled", - "status", - "snapshot_ready", - "authoritative", - "graph_available", - "node_count", - "edge_count" - ], + "application_id" + ] + }, + "RemoteConfig": { + "type": "object", + "description": "单个应用的完整远程配置。变更异步到达 SDK，并在其创建下一个会话时生效，正在进行的会话不会被中途改变。", "properties": { "enabled": { "type": "boolean", - "description": "agent 是否启用了 ServiceMap 采集。" + "description": "总开关。为 false 时引擎不下发任何值，SDK 沿用初始化值。" }, - "status": { + "activation": { "type": "string", + "description": "变更如何作用于已在运行的客户端。留空表示 `next_session`。", "enum": [ - "active", - "degraded", - "stale", - "initializing", - "disabled", - "unsupported", - "no_data" + "next_session", + "immediate" ], - "description": "主机的 ServiceMap 采集状态。\n\n| 值 | 含义 |\n|---|---|\n| `active` | 采集正常：有新鲜快照且无降级。 |\n| `degraded` | 采集在进行但质量受损：健康上报晚于快照、快照被截断/降级，或采集报错。 |\n| `stale` | 有快照但已过期（超过 2× 上报间隔未更新）。 |\n| `initializing` | Agent 已上报采集能力，但首个快照尚未就绪。 |\n| `disabled` | 该主机的拓扑采集被禁用。 |\n| `unsupported` | Agent 或内核不支持该采集。 |\n| `no_data` | 未收到任何快照或健康数据。 |" - }, - "capability_status": { - "type": "string", - "description": "agent 上报的能力状态，例如 `running`、`disabled`、`starting`、`failed`、`unsupported`。agent 未上报时不返回。" - }, - "capture_mode": { - "type": "string", - "description": "采集模式，例如 `ebpf` 或 `polling`。未知时不返回。" - }, - "report_interval_ms": { - "type": "integer", - "format": "int64", - "description": "配置的上报间隔（毫秒）。未知时不返回。" + "default": "next_session" }, - "snapshot_ready": { + "refresh_on_foreground": { "type": "boolean", - "description": "agent 是否已产出至少一份完整快照。" + "description": "允许客户端回到前台时重新拉取配置，而不是等待下一次轮询。" }, - "authoritative": { - "type": "boolean", - "description": "当前状态是否来自权威（authoritative）图快照。" + "default": { + "$ref": "#/components/schemas/RemoteConfigValues" }, - "graph_available": { - "type": "boolean", - "description": "当前是否可以拉取到该主机的实时拓扑图。" + "rules": { + "type": "array", + "description": "定向规则，按顺序评估；每个应用最多 20 条。", + "maxItems": 20, + "items": { + "$ref": "#/components/schemas/RemoteConfigRule" + } }, - "freshness_status": { + "custom": { + "type": "object", + "description": "应用自定义的透传值，原样下发给宿主应用。最多 5 个键，键长不超过 64 字节，单值不超过 4 KB JSON 且嵌套不超过 3 层，总计不超过 16 KB。持有公开 client token 的任何人都能读到它。", + "maxProperties": 5, + "additionalProperties": {} + } + } + }, + "RevertRemoteConfigRequest": { + "type": "object", + "description": "将历史版本的内容重新发布为新的版本号。", + "properties": { + "application_id": { "type": "string", - "enum": [ - "fresh", - "stale", - "unknown" - ], - "description": "主机拓扑图的新鲜度分类。`fresh` = 最新快照在 2× 上报间隔内收到；`stale` = 超过该窗口未收到新快照；`unknown` = 尚未分类。未知时不返回。" - }, - "max_age_ms": { - "type": "integer", - "format": "int64", - "description": "快照被视为过期前可容忍的最大年龄（毫秒）。不适用时不返回。" - }, - "observed_at_ms": { - "type": "integer", - "format": "int64", - "description": "agent 最近一次观测到图生成的时间，Unix 毫秒时间戳。未知时不返回。" + "description": "RUM 应用 ID。" }, - "received_at_ms": { + "version": { "type": "integer", - "format": "int64", - "description": "服务端最近一次收到快照的时间，Unix 毫秒时间戳。未知时不返回。" + "description": "要重新发布的历史版本号。", + "minimum": 1 }, - "node_count": { - "type": "integer", - "description": "该主机当前拓扑图中的节点数。" + "reason": { + "type": "string", + "description": "操作者说明。控制台留空时会自动填入 `rolled back to vN`。", + "maxLength": 255 + } + }, + "required": [ + "application_id", + "version" + ] + }, + "PreviewRemoteConfigResponse": { + "type": "object", + "description": "模拟客户端将拿到的配置值。", + "properties": { + "values": { + "$ref": "#/components/schemas/RemoteConfigValues" }, - "edge_count": { + "hit_rule_index": { "type": "integer", - "description": "该主机当前拓扑图中的边数。" - }, - "reason_codes": { - "type": "array", - "items": { - "type": "string" - }, - "description": "解释当前能力状态的机器可读原因码。为空时不返回。" - }, - "error_code": { - "type": "string", - "description": "实时状态读取失败时置为 `status_unavailable`，此时其余字段回退为清单侧的值。否则不返回。" + "description": "决定结果的规则下标（从 0 开始）；仅命中默认值时为 -1。" } } }, - "TargetInventoryServiceMapCoverage": { + "GetRemoteConfigResponse": { "type": "object", - "description": "某一页目标的 ServiceMap 状态拉取覆盖情况。", - "required": [ - "requested", - "succeeded", - "failed", - "partial" - ], + "description": "当前生效的远程配置及其版本。", "properties": { - "requested": { - "type": "integer", - "description": "本页携带 ServiceMap 数据的条目数。" + "config": { + "$ref": "#/components/schemas/RemoteConfig" }, - "succeeded": { + "version": { "type": "integer", - "description": "实时 ServiceMap 状态读取成功的条目数。" + "description": "当前配置的版本号。0 表示该应用从未配置过远程配置。" }, - "failed": { + "updated_at": { "type": "integer", - "description": "实时 ServiceMap 状态读取失败的条目数（`servicemap.error_code` 已设置）。" - }, - "partial": { - "type": "boolean", - "description": "至少一个条目状态读取失败时为 true。" + "description": "Unix 时间戳（毫秒）—— 当前版本发布时间。从未配置时为 0。", + "format": "int64" } } }, - "RoleDeleteRequest": { + "ListRemoteConfigHistoryRequest": { "type": "object", - "required": [ - "role_id" - ], - "description": "删除角色请求。", + "description": "远程配置历史查询请求。默认按最新在前排序。", "properties": { - "role_id": { + "application_id": { + "type": "string", + "description": "RUM 应用 ID。" + }, + "p": { "type": "integer", - "format": "uint64", - "description": "要删除的角色 ID。可通过 `POST /role/list` 获取（内置角色：2=Admin，6=Responder，8=Viewer）。" + "description": "从 0 开始的页码；偏移量为 p 乘以 limit。", + "minimum": 0, + "maximum": 100000, + "default": 0 }, - "is_force": { + "limit": { + "type": "integer", + "description": "每页条数。默认 20，最大 100。", + "default": 20, + "maximum": 100 + }, + "orderby": { + "type": "string", + "description": "排序字段。默认 `updated_at`。", + "enum": [ + "updated_at", + "version" + ], + "default": "updated_at" + }, + "asc": { "type": "boolean", - "default": false, - "description": "为 false（默认）时，若仍有成员持有该角色，删除失败并返回 `ReferenceExist` 错误，`data.refs` 中列出持有成员；为 true 时先从所有持有成员解除该角色，再删除角色。" + "description": "是否升序。默认 false（倒序）。" } - } + }, + "required": [ + "application_id" + ] } } } diff --git a/api-reference/platform.openapi.en.json b/api-reference/platform.openapi.en.json index 13853021..dba4d0ea 100644 --- a/api-reference/platform.openapi.en.json +++ b/api-reference/platform.openapi.en.json @@ -3146,6 +3146,11 @@ "format": "uint64", "description": "Filter by role ID. Get role IDs from `POST /role/list` (built-in roles: 2=Admin, 6=Responder, 8=Viewer)" }, + "member_id": { + "type": "integer", + "format": "uint64", + "description": "Filter by member ID. Return only the member with this ID." + }, "p": { "type": "integer", "minimum": 1, diff --git a/api-reference/platform.openapi.zh.json b/api-reference/platform.openapi.zh.json index 4a9bd54c..11f433c7 100644 --- a/api-reference/platform.openapi.zh.json +++ b/api-reference/platform.openapi.zh.json @@ -3146,6 +3146,11 @@ "format": "uint64", "description": "按角色 ID 过滤，角色 ID 可通过 `POST /role/list` 获取（内置角色：2=Admin、6=Responder、8=Viewer）" }, + "member_id": { + "type": "integer", + "format": "uint64", + "description": "按成员 ID 过滤，仅返回该成员。" + }, "p": { "type": "integer", "minimum": 1, diff --git a/api-reference/rum.openapi.en.json b/api-reference/rum.openapi.en.json index 0b6404ca..f1e5b6d0 100644 --- a/api-reference/rum.openapi.en.json +++ b/api-reference/rum.openapi.en.json @@ -3552,6 +3552,513 @@ } } } + }, + "/rum/application/remote-config/get": { + "post": { + "operationId": "rum-application-remote-config-read-get", + "summary": "Get remote config detail", + "description": "Retrieve the live remote configuration of a RUM application and the version it is stored under.", + "tags": [ + "RUM/Applications" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Version `0` means the application has never been configured; SDKs then run entirely on their init values.\n- A change reaches a client when its next session starts unless activation is set to `immediate`.", + "href": "/en/api-reference/rum/applications/rum-application-remote-config-read-get", + "metadata": { + "sidebarTitle": "Get remote config detail" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/GetRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "version": 7, + "updated_at": 1773398630657 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o" + } + } + } + } + } + }, + "/rum/application/remote-config/update": { + "post": { + "operationId": "rum-application-remote-config-write-update", + "summary": "Update remote config", + "description": "Publish a complete new remote configuration version for a RUM application.", + "tags": [ + "RUM/Applications" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- The client sends the complete object, not a patch: rule order is the priority, so a partial update has no unambiguous interpretation.\n- Each call allocates a new version and records a history row in the same transaction as the write.\n- Call `POST /rum/application/remote-config/preview` first to check what clients would receive.", + "href": "/en/api-reference/rum/applications/rum-application-remote-config-write-update", + "metadata": { + "sidebarTitle": "Update remote config" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/UpdateRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "version": 8 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "reason": "Tighten replay sampling for the Q4 launch" + } + } + } + } + } + }, + "/rum/application/remote-config/preview": { + "post": { + "operationId": "rum-application-remote-config-read-preview", + "summary": "Preview remote config", + "description": "Evaluate a draft remote configuration against a client context without publishing it.", + "tags": [ + "RUM/Applications" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Runs the same matcher as the engine, so the result matches what production clients receive.\n- Omit `config` to preview the currently live configuration.", + "href": "/en/api-reference/rum/applications/rum-application-remote-config-read-preview", + "metadata": { + "sidebarTitle": "Preview remote config" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/PreviewRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "values": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + }, + "hit_rule_index": 0 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreviewRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "env": "production", + "app_version": "2.14.3", + "sdk": "web@2.4.1" + } + } + } + } + } + }, + "/rum/application/remote-config/history/list": { + "post": { + "operationId": "rum-application-remote-config-read-history-list", + "summary": "List remote config history", + "description": "List published remote configuration versions of a RUM application.", + "tags": [ + "RUM/Applications" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Newest first by default (`orderby=updated_at`, `asc=false`).\n- `content_hash` and `equivalent_to` identify versions whose content is identical, so the console can say \"this is an earlier version's content\" instead of showing a false difference.", + "href": "/en/api-reference/rum/applications/rum-application-remote-config-read-history-list", + "metadata": { + "sidebarTitle": "List remote config history" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ListRemoteConfigHistoryResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "total": 3, + "has_next_page": false, + "items": [ + { + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "version": 8, + "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", + "reason": "Tighten replay sampling for the Q4 launch", + "updated_by": 4441703362131, + "updated_by_name": "Alice Zhang", + "updated_at": 1773398630657 + }, + { + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "version": 7, + "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", + "reason": "", + "updated_by": 4441703362131, + "updated_by_name": "Alice Zhang", + "updated_at": 1772398630657 + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListRemoteConfigHistoryRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "p": 0, + "limit": 20, + "orderby": "updated_at", + "asc": false + } + } + } + } + } + }, + "/rum/application/remote-config/history/revert": { + "post": { + "operationId": "rum-application-remote-config-write-history-revert", + "summary": "Revert remote config", + "description": "Republish an earlier remote configuration version's content as a new version.", + "tags": [ + "RUM/Applications" + ], + "x-mint": { + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- History is never rewritten: the revert publishes the earlier version's content under a NEW version number.\n- An empty `reason` is filled in by the console as `rolled back to vN`.", + "href": "/en/api-reference/rum/applications/rum-application-remote-config-write-history-revert", + "metadata": { + "sidebarTitle": "Revert remote config" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/RevertRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "version": 9 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevertRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "version": 7, + "reason": "Rolled back after the Q4 launch incident" + } + } + } + } + } } }, "components": { @@ -7157,6 +7664,350 @@ "description": "Unix timestamp in seconds when the on-premises license expires. Only present on on-premises deployments; omitted entirely for SaaS accounts." } } + }, + "UpdateRemoteConfigRequest": { + "type": "object", + "description": "Publish a whole new remote configuration version. The client sends the complete object, not a patch: rule order carries meaning.", + "properties": { + "application_id": { + "type": "string", + "description": "RUM application ID." + }, + "config": { + "$ref": "#/components/schemas/RemoteConfig" + }, + "reason": { + "type": "string", + "description": "Operator's note on why this version was published. Stored verbatim.", + "maxLength": 255 + } + }, + "required": [ + "application_id", + "config" + ] + }, + "UpdateRemoteConfigResponse": { + "type": "object", + "description": "Version allocated to the published configuration.", + "properties": { + "version": { + "type": "integer", + "description": "New published version number." + } + } + }, + "ListRemoteConfigHistoryResponse": { + "type": "object", + "description": "Remote configuration history page.", + "properties": { + "total": { + "type": "integer", + "description": "Total number of versions." + }, + "has_next_page": { + "type": "boolean", + "description": "Whether more pages remain." + }, + "items": { + "type": "array", + "description": "Version items, newest first by default.", + "items": { + "$ref": "#/components/schemas/RemoteConfigHistoryItem" + } + } + } + }, + "RevertRemoteConfigResponse": { + "type": "object", + "description": "Version created by the revert.", + "properties": { + "version": { + "type": "integer", + "description": "New version number created by the revert." + } + } + }, + "RemoteConfigValues": { + "type": "object", + "description": "The SDK knobs a configuration can set. Every field is optional: a value absent from both rule and default is omitted from the SDK response, which tells the SDK to keep its init value.", + "properties": { + "sessionSampleRate": { + "type": [ + "integer", + "null" + ], + "description": "Session sampling rate (0-100).", + "minimum": 0, + "maximum": 100 + }, + "sessionReplaySampleRate": { + "type": [ + "integer", + "null" + ], + "description": "Session Replay sampling rate (0-100).", + "minimum": 0, + "maximum": 100 + }, + "traceSampleRate": { + "type": [ + "integer", + "null" + ], + "description": "Trace sampling rate (0-100): which sessions inject trace headers into their requests.", + "minimum": 0, + "maximum": 100 + }, + "defaultPrivacyLevel": { + "type": [ + "string", + "null" + ], + "description": "How Session Replay masks a page by default.", + "enum": [ + "mask", + "mask-user-input", + "allow" + ] + } + } + }, + "RemoteConfigHistoryItem": { + "type": "object", + "description": "One published remote configuration version.", + "properties": { + "config": { + "$ref": "#/components/schemas/RemoteConfig" + }, + "version": { + "type": "integer", + "description": "Version number, unique within the application." + }, + "content_hash": { + "type": "string", + "description": "Hash of the configuration content; lets the console identify versions with identical content." + }, + "equivalent_to": { + "type": "integer", + "description": "Earliest version carrying the same content, when that is not this version itself." + }, + "reason": { + "type": "string", + "description": "Operator's note left when the version was published. Empty when none was given." + }, + "updated_by": { + "type": "integer", + "description": "ID of the member who published the version.", + "format": "int64" + }, + "updated_by_name": { + "type": "string", + "description": "Name of the member who published the version." + }, + "updated_at": { + "type": "integer", + "description": "Unix timestamp in milliseconds - when the version was published.", + "format": "int64" + } + } + }, + "PreviewRemoteConfigRequest": { + "type": "object", + "description": "Preview request. Omit `config` to preview the currently live configuration.", + "properties": { + "application_id": { + "type": "string", + "description": "RUM application ID." + }, + "config": { + "$ref": "#/components/schemas/RemoteConfig" + }, + "env": { + "type": "string", + "description": "Environment the simulated client reports." + }, + "app_version": { + "type": "string", + "description": "App version the simulated client reports." + }, + "sdk": { + "type": "string", + "description": "SDK name and version the simulated client reports, e.g. `web@2.4.1`." + } + }, + "required": [ + "application_id" + ] + }, + "RemoteConfigRule": { + "type": "object", + "description": "One targeting rule: when `match` holds, `set` overrides `default`. The first matching rule wins and evaluation stops there - rule order is the priority.", + "properties": { + "match": { + "type": "object", + "description": "Key/value conditions the SDK's config request must equal. Keys are limited to `env`, `app_version` and `sdk`; values are at most 256 bytes.", + "minProperties": 1, + "additionalProperties": { + "type": "string", + "maxLength": 256 + } + }, + "set": { + "$ref": "#/components/schemas/RemoteConfigValues" + } + }, + "required": [ + "match", + "set" + ] + }, + "GetRemoteConfigRequest": { + "type": "object", + "description": "Get remote config request", + "properties": { + "application_id": { + "type": "string", + "description": "RUM application ID." + } + }, + "required": [ + "application_id" + ] + }, + "RemoteConfig": { + "type": "object", + "description": "The whole per-application remote configuration. A change reaches an SDK asynchronously and is applied when that SDK creates its next session, so a running session never flips a decision mid-flight.", + "properties": { + "enabled": { + "type": "boolean", + "description": "Kill switch. When false the engine reports no values at all and SDKs fall back to their init values." + }, + "activation": { + "type": "string", + "description": "How a change lands on a client that is already running. Empty means `next_session`.", + "enum": [ + "next_session", + "immediate" + ], + "default": "next_session" + }, + "refresh_on_foreground": { + "type": "boolean", + "description": "Let clients re-check the configuration when they return to the foreground instead of waiting for the next poll." + }, + "default": { + "$ref": "#/components/schemas/RemoteConfigValues" + }, + "rules": { + "type": "array", + "description": "Targeting rules, evaluated in order; at most 20 per application.", + "maxItems": 20, + "items": { + "$ref": "#/components/schemas/RemoteConfigRule" + } + }, + "custom": { + "type": "object", + "description": "Application-defined pass-through values handed to the host app verbatim. At most 5 keys, each key up to 64 bytes, each value up to 4 KB of JSON nested at most 3 levels, 16 KB in total. Anyone holding the public client token can read it.", + "maxProperties": 5, + "additionalProperties": {} + } + } + }, + "RevertRemoteConfigRequest": { + "type": "object", + "description": "Republish an earlier version's content under a new version number.", + "properties": { + "application_id": { + "type": "string", + "description": "RUM application ID." + }, + "version": { + "type": "integer", + "description": "History version to republish.", + "minimum": 1 + }, + "reason": { + "type": "string", + "description": "Operator's note. The console fills in `rolled back to vN` when left empty.", + "maxLength": 255 + } + }, + "required": [ + "application_id", + "version" + ] + }, + "PreviewRemoteConfigResponse": { + "type": "object", + "description": "Values the simulated client would receive.", + "properties": { + "values": { + "$ref": "#/components/schemas/RemoteConfigValues" + }, + "hit_rule_index": { + "type": "integer", + "description": "0-based index of the rule that decided the result, or -1 when only the default applied." + } + } + }, + "GetRemoteConfigResponse": { + "type": "object", + "description": "Live remote configuration and its version.", + "properties": { + "config": { + "$ref": "#/components/schemas/RemoteConfig" + }, + "version": { + "type": "integer", + "description": "Version the live configuration is stored under. 0 means the application has never been configured." + }, + "updated_at": { + "type": "integer", + "description": "Unix timestamp in milliseconds - when the current version was published. 0 when never configured.", + "format": "int64" + } + } + }, + "ListRemoteConfigHistoryRequest": { + "type": "object", + "description": "Remote configuration history request. Newest first by default.", + "properties": { + "application_id": { + "type": "string", + "description": "RUM application ID." + }, + "p": { + "type": "integer", + "description": "Zero-based page index; offset is p multiplied by limit.", + "minimum": 0, + "maximum": 100000, + "default": 0 + }, + "limit": { + "type": "integer", + "description": "Page size. Default 20, max 100.", + "default": 20, + "maximum": 100 + }, + "orderby": { + "type": "string", + "description": "Sort field. Default: `updated_at`.", + "enum": [ + "updated_at", + "version" + ], + "default": "updated_at" + }, + "asc": { + "type": "boolean", + "description": "Ascending order. Default: false (descending)." + } + }, + "required": [ + "application_id" + ] } } } diff --git a/api-reference/rum.openapi.zh.json b/api-reference/rum.openapi.zh.json index c4f52630..624e7575 100644 --- a/api-reference/rum.openapi.zh.json +++ b/api-reference/rum.openapi.zh.json @@ -3552,6 +3552,513 @@ } } } + }, + "/rum/application/remote-config/get": { + "post": { + "operationId": "rum-application-remote-config-read-get", + "summary": "查看远程配置详情", + "description": "获取 RUM 应用当前生效的远程配置及其版本号。", + "tags": [ + "RUM/应用管理" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `version` 为 `0` 表示该应用从未配置过远程配置，SDK 完全沿用初始化值。\n- 变更在客户端下一次会话开始时生效（`activation` 为 `immediate` 时立即生效）。", + "href": "/zh/api-reference/rum/applications/rum-application-remote-config-read-get", + "metadata": { + "sidebarTitle": "查看远程配置详情" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/GetRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "version": 7, + "updated_at": 1773398630657 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o" + } + } + } + } + } + }, + "/rum/application/remote-config/update": { + "post": { + "operationId": "rum-application-remote-config-write-update", + "summary": "更新远程配置", + "description": "为 RUM 应用发布一个全新的远程配置版本。", + "tags": [ + "RUM/应用管理" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 必须提交完整配置对象而非增量补丁——规则顺序即优先级，部分更新没有无歧义的解释。\n- 每次调用都会分配新版本号，并在同一事务中写入历史记录。\n- 发布前可先调用 `POST /rum/application/remote-config/preview` 验证客户端将拿到的值。", + "href": "/zh/api-reference/rum/applications/rum-application-remote-config-write-update", + "metadata": { + "sidebarTitle": "更新远程配置" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/UpdateRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "version": 8 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "reason": "Q4 上线前收紧回放采样" + } + } + } + } + } + }, + "/rum/application/remote-config/preview": { + "post": { + "operationId": "rum-application-remote-config-read-preview", + "summary": "预览远程配置", + "description": "在不发布的情况下评估一份草稿远程配置在给定客户端上下文下的效果。", + "tags": [ + "RUM/应用管理" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用与引擎完全相同的匹配逻辑，结果与生产客户端实际获取一致。\n- 省略 `config` 时预览当前生效配置。", + "href": "/zh/api-reference/rum/applications/rum-application-remote-config-read-preview", + "metadata": { + "sidebarTitle": "预览远程配置" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/PreviewRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "values": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + }, + "hit_rule_index": 0 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreviewRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "env": "production", + "app_version": "2.14.3", + "sdk": "web@2.4.1" + } + } + } + } + } + }, + "/rum/application/remote-config/history/list": { + "post": { + "operationId": "rum-application-remote-config-read-history-list", + "summary": "查询远程配置历史列表", + "description": "查询 RUM 应用已发布的远程配置版本列表。", + "tags": [ + "RUM/应用管理" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 默认按更新时间倒序（`orderby=updated_at`，`asc=false`）。\n- 内容相同的版本通过 `content_hash` 与 `equivalent_to` 标识，控制台据此提示\"这是某历史版本的相同内容\"。", + "href": "/zh/api-reference/rum/applications/rum-application-remote-config-read-history-list", + "metadata": { + "sidebarTitle": "查询远程配置历史列表" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ListRemoteConfigHistoryResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "total": 3, + "has_next_page": false, + "items": [ + { + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "version": 8, + "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", + "reason": "Q4 上线前收紧回放采样", + "updated_by": 4441703362131, + "updated_by_name": "Alice Zhang", + "updated_at": 1773398630657 + }, + { + "config": { + "enabled": true, + "activation": "next_session", + "refresh_on_foreground": false, + "default": { + "sessionSampleRate": 100, + "sessionReplaySampleRate": 20, + "traceSampleRate": 100, + "defaultPrivacyLevel": "mask-user-input" + }, + "rules": [ + { + "match": { + "env": "production" + }, + "set": { + "sessionSampleRate": 5, + "sessionReplaySampleRate": 0, + "defaultPrivacyLevel": "mask" + } + } + ], + "custom": { + "feature_flags": { + "checkout_v2": true + } + } + }, + "version": 7, + "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", + "reason": "", + "updated_by": 4441703362131, + "updated_by_name": "Alice Zhang", + "updated_at": 1772398630657 + } + ] + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListRemoteConfigHistoryRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "p": 0, + "limit": 20, + "orderby": "updated_at", + "asc": false + } + } + } + } + } + }, + "/rum/application/remote-config/history/revert": { + "post": { + "operationId": "rum-application-remote-config-write-history-revert", + "summary": "回滚远程配置版本", + "description": "将某个历史版本的远程配置内容重新发布为新版本。", + "tags": [ + "RUM/应用管理" + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 回滚不会重写历史：旧版本内容会以新的版本号发布。\n- `reason` 留空时控制台会自动填入\"rolled back to vN\"。", + "href": "/zh/api-reference/rum/applications/rum-application-remote-config-write-history-revert", + "metadata": { + "sidebarTitle": "回滚远程配置版本" + } + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/RevertRemoteConfigResponse" + } + } + } + ] + }, + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "version": 9 + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RevertRemoteConfigRequest" + }, + "example": { + "application_id": "WoyQQ3BohkdtPivubEvE8o", + "version": 7, + "reason": "Q4 上线故障后回滚" + } + } + } + } + } } }, "components": { @@ -7157,6 +7664,350 @@ "description": "私有化部署 License 到期时间，Unix 秒级时间戳。仅私有化部署会返回该字段，SaaS 账户不会出现该字段。" } } + }, + "UpdateRemoteConfigRequest": { + "type": "object", + "description": "发布一个全新的远程配置版本。客户端需提交完整对象而非增量补丁：规则顺序承载语义。", + "properties": { + "application_id": { + "type": "string", + "description": "RUM 应用 ID。" + }, + "config": { + "$ref": "#/components/schemas/RemoteConfig" + }, + "reason": { + "type": "string", + "description": "操作者留下的发布说明，原样保存。", + "maxLength": 255 + } + }, + "required": [ + "application_id", + "config" + ] + }, + "UpdateRemoteConfigResponse": { + "type": "object", + "description": "本次发布分配到的版本号。", + "properties": { + "version": { + "type": "integer", + "description": "新发布的版本号。" + } + } + }, + "ListRemoteConfigHistoryResponse": { + "type": "object", + "description": "远程配置历史分页结果。", + "properties": { + "total": { + "type": "integer", + "description": "版本总数。" + }, + "has_next_page": { + "type": "boolean", + "description": "是否还有下一页。" + }, + "items": { + "type": "array", + "description": "版本列表，默认最新在前。", + "items": { + "$ref": "#/components/schemas/RemoteConfigHistoryItem" + } + } + } + }, + "RevertRemoteConfigResponse": { + "type": "object", + "description": "回滚创建的版本。", + "properties": { + "version": { + "type": "integer", + "description": "回滚生成的新的版本号。" + } + } + }, + "RemoteConfigValues": { + "type": "object", + "description": "配置可设置的 SDK 参数。每个字段都是可选的：规则与默认值都未设置的字段不会出现在 SDK 响应中，SDK 将沿用初始化值。", + "properties": { + "sessionSampleRate": { + "type": [ + "integer", + "null" + ], + "description": "会话采样率（0-100）。", + "minimum": 0, + "maximum": 100 + }, + "sessionReplaySampleRate": { + "type": [ + "integer", + "null" + ], + "description": "Session Replay 采样率（0-100）。", + "minimum": 0, + "maximum": 100 + }, + "traceSampleRate": { + "type": [ + "integer", + "null" + ], + "description": "Trace 采样率（0-100）：哪些会话会在请求中注入 Trace 头。", + "minimum": 0, + "maximum": 100 + }, + "defaultPrivacyLevel": { + "type": [ + "string", + "null" + ], + "description": "Session Replay 默认的页面脱敏方式。", + "enum": [ + "mask", + "mask-user-input", + "allow" + ] + } + } + }, + "RemoteConfigHistoryItem": { + "type": "object", + "description": "一个已发布的远程配置版本。", + "properties": { + "config": { + "$ref": "#/components/schemas/RemoteConfig" + }, + "version": { + "type": "integer", + "description": "版本号，在应用内唯一。" + }, + "content_hash": { + "type": "string", + "description": "配置内容的哈希；控制台用它识别内容相同的版本。" + }, + "equivalent_to": { + "type": "integer", + "description": "与本版本内容相同的最早版本号（当不是本版本自身时返回）。" + }, + "reason": { + "type": "string", + "description": "发布该版本时操作者留下的说明，未填写则为空。" + }, + "updated_by": { + "type": "integer", + "description": "发布该版本的成员 ID。", + "format": "int64" + }, + "updated_by_name": { + "type": "string", + "description": "发布该版本的成员名称。" + }, + "updated_at": { + "type": "integer", + "description": "Unix 时间戳（毫秒）—— 版本发布时间。", + "format": "int64" + } + } + }, + "PreviewRemoteConfigRequest": { + "type": "object", + "description": "预览请求。省略 `config` 时预览当前生效配置。", + "properties": { + "application_id": { + "type": "string", + "description": "RUM 应用 ID。" + }, + "config": { + "$ref": "#/components/schemas/RemoteConfig" + }, + "env": { + "type": "string", + "description": "模拟客户端上报的环境。" + }, + "app_version": { + "type": "string", + "description": "模拟客户端上报的应用版本。" + }, + "sdk": { + "type": "string", + "description": "模拟客户端上报的 SDK 名称与版本，如 `web@2.4.1`。" + } + }, + "required": [ + "application_id" + ] + }, + "RemoteConfigRule": { + "type": "object", + "description": "单条定向规则：当 `match` 条件满足时，`set` 覆盖 `default`。规则按顺序评估，第一条命中的规则生效——规则顺序即优先级。", + "properties": { + "match": { + "type": "object", + "description": "SDK 配置请求必须相等的键值对。键仅支持 `env`、`app_version`、`sdk`；值最长 256 字节。", + "minProperties": 1, + "additionalProperties": { + "type": "string", + "maxLength": 256 + } + }, + "set": { + "$ref": "#/components/schemas/RemoteConfigValues" + } + }, + "required": [ + "match", + "set" + ] + }, + "GetRemoteConfigRequest": { + "type": "object", + "description": "获取远程配置请求", + "properties": { + "application_id": { + "type": "string", + "description": "RUM 应用 ID。" + } + }, + "required": [ + "application_id" + ] + }, + "RemoteConfig": { + "type": "object", + "description": "单个应用的完整远程配置。变更异步到达 SDK，并在其创建下一个会话时生效，正在进行的会话不会被中途改变。", + "properties": { + "enabled": { + "type": "boolean", + "description": "总开关。为 false 时引擎不下发任何值，SDK 沿用初始化值。" + }, + "activation": { + "type": "string", + "description": "变更如何作用于已在运行的客户端。留空表示 `next_session`。", + "enum": [ + "next_session", + "immediate" + ], + "default": "next_session" + }, + "refresh_on_foreground": { + "type": "boolean", + "description": "允许客户端回到前台时重新拉取配置，而不是等待下一次轮询。" + }, + "default": { + "$ref": "#/components/schemas/RemoteConfigValues" + }, + "rules": { + "type": "array", + "description": "定向规则，按顺序评估；每个应用最多 20 条。", + "maxItems": 20, + "items": { + "$ref": "#/components/schemas/RemoteConfigRule" + } + }, + "custom": { + "type": "object", + "description": "应用自定义的透传值，原样下发给宿主应用。最多 5 个键，键长不超过 64 字节，单值不超过 4 KB JSON 且嵌套不超过 3 层，总计不超过 16 KB。持有公开 client token 的任何人都能读到它。", + "maxProperties": 5, + "additionalProperties": {} + } + } + }, + "RevertRemoteConfigRequest": { + "type": "object", + "description": "将历史版本的内容重新发布为新的版本号。", + "properties": { + "application_id": { + "type": "string", + "description": "RUM 应用 ID。" + }, + "version": { + "type": "integer", + "description": "要重新发布的历史版本号。", + "minimum": 1 + }, + "reason": { + "type": "string", + "description": "操作者说明。控制台留空时会自动填入 `rolled back to vN`。", + "maxLength": 255 + } + }, + "required": [ + "application_id", + "version" + ] + }, + "PreviewRemoteConfigResponse": { + "type": "object", + "description": "模拟客户端将拿到的配置值。", + "properties": { + "values": { + "$ref": "#/components/schemas/RemoteConfigValues" + }, + "hit_rule_index": { + "type": "integer", + "description": "决定结果的规则下标（从 0 开始）；仅命中默认值时为 -1。" + } + } + }, + "GetRemoteConfigResponse": { + "type": "object", + "description": "当前生效的远程配置及其版本。", + "properties": { + "config": { + "$ref": "#/components/schemas/RemoteConfig" + }, + "version": { + "type": "integer", + "description": "当前配置的版本号。0 表示该应用从未配置过远程配置。" + }, + "updated_at": { + "type": "integer", + "description": "Unix 时间戳（毫秒）—— 当前版本发布时间。从未配置时为 0。", + "format": "int64" + } + } + }, + "ListRemoteConfigHistoryRequest": { + "type": "object", + "description": "远程配置历史查询请求。默认按最新在前排序。", + "properties": { + "application_id": { + "type": "string", + "description": "RUM 应用 ID。" + }, + "p": { + "type": "integer", + "description": "从 0 开始的页码；偏移量为 p 乘以 limit。", + "minimum": 0, + "maximum": 100000, + "default": 0 + }, + "limit": { + "type": "integer", + "description": "每页条数。默认 20，最大 100。", + "default": 20, + "maximum": 100 + }, + "orderby": { + "type": "string", + "description": "排序字段。默认 `updated_at`。", + "enum": [ + "updated_at", + "version" + ], + "default": "updated_at" + }, + "asc": { + "type": "boolean", + "description": "是否升序。默认 false（倒序）。" + } + }, + "required": [ + "application_id" + ] } } } diff --git a/docs.json b/docs.json index d34ad5e2..6ea62d7d 100644 --- a/docs.json +++ b/docs.json @@ -2283,6 +2283,7 @@ "POST /schedule/info", "POST /schedule/list", "POST /schedule/self", + "POST /schedule/by-person", "POST /schedule/infos" ] }, @@ -2542,7 +2543,12 @@ "POST /rum/application/create", "POST /rum/application/update", "POST /rum/application/delete", - "POST /rum/application/webhook/test" + "POST /rum/application/webhook/test", + "POST /rum/application/remote-config/get", + "POST /rum/application/remote-config/update", + "POST /rum/application/remote-config/preview", + "POST /rum/application/remote-config/history/list", + "POST /rum/application/remote-config/history/revert" ] }, { @@ -3662,6 +3668,7 @@ "POST /schedule/info", "POST /schedule/list", "POST /schedule/self", + "POST /schedule/by-person", "POST /schedule/infos" ] }, @@ -3921,7 +3928,12 @@ "POST /rum/application/create", "POST /rum/application/update", "POST /rum/application/delete", - "POST /rum/application/webhook/test" + "POST /rum/application/webhook/test", + "POST /rum/application/remote-config/get", + "POST /rum/application/remote-config/update", + "POST /rum/application/remote-config/preview", + "POST /rum/application/remote-config/history/list", + "POST /rum/application/remote-config/history/revert" ] }, { diff --git a/en/openapi/api-catalog.mdx b/en/openapi/api-catalog.mdx index 2cb1e50b..65e8d7f5 100644 --- a/en/openapi/api-catalog.mdx +++ b/en/openapi/api-catalog.mdx @@ -3,13 +3,13 @@ title: "API Catalog" description: "Complete list of Flashduty Open API endpoints, organized by product module with links to detailed documentation" --- -Flashduty Open API provides **336** endpoints covering five major modules: On-call, Monitors, RUM, AI SRE, and Platform. All endpoints use unified authentication and request specifications. See [Quick Start](/en/openapi/introduction) for details. +Flashduty Open API provides **342** endpoints covering five major modules: On-call, Monitors, RUM, AI SRE, and Platform. All endpoints use unified authentication and request specifications. See [Quick Start](/en/openapi/introduction) for details. All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated via APP Key through query string. - + ### Incidents @@ -146,6 +146,7 @@ All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated vi | POST | [`/schedule/info`](/en/api-reference/on-call/schedules/schedule-info) | Get schedule info | | POST | [`/schedule/list`](/en/api-reference/on-call/schedules/schedule-list) | List schedules | | POST | [`/schedule/self`](/en/api-reference/on-call/schedules/schedule-self) | List my schedules | +| POST | [`/schedule/by-person`](/en/api-reference/on-call/schedules/schedule-by-person) | Get member on-call status | | POST | [`/schedule/infos`](/en/api-reference/on-call/schedules/schedule-infos) | Batch get schedules | ### Licenses @@ -343,7 +344,7 @@ All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated vi - + ### Facets @@ -357,6 +358,11 @@ All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated vi | Method | Endpoint | Description | | :--- | :--- | :--- | | POST | [`/rum/application/webhook/test`](/en/api-reference/rum/applications/rum-application-webhook-test) | Test application webhook | +| POST | [`/rum/application/remote-config/history/revert`](/en/api-reference/rum/applications/rum-application-remote-config-write-history-revert) | Revert remote config | +| POST | [`/rum/application/remote-config/history/list`](/en/api-reference/rum/applications/rum-application-remote-config-read-history-list) | List remote config history | +| POST | [`/rum/application/remote-config/preview`](/en/api-reference/rum/applications/rum-application-remote-config-read-preview) | Preview remote config | +| POST | [`/rum/application/remote-config/update`](/en/api-reference/rum/applications/rum-application-remote-config-write-update) | Update remote config | +| POST | [`/rum/application/remote-config/get`](/en/api-reference/rum/applications/rum-application-remote-config-read-get) | Get remote config detail | | POST | [`/rum/application/list`](/en/api-reference/rum/applications/rum-application-read-list) | List applications | | POST | [`/rum/application/infos`](/en/api-reference/rum/applications/rum-application-read-infos) | Batch get applications | | POST | [`/rum/application/info`](/en/api-reference/rum/applications/rum-application-read-info) | Get application detail | diff --git a/zh/openapi/api-catalog.mdx b/zh/openapi/api-catalog.mdx index 9d99925e..1b96a179 100644 --- a/zh/openapi/api-catalog.mdx +++ b/zh/openapi/api-catalog.mdx @@ -3,13 +3,13 @@ title: "API 目录" description: "Flashduty Open API 接口完整列表，按产品模块组织并链接到详细文档" --- -Flashduty Open API 提供 **336** 个接口，覆盖 On-call、Monitors、RUM、AI SRE 和平台五个主要模块。所有接口使用统一认证方式和请求规范。详情参见[快速开始](/zh/openapi/introduction)。 +Flashduty Open API 提供 **342** 个接口，覆盖 On-call、Monitors、RUM、AI SRE 和平台五个主要模块。所有接口使用统一认证方式和请求规范。详情参见[快速开始](/zh/openapi/introduction)。 所有接口 URL 均以 `https://api.flashcat.cloud` 为 base，通过 query string 中的 APP Key 认证。 - + ### 故障管理 @@ -146,6 +146,7 @@ Flashduty Open API 提供 **336** 个接口，覆盖 On-call、Monitors、RUM、 | POST | [`/schedule/info`](/zh/api-reference/on-call/schedules/schedule-info) | 获取值班表详情 | | POST | [`/schedule/list`](/zh/api-reference/on-call/schedules/schedule-list) | 查询值班表列表 | | POST | [`/schedule/self`](/zh/api-reference/on-call/schedules/schedule-self) | 查询我的值班表 | +| POST | [`/schedule/by-person`](/zh/api-reference/on-call/schedules/schedule-by-person) | 查看成员值班状态 | | POST | [`/schedule/infos`](/zh/api-reference/on-call/schedules/schedule-infos) | 批量获取值班表 | ### 许可管理 @@ -343,7 +344,7 @@ Flashduty Open API 提供 **336** 个接口，覆盖 On-call、Monitors、RUM、 - + ### RUM 自定义字段 @@ -357,6 +358,11 @@ Flashduty Open API 提供 **336** 个接口，覆盖 On-call、Monitors、RUM、 | 方法 | 接口 | 描述 | | :--- | :--- | :--- | | POST | [`/rum/application/webhook/test`](/zh/api-reference/rum/applications/rum-application-webhook-test) | 测试应用 Webhook | +| POST | [`/rum/application/remote-config/history/revert`](/zh/api-reference/rum/applications/rum-application-remote-config-write-history-revert) | 回滚远程配置版本 | +| POST | [`/rum/application/remote-config/history/list`](/zh/api-reference/rum/applications/rum-application-remote-config-read-history-list) | 查询远程配置历史列表 | +| POST | [`/rum/application/remote-config/preview`](/zh/api-reference/rum/applications/rum-application-remote-config-read-preview) | 预览远程配置 | +| POST | [`/rum/application/remote-config/update`](/zh/api-reference/rum/applications/rum-application-remote-config-write-update) | 更新远程配置 | +| POST | [`/rum/application/remote-config/get`](/zh/api-reference/rum/applications/rum-application-remote-config-read-get) | 查看远程配置详情 | | POST | [`/rum/application/list`](/zh/api-reference/rum/applications/rum-application-read-list) | 查询应用列表 | | POST | [`/rum/application/infos`](/zh/api-reference/rum/applications/rum-application-read-infos) | 批量查询应用详情 | | POST | [`/rum/application/info`](/zh/api-reference/rum/applications/rum-application-read-info) | 查看应用详情 |