轮换私有逻辑缓存组

POST

/t1/cache/v1/bindings/{bindingId}/rotate

curl --request POST \
  --url https://api.tansr.com/t1/cache/v1/bindings/example/rotate \
  --header 'Content-Type: application/json' \
  --header 'x-tansr-app-token: <x-tansr-app-token>' \
  --data '{ "protocol": "sdk2-cache-v1", "request": { "operationEpoch": "example", "requestId": "example" }, "bindingId": "example", "expectedRevision": "example", "ticket": "example", "reason": "manual" }'

仅接受当前 app_user 短期令牌，并按当前应用、末端用户和原会话验证权限。此扩展默认关闭；未启用时不提供控制接口。GET 不接受请求体，所有查询参数只能出现一次；拒绝未知参数。POST 不接受查询串或 Content-Encoding。

控制 JSON 最多 65536 字节；拒绝重复键、未知字段、无效 UTF-8、未配对代理项和非整数数字词法（含小数、指数、负零）。序号必须是 0..9223372036854775807 的规范十进制字符串，不能经 Number 转换。

请求体 bindingId 必须与路径一致；reason 仅允许 manual，携带当前 ticket 和 expectedRevision。

Authorizations

• appToken

Parameters

Path Parameters

bindingId

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

Request Body^required

Media typeapplication/json

object

protocol

required

Allowed value: sdk2-cache-v1

request

required

object

operationEpoch

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

requestId

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

bindingId

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

expectedRevision

required

Canonical unsigned decimal 0..2^63-1. Never parse through IEEE754 Number.

string

