# 儲存自訂指標版本 Canonical URL: https://sosoapi.ai/zh-hant/docs/mcp/save-custom-metric `sosoapi_save_custom_metric` 以 editor 或以上角色儲存自訂指標新版本，傳 workspace_id、formula、已審閱 dataset、expected_version 同 mutation_id。新定義用 expected_version=null；formula.version 必須係原版本加一。伺服器重算並核對可選 calculation，保存公式、計算及數據來源；重試保留同一 mutation_id 同內容，唔會自動更新來源。 ## Profiles 及連接方式 Profiles: full Transports: stdio, http Profile 只影響工具可見性，不會授予權限。HTTP 不提供本機檔案上傳。SOSOAPI_OUTPUT_SCHEMAS=1 會宣告輸出 schema；兩種模式均會回傳 structured results。 ## 權限及改動 MCP annotations 只提供工具發現提示，並非存取控制保證；實際呼叫仍須通過登入、角色、資源及能力檢查。 ```json { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false } ``` `/analytics-api/reporting/metrics/save` — agent:operate; synchronous_http_response ## 輸入欄位 ```json { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "formula": { "type": "object", "properties": { "contractVersion": { "type": "string", "enum": [ "analytics-metric/v1" ] }, "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "version": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "expression": { "type": "string", "minLength": 1, "maxLength": 1000 }, "fields": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "selector": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "facebook", "instagram", "threads", "youtube" ] }, "key": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,100}$" }, "definition": { "type": "string", "minLength": 1, "maxLength": 500 }, "unit": { "type": "string", "enum": [ "count", "seconds", "minutes", "percent", "ratio" ] }, "grain": { "type": "string", "enum": [ "post", "account" ] }, "measurementKind": { "type": "string", "enum": [ "lifetime", "snapshot", "period", "unknown" ] }, "nativePeriod": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] } }, "required": [ "platform", "key", "definition", "unit", "grain", "measurementKind", "nativePeriod", "timezone" ], "additionalProperties": false }, "aggregation": { "type": "string", "enum": [ "single", "sum" ] } }, "required": [ "identifier", "selector", "aggregation" ], "additionalProperties": false } }, "rounding": { "type": "object", "properties": { "decimalPlaces": { "type": "integer", "minimum": 0, "maximum": 8 }, "mode": { "type": "string", "enum": [ "half_away_from_zero" ] } }, "required": [ "decimalPlaces", "mode" ], "additionalProperties": false } }, "required": [ "contractVersion", "id", "workspaceId", "name", "version", "expression", "fields", "rounding" ], "additionalProperties": false }, "dataset": { "type": "object", "properties": { "contractVersion": { "type": "string", "enum": [ "analytics-report/v1" ] }, "id": { "type": "string", "format": "uuid" }, "reviewedAt": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" }, "selection": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "accountIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid" } }, "platforms": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "facebook", "instagram", "threads", "youtube" ] } }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "workspaceId", "accountIds", "platforms", "startDate", "endDate", "timezone" ], "additionalProperties": false }, "accounts": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "facebook", "instagram", "threads", "youtube" ] }, "name": { "type": "string", "maxLength": 500 }, "connectionStatus": { "type": "string", "maxLength": 100 }, "healthMessage": { "type": "string", "maxLength": 1000 } }, "required": [ "id", "workspaceId", "platform", "name" ], "additionalProperties": false } }, "posts": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "social_post_id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "social_account_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "instagram", "facebook", "threads", "youtube" ] }, "provider_post_id": { "type": "string", "minLength": 1, "maxLength": 512 }, "provider_published_at": { "anyOf": [ { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" }, { "type": "null" } ] }, "content_format": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "permalink": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri" }, { "type": "null" } ] }, "provider_state": { "type": "string", "enum": [ "available", "deleted", "unavailable", "unknown" ] }, "first_seen_at": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" }, "last_seen_at": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" }, "scheduled_post_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "provenance": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "instagram", "facebook", "threads", "youtube" ] }, "source": { "type": "string", "enum": [ "provider_api", "provider_webhook", "publication_outcome", "backfill" ] }, "source_job_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "provider_api_version": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "schema_version": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "provider", "source", "source_job_id", "provider_api_version", "schema_version" ], "additionalProperties": false } }, "required": [ "social_post_id", "workspace_id", "social_account_id", "platform", "provider_post_id", "provider_published_at", "content_format", "permalink", "provider_state", "first_seen_at", "last_seen_at", "scheduled_post_id", "provenance" ], "additionalProperties": false } }, "sources": { "maxItems": 30, "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "facebook", "instagram", "threads", "youtube" ] }, "resourceKind": { "type": "string", "enum": [ "account", "post" ] }, "providerResourceId": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ] }, "requestId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "available", "partial", "not_returned", "unsupported", "permission_required", "threshold_not_met", "no_data", "failed", "pending", "stale" ] }, "reason": { "anyOf": [ { "type": "string", "maxLength": 8000 }, { "type": "null" } ] }, "envelope": { "anyOf": [ { "type": "object", "properties": { "contract_version": { "type": "string", "enum": [ "provider-insights/v1" ] }, "request_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "facebook", "instagram", "threads", "youtube" ] }, "resource": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "account", "post" ] }, "social_account_id": { "type": "string", "format": "uuid" }, "provider_resource_id": { "type": [ "string", "null" ] } }, "required": [ "kind", "social_account_id", "provider_resource_id" ], "additionalProperties": false }, "provider_api_version": { "type": "string", "minLength": 1, "maxLength": 100 }, "fetched_at": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" }, "status": { "type": "string", "enum": [ "available", "partial", "unavailable" ] }, "availability": { "minItems": 1, "maxItems": 64, "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "available", "partial", "not_returned", "unsupported", "permission_required", "threshold_not_met", "no_data", "failed" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 }, "diagnostics": { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 0, "maximum": 599 }, "failed_step": { "type": "string", "minLength": 1, "maxLength": 200 }, "provider_code": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 100 } ] }, "provider_subcode": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 100 } ] }, "provider_type": { "type": "string", "maxLength": 200 }, "is_transient": { "type": "boolean" }, "provider_request_id": { "type": "string", "maxLength": 200 }, "access": { "type": "object", "properties": { "login_mode": { "type": "string", "enum": [ "instagram_login", "facebook_login", "threads_user" ] }, "provider_host": { "type": "string", "maxLength": 200 }, "required_permissions": { "maxItems": 16, "type": "array", "items": { "type": "string", "maxLength": 100 } }, "current_connection_policy_permissions": { "maxItems": 16, "type": "array", "items": { "type": "string", "maxLength": 100 } }, "granted_permissions": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 100 } }, { "type": "null" } ] }, "grant_evidence": { "type": "string", "enum": [ "exact", "unknown" ] }, "permission_state": { "type": "string", "enum": [ "granted", "missing", "unknown" ] }, "grant_observed_at": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" }, "app_access": { "type": "string", "enum": [ "unverified" ] }, "next_step": { "type": "string", "maxLength": 1500 } }, "required": [ "login_mode", "provider_host", "required_permissions", "current_connection_policy_permissions", "granted_permissions", "grant_evidence", "permission_state", "app_access", "next_step" ], "additionalProperties": false } }, "required": [ "http_status" ], "additionalProperties": false } }, "required": [ "scope", "status" ], "additionalProperties": false } }, "provider_data": { "anyOf": [ {}, { "type": "null" } ] }, "requested_date_range": { "anyOf": [ { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "start_date", "end_date" ], "additionalProperties": false }, { "type": "null" } ] }, "cache": { "type": "object", "properties": { "authoritative": { "type": "boolean", "enum": [ false ] }, "status": { "type": "string", "enum": [ "stored", "hit", "bypassed" ] }, "expires_at": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" } }, "required": [ "authoritative", "status", "expires_at" ], "additionalProperties": false } }, "required": [ "contract_version", "request_id", "platform", "resource", "provider_api_version", "fetched_at", "status", "availability", "provider_data", "requested_date_range", "cache" ], "additionalProperties": false }, { "type": "null" } ] }, "metrics": { "maxItems": 5000, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 150 }, "definition": { "type": "string", "minLength": 1, "maxLength": 1000 }, "unit": { "type": "string", "minLength": 1, "maxLength": 100 }, "grain": { "type": "string", "enum": [ "post", "account" ] }, "value": { "type": [ "number", "null" ] }, "availability": { "type": "string", "enum": [ "available", "partial", "not_returned", "unsupported", "permission_required", "threshold_not_met", "no_data", "failed", "pending", "stale" ] }, "reason": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "measurement": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "lifetime", "snapshot", "period", "unknown" ] }, "period": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "start": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "end": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] } }, "required": [ "kind", "period", "start", "end", "timezone" ], "additionalProperties": false }, "sourcePath": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "key", "definition", "unit", "grain", "value", "availability", "reason", "measurement", "sourcePath" ], "additionalProperties": false } } }, "required": [ "accountId", "platform", "resourceKind", "providerResourceId", "requestId", "status", "reason", "envelope", "metrics" ], "additionalProperties": false } }, "coverage": { "type": "object", "properties": { "population": { "type": "string", "enum": [ "discovered_posts" ] }, "postsComplete": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string", "maxLength": 16384 }, { "type": "null" } ] }, "postLimit": { "type": "integer", "minimum": 0, "maximum": 1000 }, "postInsightsLimit": { "type": "integer", "minimum": 0, "maximum": 20 }, "omittedPostInsights": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "notes": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 2000 } } }, "required": [ "population", "postsComplete", "nextCursor", "postLimit", "postInsightsLimit", "omittedPostInsights", "notes" ], "additionalProperties": false }, "customMetrics": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "expression": { "type": "string", "minLength": 1, "maxLength": 1000 }, "definition": { "type": "string", "maxLength": 1000 }, "unit": { "type": "string", "maxLength": 100 }, "grain": { "type": "string", "enum": [ "post", "account", "compatible_sum" ] }, "rounding": { "type": "object", "properties": { "decimalPlaces": { "type": "integer", "minimum": 0, "maximum": 8 }, "mode": { "type": "string", "enum": [ "half_away_from_zero" ] } }, "required": [ "decimalPlaces", "mode" ], "additionalProperties": false }, "inputs": { "maxItems": 5000, "type": "array", "items": { "type": "object", "properties": { "requestId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sourcePath": { "type": "string", "maxLength": 2000 }, "value": { "type": [ "number", "null" ] }, "availability": { "type": "string", "enum": [ "available", "partial", "not_returned", "unsupported", "permission_required", "threshold_not_met", "no_data", "failed", "pending", "stale" ] } }, "required": [ "requestId", "sourcePath", "value", "availability" ], "additionalProperties": false } }, "value": { "type": [ "number", "null" ] }, "availability": { "type": "string", "enum": [ "available", "partial", "not_returned", "unsupported", "permission_required", "threshold_not_met", "no_data", "failed", "pending", "stale" ] }, "reason": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "formula": { "type": "object", "properties": { "contractVersion": { "type": "string", "enum": [ "analytics-metric/v1" ] }, "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "version": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "expression": { "type": "string", "minLength": 1, "maxLength": 1000 }, "fields": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "selector": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "facebook", "instagram", "threads", "youtube" ] }, "key": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,100}$" }, "definition": { "type": "string", "minLength": 1, "maxLength": 500 }, "unit": { "type": "string", "enum": [ "count", "seconds", "minutes", "percent", "ratio" ] }, "grain": { "type": "string", "enum": [ "post", "account" ] }, "measurementKind": { "type": "string", "enum": [ "lifetime", "snapshot", "period", "unknown" ] }, "nativePeriod": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] } }, "required": [ "platform", "key", "definition", "unit", "grain", "measurementKind", "nativePeriod", "timezone" ], "additionalProperties": false }, "aggregation": { "type": "string", "enum": [ "single", "sum" ] } }, "required": [ "identifier", "selector", "aggregation" ], "additionalProperties": false } }, "rounding": { "type": "object", "properties": { "decimalPlaces": { "type": "integer", "minimum": 0, "maximum": 8 }, "mode": { "type": "string", "enum": [ "half_away_from_zero" ] } }, "required": [ "decimalPlaces", "mode" ], "additionalProperties": false } }, "required": [ "contractVersion", "id", "workspaceId", "name", "version", "expression", "fields", "rounding" ], "additionalProperties": false }, "calculation": { "type": "object", "properties": { "contractVersion": { "type": "string", "enum": [ "analytics-metric/v1" ] }, "workspaceId": { "type": "string", "format": "uuid" }, "datasetId": { "type": "string", "minLength": 1, "maxLength": 100 }, "formulaId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "expression": { "type": "string", "maxLength": 1000 }, "rounding": { "type": "object", "properties": { "decimalPlaces": { "type": "integer", "minimum": 0, "maximum": 8 }, "mode": { "type": "string", "enum": [ "half_away_from_zero" ] } }, "required": [ "decimalPlaces", "mode" ], "additionalProperties": false }, "value": { "type": [ "number", "null" ] }, "unit": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "available", "not_returned" ] }, "code": { "type": "string", "enum": [ "ok", "invalid_expression", "missing_input", "incompatible_input", "zero_denominator", "numeric_limit", "workspace_mismatch", "ambiguous_input", "unknown_exclusion" ] }, "reason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "excludedInputIds": { "maxItems": 5000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1500 } }, "inputs": { "maxItems": 5000, "type": "array", "items": { "type": "object", "properties": { "inputId": { "type": "string", "minLength": 1, "maxLength": 1500 }, "selector": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "facebook", "instagram", "threads", "youtube" ] }, "key": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,100}$" }, "definition": { "type": "string", "minLength": 1, "maxLength": 500 }, "unit": { "type": "string", "enum": [ "count", "seconds", "minutes", "percent", "ratio" ] }, "grain": { "type": "string", "enum": [ "post", "account" ] }, "measurementKind": { "type": "string", "enum": [ "lifetime", "snapshot", "period", "unknown" ] }, "nativePeriod": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] } }, "required": [ "platform", "key", "definition", "unit", "grain", "measurementKind", "nativePeriod", "timezone" ], "additionalProperties": false }, "value": { "type": [ "number", "null" ] }, "availability": { "type": "string", "enum": [ "available", "partial", "not_returned", "unsupported", "permission_required", "threshold_not_met", "no_data", "failed", "pending", "stale" ] }, "reason": { "anyOf": [ { "type": "string", "maxLength": 8000 }, { "type": "null" } ] }, "measurement": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "lifetime", "snapshot", "period", "unknown" ] }, "period": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "start": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "end": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] } }, "required": [ "kind", "period", "start", "end", "timezone" ], "additionalProperties": false }, "requestId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sourcePath": { "type": "string", "minLength": 1, "maxLength": 1000 }, "accountId": { "type": "string", "format": "uuid" }, "providerResourceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ] }, "fetchedAt": { "anyOf": [ { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" }, { "type": "null" } ] }, "identifier": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "included": { "type": "boolean" } }, "required": [ "inputId", "selector", "value", "availability", "reason", "measurement", "requestId", "sourcePath", "accountId", "providerResourceId", "fetchedAt", "identifier", "included" ], "additionalProperties": false } } }, "required": [ "contractVersion", "workspaceId", "datasetId", "formulaId", "name", "version", "expression", "rounding", "value", "unit", "status", "code", "reason", "excludedInputIds", "inputs" ], "additionalProperties": false } }, "required": [ "id", "name", "version", "expression", "definition", "unit", "grain", "rounding", "inputs", "value", "availability", "reason" ], "additionalProperties": false } } }, "required": [ "contractVersion", "id", "reviewedAt", "selection", "accounts", "posts", "sources", "coverage", "customMetrics" ], "additionalProperties": false }, "excluded_input_ids": { "maxItems": 5000, "type": "array", "items": { "type": "string", "maxLength": 4000 } }, "expected_version": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] }, "mutation_id": { "type": "string", "format": "uuid" }, "calculation": { "type": "object", "properties": { "contractVersion": { "type": "string", "enum": [ "analytics-metric/v1" ] }, "workspaceId": { "type": "string", "format": "uuid" }, "datasetId": { "type": "string", "minLength": 1, "maxLength": 100 }, "formulaId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "expression": { "type": "string", "maxLength": 1000 }, "rounding": { "type": "object", "properties": { "decimalPlaces": { "type": "integer", "minimum": 0, "maximum": 8 }, "mode": { "type": "string", "enum": [ "half_away_from_zero" ] } }, "required": [ "decimalPlaces", "mode" ], "additionalProperties": false }, "value": { "type": [ "number", "null" ] }, "unit": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "available", "not_returned" ] }, "code": { "type": "string", "enum": [ "ok", "invalid_expression", "missing_input", "incompatible_input", "zero_denominator", "numeric_limit", "workspace_mismatch", "ambiguous_input", "unknown_exclusion" ] }, "reason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "excludedInputIds": { "maxItems": 5000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1500 } }, "inputs": { "maxItems": 5000, "type": "array", "items": { "type": "object", "properties": { "inputId": { "type": "string", "minLength": 1, "maxLength": 1500 }, "selector": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "facebook", "instagram", "threads", "youtube" ] }, "key": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,100}$" }, "definition": { "type": "string", "minLength": 1, "maxLength": 500 }, "unit": { "type": "string", "enum": [ "count", "seconds", "minutes", "percent", "ratio" ] }, "grain": { "type": "string", "enum": [ "post", "account" ] }, "measurementKind": { "type": "string", "enum": [ "lifetime", "snapshot", "period", "unknown" ] }, "nativePeriod": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] } }, "required": [ "platform", "key", "definition", "unit", "grain", "measurementKind", "nativePeriod", "timezone" ], "additionalProperties": false }, "value": { "type": [ "number", "null" ] }, "availability": { "type": "string", "enum": [ "available", "partial", "not_returned", "unsupported", "permission_required", "threshold_not_met", "no_data", "failed", "pending", "stale" ] }, "reason": { "anyOf": [ { "type": "string", "maxLength": 8000 }, { "type": "null" } ] }, "measurement": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "lifetime", "snapshot", "period", "unknown" ] }, "period": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "start": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "end": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] } }, "required": [ "kind", "period", "start", "end", "timezone" ], "additionalProperties": false }, "requestId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sourcePath": { "type": "string", "minLength": 1, "maxLength": 1000 }, "accountId": { "type": "string", "format": "uuid" }, "providerResourceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ] }, "fetchedAt": { "anyOf": [ { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" }, { "type": "null" } ] }, "identifier": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "included": { "type": "boolean" } }, "required": [ "inputId", "selector", "value", "availability", "reason", "measurement", "requestId", "sourcePath", "accountId", "providerResourceId", "fetchedAt", "identifier", "included" ], "additionalProperties": false } } }, "required": [ "contractVersion", "workspaceId", "datasetId", "formulaId", "name", "version", "expression", "rounding", "value", "unit", "status", "code", "reason", "excludedInputIds", "inputs" ], "additionalProperties": false } }, "required": [ "workspace_id", "formula", "dataset", "expected_version", "mutation_id" ], "additionalProperties": false } ``` ## 結構化輸出 此 schema 描述成功工具結果的 structuredContent。MCP envelope 亦包括 content，失敗時可能設定 isError；請勿將文字收據或已接受的請求視為平台終態。權限及重試規則請參閱對應的 API 操作。 ```json { "type": "object", "properties": { "definition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "metric", "template" ] }, "workspace_id": { "type": "string", "format": "uuid" }, "definition_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "name": { "type": "string", "maxLength": 100 }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "source_object_key": { "type": [ "string", "null" ] }, "source_sha256": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" }, "archived": { "type": "boolean" } }, "required": [ "id", "kind", "workspace_id", "definition_id", "version", "name", "payload", "source_object_key", "source_sha256", "created_at", "archived" ], "additionalProperties": false }, "replayed": { "type": "boolean" } }, "required": [ "definition", "replayed" ], "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false } ``` ## 工具呼叫範例 以下虛構值已按 contract 驗證，並非真實帳戶 ID、憑證或發佈紀錄。請以已授權範圍回傳的 ID、已準備完成的素材及已審核排程取代，並在寫入前核對平台資格。此頁不會呼叫 API。 ```json { "name": "sosoapi_save_custom_metric", "arguments": { "workspace_id": "11111111-1111-4111-8111-111111111111", "formula": { "contractVersion": "analytics-metric/v1", "id": "11111111-1111-4111-8111-111111111111", "workspaceId": "11111111-1111-4111-8111-111111111111", "name": "example", "version": 1, "expression": "example", "fields": [], "rounding": { "decimalPlaces": 0, "mode": "half_away_from_zero" } }, "dataset": { "contractVersion": "analytics-report/v1", "id": "11111111-1111-4111-8111-111111111111", "reviewedAt": "2099-01-15T09:00:00Z", "selection": { "workspaceId": "11111111-1111-4111-8111-111111111111", "accountIds": [ "11111111-1111-4111-8111-111111111111" ], "platforms": [ "facebook" ], "startDate": "2099-01-15", "endDate": "2099-01-15", "timezone": "UTC" }, "accounts": [ { "id": "11111111-1111-4111-8111-111111111111", "workspaceId": "11111111-1111-4111-8111-111111111111", "platform": "facebook", "name": "Fictional report account" } ], "posts": [], "sources": [], "coverage": { "population": "discovered_posts", "postsComplete": false, "nextCursor": null, "postLimit": 0, "postInsightsLimit": 0, "omittedPostInsights": 0, "notes": [] }, "customMetrics": [] }, "expected_version": null, "mutation_id": "11111111-1111-4111-8111-111111111111" } } ``` structuredContent ```json { "definition": { "id": "11111111-1111-4111-8111-111111111111", "kind": "metric", "workspace_id": "11111111-1111-4111-8111-111111111111", "definition_id": "11111111-1111-4111-8111-111111111111", "version": 1, "name": "example", "payload": {}, "source_object_key": "example", "source_sha256": "example", "created_at": "2099-01-15T09:00:00Z", "archived": false }, "replayed": false } ``` ## 對應 API 操作 - [/analytics-api/reporting/metrics/save](https://sosoapi.ai/zh-hant/docs/api/analytics-api-reporting-metrics-save)