切换主题
交换运行时会话
POST /miniapp/v1/apps/{app_id}/runtime/sessions/exchange
应用后端持服务凭据兑换一次性 code，获得 AppID 作用域 openid 和仅后端保存的 token。run_instance_id 必填于请求体，旧客户端若同时传实例 Header，必须与请求体一致。业务登录态由应用后端建立，平台 token 禁止返回 JS。
鉴权与参数
应用后端使用 Authorization: Bearer <本应用服务凭据>。
| 参数 | 位置 | 必填 | 说明 |
|---|---|---|---|
app_id | path | 是 | {"type":"string","pattern":"^[a-z][a-z0-9_-]{2,63}$"} |
请求体
Content-Type：application/json。
| 字段 | 类型 | 在所属对象中必填 | 说明与约束 |
|---|---|---|---|
code | string | 是 | minLength: 1 |
run_instance_id | string | 是 | minLength: 8；maxLength: 128 |
响应
HTTP 201
Session token. The token is returned only here.
| 字段 | 类型 | 在所属对象中必填 | 说明与约束 |
|---|---|---|---|
code | string | 是 | description: 请求成功时返回的稳定业务码。；const: miniapp_success |
data | object | 是 | |
data.session | object | 是 | additionalProperties: false |
data.session.app_id | string | 是 | |
data.session.version | string | 是 | pattern: ^(0|[1-9][0-9])\.(0|[1-9][0-9])\.(0|[1-9][0-9])(?😦?:0|[1-9][0-9]|[0-9A-Za-z-][A-Za-z-][0-9A-Za-z-])(?:\.(?:0|[1-9][0-9]|[0-9A-Za-z-][A-Za-z-][0-9A-Za-z-])))?$ |
data.session.openid | string | 是 | description: 本应用内稳定的用户标识；不同应用互不关联。；pattern: ^oid_[0-9a-f]{48}$ |
data.session.run_instance_id | string | 是 | |
data.session.issued_at | string | 是 | format: date-time |
data.session.expires_at | string | 是 | format: date-time |
data.token | string | 是 |
HTTP 400
请求参数无效。
| 字段 | 类型 | 在所属对象中必填 | 说明与约束 |
|---|---|---|---|
error | object | 是 | |
error.code | string | 是 | |
error.message | string | 是 | |
error.details | object | 否 | additionalProperties: false |
error.details.reason | string | 否 |
HTTP 401
服务凭据或运行时会话无效。
| 字段 | 类型 | 在所属对象中必填 | 说明与约束 |
|---|---|---|---|
error | object | 是 | |
error.code | string | 是 | |
error.message | string | 是 | |
error.details | object | 否 | additionalProperties: false |
error.details.reason | string | 否 |
完整定义
下列定义包含引用、Header 和字段约束，来自同一契约的本接口投影。
查看 JSON Schema 与响应定义
json
{
"openapi": "3.1.0",
"info": {
"title": "MetaEco 应用服务端 API",
"version": "6.0.0"
},
"servers": [
{
"url": "{platformOrigin}",
"description": "导入后填写实际 API 入口；文档域名不承载 API",
"variables": {
"platformOrigin": {
"default": "https://api.example.invalid",
"description": "替换为当前应用分配的 API 网关，示例域名不可访问"
}
}
}
],
"paths": {
"/miniapp/v1/apps/{app_id}/runtime/sessions/exchange": {
"post": {
"summary": "交换运行时会话",
"description": "应用后端持服务凭据兑换一次性 code，获得 AppID 作用域 openid 和仅后端保存的 token。run_instance_id 必填于请求体，旧客户端若同时传实例 Header，必须与请求体一致。业务登录态由应用后端建立，平台 token 禁止返回 JS。",
"tags": [
"runtime"
],
"security": [
{
"serviceCredential": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/AppID"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionExchangeRequest"
}
}
}
},
"responses": {
"201": {
"description": "Session token. The token is returned only here.",
"headers": {
"X-Request-ID": {
"$ref": "#/components/headers/RequestID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionExchangeResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/InvalidRequest"
},
"401": {
"$ref": "#/components/responses/RuntimeUnauthorized"
}
}
}
}
},
"components": {
"securitySchemes": {
"serviceCredential": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "MiniAppServiceCredential",
"description": "小程序运行时和内部服务调用使用的短期服务凭据。"
}
},
"parameters": {
"AppID": {
"name": "app_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^[a-z][a-z0-9_-]{2,63}$"
}
}
},
"schemas": {
"SessionExchangeRequest": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"run_instance_id"
],
"properties": {
"code": {
"type": "string",
"minLength": 1
},
"run_instance_id": {
"type": "string",
"minLength": 8,
"maxLength": 128
}
}
},
"SessionExchangeResponse": {
"type": "object",
"required": [
"code",
"data"
],
"properties": {
"code": {
"$ref": "#/components/schemas/SuccessCode"
},
"data": {
"type": "object",
"required": [
"session",
"token"
],
"properties": {
"session": {
"$ref": "#/components/schemas/Session"
},
"token": {
"type": "string"
}
}
}
}
},
"SuccessCode": {
"type": "string",
"const": "miniapp_success",
"description": "请求成功时返回的稳定业务码。"
},
"Session": {
"type": "object",
"additionalProperties": false,
"required": [
"app_id",
"version",
"openid",
"run_instance_id",
"issued_at",
"expires_at"
],
"properties": {
"app_id": {
"type": "string"
},
"version": {
"$ref": "#/components/schemas/SemVer"
},
"openid": {
"type": "string",
"pattern": "^oid_[0-9a-f]{48}$",
"description": "本应用内稳定的用户标识；不同应用互不关联。"
},
"run_instance_id": {
"type": "string"
},
"issued_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time"
}
}
},
"SemVer": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)\\\\.(0|[1-9][0-9]*)\\\\.(0|[1-9][0-9]*)(?:-(?:0|[1-9][0-9]*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\\\\.(?:0|[1-9][0-9]*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*)?$"
},
"ErrorResponse": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": false,
"properties": {
"reason": {
"type": "string"
}
}
}
}
}
}
}
},
"headers": {
"RequestID": {
"description": "请求追踪 ID，用于关联客户端、网关和服务端日志。",
"schema": {
"type": "string",
"maxLength": 128
}
}
},
"responses": {
"InvalidRequest": {
"description": "请求参数无效。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"RuntimeUnauthorized": {
"description": "服务凭据或运行时会话无效。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
}