<= 19 characters /^(0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$/

ticket

required

string

>= 43 characters <= 43 characters /^[A-Za-z0-9_-]{43}$/

reason

required

Allowed value: manual

Responses

200

成功；相同操作身份按原结果重放。

Media typeapplication/json

object

protocol

required

Allowed value: sdk2-cache-v1

request

required

object

operationEpoch

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

requestId

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

operation

required

string

Allowed values: open renew rotate close rebind

semanticDigest

required

object

algorithm

required

Allowed value: hmac-sha256

keyId

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

digest

required

string

/^[a-f0-9]{64}$/

state

required

Allowed value: completed

binding

required

object

protocol

required

Allowed value: sdk2-cache-v1

audience

required

Allowed value: gateway-cache

bindingId

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

logicalRef

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

revision

required

Canonical unsigned decimal 0..2^63-1. Never parse through IEEE754 Number.

string

<= 19 characters /^(0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$/

state

required

string

Allowed values: active closed revoked expired

mode

required

Allowed value: private-logical-v1

groupGeneration

required

Canonical unsigned decimal 0..2^63-1. Never parse through IEEE754 Number.

string

<= 19 characters /^(0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$/

projection

required

Any of:

object

object

projectionRef

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

revision

required

Canonical unsigned decimal 0..2^63-1. Never parse through IEEE754 Number.

string

<= 19 characters /^(0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6]|9223372036854775807)$/

status

required

string

Allowed values: current rebuild-required missing

reason

required

string

Allowed values: unchanged policy-changed generation-changed provider-changed source-missing legacy-missing key-rotated

null

null

expiresAt

required

string format: date-time

availability

required

Allowed value: legacy-complete

ticket

required

Any of:

string

string

>= 43 characters <= 43 characters /^[A-Za-z0-9_-]{43}$/

null

null

ticketExpiresAt

required

Any of:

string

string format: date-time

null

null

Example

{
  "protocol": "sdk2-cache-v1",
  "operation": "open",
  "semanticDigest": {
    "algorithm": "hmac-sha256"
  },
  "state": "completed",
  "binding": {
    "protocol": "sdk2-cache-v1",
    "audience": "gateway-cache",
    "state": "active",
    "mode": "private-logical-v1",
    "projection": {
      "status": "current",
      "reason": "unchanged"
    },
    "availability": "legacy-complete"
  }
}

Headers

Cache-Control

required

string

Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

400

Invalid_request 或 protocol_version_mismatch

Media typeapplication/json

object

protocol

required

Allowed value: sdk2-cache-v1

requestId

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

code

required

string

Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown

status

required

integer

>= 400 <= 503

retryAction

required

string

Allowed values: none same-request query-status refresh-projection

fallback

required

Allowed value: none

message

required

string

>= 1 characters <= 256 characters

Example

{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Cache-Control

required

string

Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

401

Unauthorized

Media typeapplication/json

object

protocol

required

Allowed value: sdk2-cache-v1

requestId

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

code

required

string

Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown

status

required

integer

>= 400 <= 503

retryAction

required

string

Allowed values: none same-request query-status refresh-projection

fallback

required

Allowed value: none

message

required

string

>= 1 characters <= 256 characters

Example

{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Cache-Control

required

string

Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

403

Forbidden

Media typeapplication/json

object

protocol

required

Allowed value: sdk2-cache-v1

requestId

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

code

required

string

Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown

status

required

integer

>= 400 <= 503

retryAction

required

string

Allowed values: none same-request query-status refresh-projection

fallback

required

Allowed value: none

message

required

string

>= 1 characters <= 256 characters

Example

{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Cache-Control

required

string

Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

409

Stale_revision、stale_generation、request_id_conflict 或 projection_stale

Media typeapplication/json

object

protocol

required

Allowed value: sdk2-cache-v1

requestId

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

code

required

string

Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown

status

required

integer

>= 400 <= 503

retryAction

required

string

Allowed values: none same-request query-status refresh-projection

fallback

required

Allowed value: none

message

required

string

>= 1 characters <= 256 characters

Example

{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Cache-Control

required

string

Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

410

Ticket_expired、mapping_expired 或 receipt_expired

Media typeapplication/json

object

protocol

required

Allowed value: sdk2-cache-v1

requestId

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

code

required

string

Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown

status

required

integer

>= 400 <= 503

retryAction

required

string

Allowed values: none same-request query-status refresh-projection

fallback

required

Allowed value: none

message

required

string

>= 1 characters <= 256 characters

Example

{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Cache-Control

required

string

Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

413

Payload_too_large

Media typeapplication/json

object

protocol

required

Allowed value: sdk2-cache-v1

requestId

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

code

required

string

Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown

status

required

integer

>= 400 <= 503

retryAction

required

string

Allowed values: none same-request query-status refresh-projection

fallback

required

Allowed value: none

message

required

string

>= 1 characters <= 256 characters

Example

{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Cache-Control

required

string

Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

422

Unsupported_capability

Media typeapplication/json

object

protocol

required

Allowed value: sdk2-cache-v1

requestId

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

code

required

string

Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown

status

required

integer

>= 400 <= 503

retryAction

required

string

Allowed values: none same-request query-status refresh-projection

fallback

required

Allowed value: none

message

required

string

>= 1 characters <= 256 characters

Example

{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Cache-Control

required

string

Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

429

Capacity_exceeded

Media typeapplication/json

object

protocol

required

Allowed value: sdk2-cache-v1

requestId

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

code

required

string

Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown

status

required

integer

>= 400 <= 503

retryAction

required

string

Allowed values: none same-request query-status refresh-projection

fallback

required

Allowed value: none

message

required

string

>= 1 characters <= 256 characters

Example

{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Cache-Control

required

string

Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

503

Epoch_unavailable、mapping_unavailable 或 result_unknown；未知结果不得自动重新执行或回退旧接口。

Media typeapplication/json

object

protocol

required

Allowed value: sdk2-cache-v1

requestId

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/

code

required

string

Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown

status

required

integer

>= 400 <= 503

retryAction

required

string

Allowed values: none same-request query-status refresh-projection

fallback

required

Allowed value: none

message

required

string

>= 1 characters <= 256 characters

Example

{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Cache-Control

required

string

Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

本文是否有帮助?

有帮助没帮助