692 lines
27 KiB
JSON
692 lines
27 KiB
JSON
|
{
|
||
|
|
"openapi": "3.1.0",
|
||
|
|
"jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
|
||
|
|
"info": {
|
||
|
|
"title": "YoVision Sense Control API",
|
||
|
|
"version": "1.0.0",
|
||
|
|
"description": "受控的设备期望态与收敛查询契约。Tenant 只从认证上下文确定；Site、Area、RBAC 和配额真相仍由 Bell 持有。"
|
||
|
|
},
|
||
|
|
"servers": [
|
||
|
|
{
|
||
|
|
"url": "/",
|
||
|
|
"description": "由部署入口提供 scheme、host 和认证终止"
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"security": [
|
||
|
|
{
|
||
|
|
"bearerAuth": []
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"tags": [
|
||
|
|
{
|
||
|
|
"name": "Devices",
|
||
|
|
"description": "设备台账、期望态和收敛状态"
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"name": "Operations",
|
||
|
|
"description": "批量写入的逐项结果"
|
||
|
|
}
|
||
|
|
],
|
||
|
|
"paths": {
|
||
|
|
"/api/v1/sites/{site_id}/devices": {
|
||
|
|
"get": {
|
||
|
|
"tags": ["Devices"],
|
||
|
|
"operationId": "listDevices",
|
||
|
|
"summary": "分页查询当前认证租户下的站点设备",
|
||
|
|
"parameters": [
|
||
|
|
{"$ref": "#/components/parameters/SiteID"},
|
||
|
|
{"$ref": "#/components/parameters/Cursor"},
|
||
|
|
{"$ref": "#/components/parameters/Limit"},
|
||
|
|
{"$ref": "#/components/parameters/ModalityFilter"},
|
||
|
|
{"$ref": "#/components/parameters/CapabilityFilter"},
|
||
|
|
{"$ref": "#/components/parameters/DesiredStateFilter"},
|
||
|
|
{"$ref": "#/components/parameters/ActualStateFilter"}
|
||
|
|
],
|
||
|
|
"responses": {
|
||
|
|
"200": {
|
||
|
|
"description": "按 created_at、id 稳定升序返回的一页设备",
|
||
|
|
"headers": {"X-Trace-ID": {"$ref": "#/components/headers/TraceID"}},
|
||
|
|
"content": {
|
||
|
|
"application/json": {"schema": {"$ref": "#/components/schemas/DevicePage"}}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"401": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"404": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"500": {"$ref": "#/components/responses/ErrorResponse"}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"post": {
|
||
|
|
"tags": ["Devices"],
|
||
|
|
"operationId": "createDevice",
|
||
|
|
"summary": "创建待探测设备",
|
||
|
|
"parameters": [
|
||
|
|
{"$ref": "#/components/parameters/SiteID"},
|
||
|
|
{"$ref": "#/components/parameters/IdempotencyKey"}
|
||
|
|
],
|
||
|
|
"requestBody": {
|
||
|
|
"required": true,
|
||
|
|
"content": {
|
||
|
|
"application/json": {"schema": {"$ref": "#/components/schemas/DeviceCreate"}}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"responses": {
|
||
|
|
"201": {"$ref": "#/components/responses/CreatedDevice"},
|
||
|
|
"400": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"401": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"404": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"409": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"422": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"503": {"$ref": "#/components/responses/ErrorResponse"}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"/api/v1/sites/{site_id}/devices/{device_id}": {
|
||
|
|
"get": {
|
||
|
|
"tags": ["Devices"],
|
||
|
|
"operationId": "getDevice",
|
||
|
|
"summary": "读取设备期望态、实际态和收敛进度",
|
||
|
|
"parameters": [
|
||
|
|
{"$ref": "#/components/parameters/SiteID"},
|
||
|
|
{"$ref": "#/components/parameters/DeviceID"}
|
||
|
|
],
|
||
|
|
"responses": {
|
||
|
|
"200": {"$ref": "#/components/responses/CurrentDevice"},
|
||
|
|
"401": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"404": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"500": {"$ref": "#/components/responses/ErrorResponse"}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"patch": {
|
||
|
|
"tags": ["Devices"],
|
||
|
|
"operationId": "updateDevice",
|
||
|
|
"summary": "按 ETag 修改设备可编辑配置",
|
||
|
|
"parameters": [
|
||
|
|
{"$ref": "#/components/parameters/SiteID"},
|
||
|
|
{"$ref": "#/components/parameters/DeviceID"},
|
||
|
|
{"$ref": "#/components/parameters/IfMatch"}
|
||
|
|
],
|
||
|
|
"requestBody": {
|
||
|
|
"required": true,
|
||
|
|
"content": {
|
||
|
|
"application/merge-patch+json": {"schema": {"$ref": "#/components/schemas/DevicePatch"}}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"responses": {
|
||
|
|
"202": {"$ref": "#/components/responses/AcceptedMutation"},
|
||
|
|
"400": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"401": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"404": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"409": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"412": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"422": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"428": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"503": {"$ref": "#/components/responses/ErrorResponse"}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"/api/v1/sites/{site_id}/devices/{device_id}/desired-state": {
|
||
|
|
"put": {
|
||
|
|
"tags": ["Devices"],
|
||
|
|
"operationId": "setDeviceDesiredState",
|
||
|
|
"summary": "启用或停用设备接入期望态",
|
||
|
|
"description": "成功只表示期望态已持久化并进入对账，不表示实际态已经收敛。重复提交不会重复改变 generation，但每次请求均可产生审计事实。",
|
||
|
|
"parameters": [
|
||
|
|
{"$ref": "#/components/parameters/SiteID"},
|
||
|
|
{"$ref": "#/components/parameters/DeviceID"},
|
||
|
|
{"$ref": "#/components/parameters/IfMatch"}
|
||
|
|
],
|
||
|
|
"requestBody": {
|
||
|
|
"required": true,
|
||
|
|
"content": {
|
||
|
|
"application/json": {"schema": {"$ref": "#/components/schemas/DesiredStateChange"}}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"responses": {
|
||
|
|
"202": {"$ref": "#/components/responses/AcceptedMutation"},
|
||
|
|
"400": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"401": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"404": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"412": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"422": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"428": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"503": {"$ref": "#/components/responses/ErrorResponse"}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"/api/v1/sites/{site_id}/devices:batchDesiredState": {
|
||
|
|
"post": {
|
||
|
|
"tags": ["Devices"],
|
||
|
|
"operationId": "batchSetDeviceDesiredState",
|
||
|
|
"summary": "批量提交最多 128 个设备期望态变更",
|
||
|
|
"parameters": [
|
||
|
|
{"$ref": "#/components/parameters/SiteID"},
|
||
|
|
{"$ref": "#/components/parameters/IdempotencyKey"}
|
||
|
|
],
|
||
|
|
"requestBody": {
|
||
|
|
"required": true,
|
||
|
|
"content": {
|
||
|
|
"application/json": {"schema": {"$ref": "#/components/schemas/BatchDesiredStateRequest"}}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"responses": {
|
||
|
|
"202": {
|
||
|
|
"description": "请求已接收；响应包含已知的逐项接受/拒绝结果，后续状态从 operation 读取",
|
||
|
|
"headers": {
|
||
|
|
"Location": {"$ref": "#/components/headers/OperationLocation"},
|
||
|
|
"X-Trace-ID": {"$ref": "#/components/headers/TraceID"}
|
||
|
|
},
|
||
|
|
"content": {
|
||
|
|
"application/json": {"schema": {"$ref": "#/components/schemas/BatchOperation"}}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"400": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"401": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"404": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"409": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"422": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"503": {"$ref": "#/components/responses/ErrorResponse"}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"/api/v1/operations/{operation_id}": {
|
||
|
|
"get": {
|
||
|
|
"tags": ["Operations"],
|
||
|
|
"operationId": "getOperation",
|
||
|
|
"summary": "查询批量写入和逐项结果",
|
||
|
|
"parameters": [
|
||
|
|
{"$ref": "#/components/parameters/OperationID"}
|
||
|
|
],
|
||
|
|
"responses": {
|
||
|
|
"200": {
|
||
|
|
"description": "批量操作状态",
|
||
|
|
"headers": {"X-Trace-ID": {"$ref": "#/components/headers/TraceID"}},
|
||
|
|
"content": {
|
||
|
|
"application/json": {"schema": {"$ref": "#/components/schemas/BatchOperation"}}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"401": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"404": {"$ref": "#/components/responses/ErrorResponse"},
|
||
|
|
"500": {"$ref": "#/components/responses/ErrorResponse"}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"components": {
|
||
|
|
"securitySchemes": {
|
||
|
|
"bearerAuth": {
|
||
|
|
"type": "http",
|
||
|
|
"scheme": "bearer",
|
||
|
|
"bearerFormat": "opaque",
|
||
|
|
"description": "认证实现与 claim 格式不属于 v1 契约；服务端必须从已验证主体确定 tenant 与权限。"
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"parameters": {
|
||
|
|
"SiteID": {
|
||
|
|
"name": "site_id",
|
||
|
|
"in": "path",
|
||
|
|
"required": true,
|
||
|
|
"schema": {"$ref": "#/components/schemas/LogicalID"},
|
||
|
|
"description": "当前认证租户中的稳定站点 ID"
|
||
|
|
},
|
||
|
|
"DeviceID": {
|
||
|
|
"name": "device_id",
|
||
|
|
"in": "path",
|
||
|
|
"required": true,
|
||
|
|
"schema": {"$ref": "#/components/schemas/LogicalID"}
|
||
|
|
},
|
||
|
|
"OperationID": {
|
||
|
|
"name": "operation_id",
|
||
|
|
"in": "path",
|
||
|
|
"required": true,
|
||
|
|
"schema": {"type": "string", "pattern": "^op_[0-9A-HJKMNP-TV-Z]{26}$"}
|
||
|
|
},
|
||
|
|
"Cursor": {
|
||
|
|
"name": "cursor",
|
||
|
|
"in": "query",
|
||
|
|
"required": false,
|
||
|
|
"schema": {"type": "string", "minLength": 16, "maxLength": 512},
|
||
|
|
"description": "不透明游标；客户端不得解析或构造"
|
||
|
|
},
|
||
|
|
"Limit": {
|
||
|
|
"name": "limit",
|
||
|
|
"in": "query",
|
||
|
|
"required": false,
|
||
|
|
"schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}
|
||
|
|
},
|
||
|
|
"ModalityFilter": {
|
||
|
|
"name": "modality",
|
||
|
|
"in": "query",
|
||
|
|
"required": false,
|
||
|
|
"schema": {"$ref": "#/components/schemas/Modality"}
|
||
|
|
},
|
||
|
|
"CapabilityFilter": {
|
||
|
|
"name": "capability",
|
||
|
|
"in": "query",
|
||
|
|
"required": false,
|
||
|
|
"schema": {"$ref": "#/components/schemas/Capability"}
|
||
|
|
},
|
||
|
|
"DesiredStateFilter": {
|
||
|
|
"name": "desired_state",
|
||
|
|
"in": "query",
|
||
|
|
"required": false,
|
||
|
|
"schema": {"$ref": "#/components/schemas/DesiredState"}
|
||
|
|
},
|
||
|
|
"ActualStateFilter": {
|
||
|
|
"name": "actual_state",
|
||
|
|
"in": "query",
|
||
|
|
"required": false,
|
||
|
|
"schema": {"$ref": "#/components/schemas/ActualState"}
|
||
|
|
},
|
||
|
|
"IdempotencyKey": {
|
||
|
|
"name": "Idempotency-Key",
|
||
|
|
"in": "header",
|
||
|
|
"required": true,
|
||
|
|
"schema": {
|
||
|
|
"type": "string",
|
||
|
|
"minLength": 16,
|
||
|
|
"maxLength": 128,
|
||
|
|
"pattern": "^[A-Za-z0-9._:-]+$"
|
||
|
|
},
|
||
|
|
"description": "同一认证主体、站点、operationId、key 和规范化 body 在 24 小时内返回同一结果；key 相同而 body 不同返回 idempotency_conflict。"
|
||
|
|
},
|
||
|
|
"IfMatch": {
|
||
|
|
"name": "If-Match",
|
||
|
|
"in": "header",
|
||
|
|
"required": true,
|
||
|
|
"schema": {"type": "string", "minLength": 3, "maxLength": 128},
|
||
|
|
"description": "使用最近一次 GET/写响应的 opaque ETag；不匹配返回 412 etag_mismatch。"
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"headers": {
|
||
|
|
"ETag": {
|
||
|
|
"description": "设备资源的不透明并发版本",
|
||
|
|
"schema": {"type": "string"}
|
||
|
|
},
|
||
|
|
"TraceID": {
|
||
|
|
"description": "不含租户、主机或凭据的排查 ID",
|
||
|
|
"schema": {"type": "string", "minLength": 8, "maxLength": 128}
|
||
|
|
},
|
||
|
|
"DeviceLocation": {
|
||
|
|
"description": "新建设备资源的相对路径",
|
||
|
|
"schema": {"type": "string", "pattern": "^/api/v1/sites/[^/]+/devices/[^/]+$"}
|
||
|
|
},
|
||
|
|
"OperationLocation": {
|
||
|
|
"description": "批量操作资源的相对路径",
|
||
|
|
"schema": {"type": "string", "pattern": "^/api/v1/operations/op_[0-9A-HJKMNP-TV-Z]{26}$"}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"responses": {
|
||
|
|
"CurrentDevice": {
|
||
|
|
"description": "设备当前表示；endpoint 与 credential ref 永不回显",
|
||
|
|
"headers": {
|
||
|
|
"ETag": {"$ref": "#/components/headers/ETag"},
|
||
|
|
"X-Trace-ID": {"$ref": "#/components/headers/TraceID"}
|
||
|
|
},
|
||
|
|
"content": {
|
||
|
|
"application/json": {"schema": {"$ref": "#/components/schemas/Device"}}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"CreatedDevice": {
|
||
|
|
"description": "设备已创建；启用设备仍需等待对账收敛",
|
||
|
|
"headers": {
|
||
|
|
"ETag": {"$ref": "#/components/headers/ETag"},
|
||
|
|
"Location": {"$ref": "#/components/headers/DeviceLocation"},
|
||
|
|
"X-Trace-ID": {"$ref": "#/components/headers/TraceID"}
|
||
|
|
},
|
||
|
|
"content": {
|
||
|
|
"application/json": {"schema": {"$ref": "#/components/schemas/Device"}}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"AcceptedMutation": {
|
||
|
|
"description": "期望态/配置写入已接受，实际态异步收敛",
|
||
|
|
"headers": {
|
||
|
|
"ETag": {"$ref": "#/components/headers/ETag"},
|
||
|
|
"X-Trace-ID": {"$ref": "#/components/headers/TraceID"}
|
||
|
|
},
|
||
|
|
"content": {
|
||
|
|
"application/json": {"schema": {"$ref": "#/components/schemas/MutationReceipt"}}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"ErrorResponse": {
|
||
|
|
"description": "稳定错误；不返回内部堆栈、资源存在性或连接秘密",
|
||
|
|
"headers": {"X-Trace-ID": {"$ref": "#/components/headers/TraceID"}},
|
||
|
|
"content": {
|
||
|
|
"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"schemas": {
|
||
|
|
"LogicalID": {
|
||
|
|
"type": "string",
|
||
|
|
"minLength": 1,
|
||
|
|
"maxLength": 64,
|
||
|
|
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$"
|
||
|
|
},
|
||
|
|
"Modality": {
|
||
|
|
"type": "string",
|
||
|
|
"enum": ["video", "radar", "contact", "button", "wearable", "other"]
|
||
|
|
},
|
||
|
|
"Capability": {
|
||
|
|
"type": "string",
|
||
|
|
"enum": ["video_capture", "audio_capture", "spatial_rule", "telemetry"]
|
||
|
|
},
|
||
|
|
"DesiredState": {
|
||
|
|
"type": "string",
|
||
|
|
"enum": ["disabled", "enabled"]
|
||
|
|
},
|
||
|
|
"ActualState": {
|
||
|
|
"type": "string",
|
||
|
|
"enum": ["pending", "online", "offline", "failed"]
|
||
|
|
},
|
||
|
|
"AdapterStatus": {
|
||
|
|
"type": "string",
|
||
|
|
"enum": ["pending", "ready", "adapter_not_ready", "authentication_failed", "unavailable"]
|
||
|
|
},
|
||
|
|
"ErrorCode": {
|
||
|
|
"type": "string",
|
||
|
|
"enum": [
|
||
|
|
"invalid_request",
|
||
|
|
"unauthenticated",
|
||
|
|
"forbidden",
|
||
|
|
"not_found",
|
||
|
|
"conflict",
|
||
|
|
"precondition_required",
|
||
|
|
"etag_mismatch",
|
||
|
|
"idempotency_conflict",
|
||
|
|
"duplicate_serial_number",
|
||
|
|
"quota_exceeded",
|
||
|
|
"quota_projection_unavailable",
|
||
|
|
"quota_projection_invalid",
|
||
|
|
"area_policy_denied",
|
||
|
|
"area_policy_unavailable",
|
||
|
|
"adapter_not_ready",
|
||
|
|
"authentication_failed",
|
||
|
|
"endpoint_credentials_forbidden",
|
||
|
|
"batch_too_large",
|
||
|
|
"service_unavailable",
|
||
|
|
"internal_error"
|
||
|
|
]
|
||
|
|
},
|
||
|
|
"DeviceCreate": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": false,
|
||
|
|
"required": ["serial_number", "name", "modality", "capabilities", "area_id"],
|
||
|
|
"properties": {
|
||
|
|
"serial_number": {"type": "string", "minLength": 1, "maxLength": 128},
|
||
|
|
"name": {"type": "string", "minLength": 1, "maxLength": 200},
|
||
|
|
"modality": {"$ref": "#/components/schemas/Modality"},
|
||
|
|
"capabilities": {
|
||
|
|
"type": "array",
|
||
|
|
"minItems": 1,
|
||
|
|
"maxItems": 16,
|
||
|
|
"uniqueItems": true,
|
||
|
|
"items": {"$ref": "#/components/schemas/Capability"},
|
||
|
|
"description": "请求接入的能力集合；适配器探测不支持时以稳定错误拒绝或标记 adapter_not_ready。"
|
||
|
|
},
|
||
|
|
"area_id": {"$ref": "#/components/schemas/LogicalID"},
|
||
|
|
"endpoint_ref": {
|
||
|
|
"type": "string",
|
||
|
|
"format": "uri",
|
||
|
|
"minLength": 1,
|
||
|
|
"maxLength": 2048,
|
||
|
|
"writeOnly": true,
|
||
|
|
"description": "绝对 URI，禁止 userinfo；只在受控写路径使用。"
|
||
|
|
},
|
||
|
|
"credential_ref": {
|
||
|
|
"type": "string",
|
||
|
|
"minLength": 1,
|
||
|
|
"maxLength": 512,
|
||
|
|
"writeOnly": true,
|
||
|
|
"description": "不透明密钥引用，不是用户名、密码或 token。"
|
||
|
|
},
|
||
|
|
"profile_token": {
|
||
|
|
"type": "string",
|
||
|
|
"minLength": 1,
|
||
|
|
"maxLength": 256,
|
||
|
|
"writeOnly": true
|
||
|
|
},
|
||
|
|
"desired_state": {
|
||
|
|
"allOf": [{"$ref": "#/components/schemas/DesiredState"}],
|
||
|
|
"default": "disabled"
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"allOf": [
|
||
|
|
{
|
||
|
|
"if": {
|
||
|
|
"required": ["modality"],
|
||
|
|
"properties": {"modality": {"const": "video"}}
|
||
|
|
},
|
||
|
|
"then": {
|
||
|
|
"properties": {
|
||
|
|
"capabilities": {"contains": {"const": "video_capture"}, "minContains": 1}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
{
|
||
|
|
"if": {
|
||
|
|
"required": ["capabilities"],
|
||
|
|
"properties": {
|
||
|
|
"capabilities": {"contains": {"const": "video_capture"}, "minContains": 1}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"then": {"required": ["endpoint_ref", "credential_ref"]}
|
||
|
|
}
|
||
|
|
]
|
||
|
|
},
|
||
|
|
"DevicePatch": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": false,
|
||
|
|
"minProperties": 1,
|
||
|
|
"properties": {
|
||
|
|
"name": {"type": "string", "minLength": 1, "maxLength": 200},
|
||
|
|
"area_id": {"$ref": "#/components/schemas/LogicalID"},
|
||
|
|
"endpoint_ref": {
|
||
|
|
"type": "string",
|
||
|
|
"format": "uri",
|
||
|
|
"minLength": 1,
|
||
|
|
"maxLength": 2048,
|
||
|
|
"writeOnly": true,
|
||
|
|
"description": "绝对 URI，禁止 userinfo。"
|
||
|
|
},
|
||
|
|
"credential_ref": {
|
||
|
|
"type": "string",
|
||
|
|
"minLength": 1,
|
||
|
|
"maxLength": 512,
|
||
|
|
"writeOnly": true
|
||
|
|
},
|
||
|
|
"profile_token": {
|
||
|
|
"type": "string",
|
||
|
|
"minLength": 1,
|
||
|
|
"maxLength": 256,
|
||
|
|
"writeOnly": true
|
||
|
|
}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"DesiredStateChange": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": false,
|
||
|
|
"required": ["desired_state", "reason"],
|
||
|
|
"properties": {
|
||
|
|
"desired_state": {"$ref": "#/components/schemas/DesiredState"},
|
||
|
|
"reason": {"type": "string", "minLength": 1, "maxLength": 500}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"Device": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": false,
|
||
|
|
"required": [
|
||
|
|
"id", "tenant_id", "site_id", "serial_number", "name", "modality",
|
||
|
|
"capabilities", "area_id", "desired_state", "actual_state", "adapter_status",
|
||
|
|
"endpoint_configured", "credential_configured", "generation", "observed_generation",
|
||
|
|
"converged", "failure_count", "projection_versions", "created_at", "updated_at"
|
||
|
|
],
|
||
|
|
"properties": {
|
||
|
|
"id": {"$ref": "#/components/schemas/LogicalID"},
|
||
|
|
"tenant_id": {
|
||
|
|
"allOf": [{"$ref": "#/components/schemas/LogicalID"}],
|
||
|
|
"readOnly": true,
|
||
|
|
"description": "只用于回显已授权上下文，不得由客户端写入。"
|
||
|
|
},
|
||
|
|
"site_id": {"$ref": "#/components/schemas/LogicalID"},
|
||
|
|
"serial_number": {"type": "string", "minLength": 1, "maxLength": 128},
|
||
|
|
"name": {"type": "string", "minLength": 1, "maxLength": 200},
|
||
|
|
"modality": {"$ref": "#/components/schemas/Modality"},
|
||
|
|
"capabilities": {
|
||
|
|
"type": "array",
|
||
|
|
"items": {"$ref": "#/components/schemas/Capability"},
|
||
|
|
"uniqueItems": true,
|
||
|
|
"maxItems": 16,
|
||
|
|
"readOnly": true
|
||
|
|
},
|
||
|
|
"area_id": {"$ref": "#/components/schemas/LogicalID"},
|
||
|
|
"desired_state": {"$ref": "#/components/schemas/DesiredState"},
|
||
|
|
"actual_state": {"$ref": "#/components/schemas/ActualState"},
|
||
|
|
"adapter_status": {"$ref": "#/components/schemas/AdapterStatus"},
|
||
|
|
"endpoint_configured": {"type": "boolean", "readOnly": true},
|
||
|
|
"credential_configured": {"type": "boolean", "readOnly": true},
|
||
|
|
"generation": {"type": "integer", "format": "int64", "minimum": 1, "readOnly": true},
|
||
|
|
"observed_generation": {"type": "integer", "format": "int64", "minimum": 0, "readOnly": true},
|
||
|
|
"converged": {
|
||
|
|
"type": "boolean",
|
||
|
|
"readOnly": true,
|
||
|
|
"description": "期望代已被观察且当前无待重试；不等价于所有外部系统健康。"
|
||
|
|
},
|
||
|
|
"failure_count": {"type": "integer", "minimum": 0, "readOnly": true},
|
||
|
|
"next_attempt_at": {"type": ["string", "null"], "format": "date-time", "readOnly": true},
|
||
|
|
"last_error_code": {"type": ["string", "null"], "maxLength": 128, "readOnly": true},
|
||
|
|
"projection_versions": {"$ref": "#/components/schemas/ProjectionVersions"},
|
||
|
|
"created_at": {"type": "string", "format": "date-time", "readOnly": true},
|
||
|
|
"updated_at": {"type": "string", "format": "date-time", "readOnly": true}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"ProjectionVersions": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": false,
|
||
|
|
"required": ["quota_source_version", "area_policy_source_version", "synced_at"],
|
||
|
|
"properties": {
|
||
|
|
"quota_source_version": {"type": ["integer", "null"], "format": "int64", "minimum": 1, "readOnly": true},
|
||
|
|
"area_policy_source_version": {"type": ["integer", "null"], "format": "int64", "minimum": 1, "readOnly": true},
|
||
|
|
"synced_at": {"type": ["string", "null"], "format": "date-time", "readOnly": true}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"SiteQuotaStatus": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": false,
|
||
|
|
"required": ["status", "used_video_channels", "max_video_channels", "available_video_channels", "over_limit", "source_version", "synced_at"],
|
||
|
|
"properties": {
|
||
|
|
"status": {"type": "string", "enum": ["current", "unavailable", "invalid"]},
|
||
|
|
"used_video_channels": {"type": "integer", "minimum": 0, "maximum": 128},
|
||
|
|
"max_video_channels": {"type": ["integer", "null"], "minimum": 1, "maximum": 128},
|
||
|
|
"available_video_channels": {"type": ["integer", "null"], "minimum": 0, "maximum": 128},
|
||
|
|
"over_limit": {"type": "boolean"},
|
||
|
|
"source_version": {"type": ["integer", "null"], "format": "int64", "minimum": 1},
|
||
|
|
"synced_at": {"type": ["string", "null"], "format": "date-time"}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"PageInfo": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": false,
|
||
|
|
"required": ["limit", "has_more", "next_cursor"],
|
||
|
|
"properties": {
|
||
|
|
"limit": {"type": "integer", "minimum": 1, "maximum": 100},
|
||
|
|
"has_more": {"type": "boolean"},
|
||
|
|
"next_cursor": {"type": ["string", "null"], "maxLength": 512}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"DevicePage": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": false,
|
||
|
|
"required": ["items", "page", "quota"],
|
||
|
|
"properties": {
|
||
|
|
"items": {"type": "array", "maxItems": 100, "items": {"$ref": "#/components/schemas/Device"}},
|
||
|
|
"page": {"$ref": "#/components/schemas/PageInfo"},
|
||
|
|
"quota": {"$ref": "#/components/schemas/SiteQuotaStatus"}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"MutationReceipt": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": false,
|
||
|
|
"required": ["device", "accepted_at", "trace_id"],
|
||
|
|
"properties": {
|
||
|
|
"device": {"$ref": "#/components/schemas/Device"},
|
||
|
|
"accepted_at": {"type": "string", "format": "date-time"},
|
||
|
|
"trace_id": {"type": "string", "minLength": 8, "maxLength": 128}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"BatchDesiredStateItem": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": false,
|
||
|
|
"required": ["device_id", "etag", "desired_state"],
|
||
|
|
"properties": {
|
||
|
|
"device_id": {"$ref": "#/components/schemas/LogicalID"},
|
||
|
|
"etag": {"type": "string", "minLength": 3, "maxLength": 128},
|
||
|
|
"desired_state": {"$ref": "#/components/schemas/DesiredState"}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"BatchDesiredStateRequest": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": false,
|
||
|
|
"required": ["items", "reason"],
|
||
|
|
"properties": {
|
||
|
|
"items": {
|
||
|
|
"type": "array",
|
||
|
|
"minItems": 1,
|
||
|
|
"maxItems": 128,
|
||
|
|
"items": {"$ref": "#/components/schemas/BatchDesiredStateItem"}
|
||
|
|
},
|
||
|
|
"reason": {"type": "string", "minLength": 1, "maxLength": 500}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"BatchItemResult": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": false,
|
||
|
|
"required": ["device_id", "status", "error_code", "message", "generation"],
|
||
|
|
"properties": {
|
||
|
|
"device_id": {"$ref": "#/components/schemas/LogicalID"},
|
||
|
|
"status": {"type": "string", "enum": ["accepted", "rejected", "succeeded", "failed"]},
|
||
|
|
"error_code": {"oneOf": [{"$ref": "#/components/schemas/ErrorCode"}, {"type": "null"}]},
|
||
|
|
"message": {"type": ["string", "null"], "maxLength": 500},
|
||
|
|
"generation": {"type": ["integer", "null"], "format": "int64", "minimum": 1}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"BatchOperation": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": false,
|
||
|
|
"required": ["id", "status", "submitted_at", "completed_at", "results", "trace_id"],
|
||
|
|
"properties": {
|
||
|
|
"id": {"type": "string", "pattern": "^op_[0-9A-HJKMNP-TV-Z]{26}$"},
|
||
|
|
"status": {"type": "string", "enum": ["queued", "running", "succeeded", "partially_succeeded", "failed"]},
|
||
|
|
"submitted_at": {"type": "string", "format": "date-time"},
|
||
|
|
"completed_at": {"type": ["string", "null"], "format": "date-time"},
|
||
|
|
"results": {"type": "array", "maxItems": 128, "items": {"$ref": "#/components/schemas/BatchItemResult"}},
|
||
|
|
"trace_id": {"type": "string", "minLength": 8, "maxLength": 128}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"FieldError": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": false,
|
||
|
|
"required": ["field", "code", "message"],
|
||
|
|
"properties": {
|
||
|
|
"field": {"type": "string", "maxLength": 256},
|
||
|
|
"code": {"type": "string", "maxLength": 128},
|
||
|
|
"message": {"type": "string", "maxLength": 500}
|
||
|
|
}
|
||
|
|
},
|
||
|
|
"Problem": {
|
||
|
|
"type": "object",
|
||
|
|
"additionalProperties": false,
|
||
|
|
"required": ["type", "title", "status", "code", "message", "trace_id", "field_errors"],
|
||
|
|
"properties": {
|
||
|
|
"type": {"type": "string", "format": "uri-reference"},
|
||
|
|
"title": {"type": "string", "maxLength": 200},
|
||
|
|
"status": {"type": "integer", "minimum": 400, "maximum": 599},
|
||
|
|
"code": {"$ref": "#/components/schemas/ErrorCode"},
|
||
|
|
"message": {"type": "string", "maxLength": 1000},
|
||
|
|
"trace_id": {"type": "string", "minLength": 8, "maxLength": 128},
|
||
|
|
"field_errors": {"type": "array", "maxItems": 100, "items": {"$ref": "#/components/schemas/FieldError"}}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|