全局 header 参数

参数名类型是否必传说明
platformNumberYES平台编号(配置表 platforms 键名的键值)
versionStringYES语义化版本号
versionIntNumberYES整型版本号
appIdStringYESApp ID(密钥表 session_keys > app_id 字段)
timestampStringYES签名生成时间(当前 Unix 时间戳,精确到秒或毫秒都支持)
signStringYES请求签名(解析签名后验证 session_keys > app_secret 密钥信息)
langTagStringNO语言标签(留空则输出默认语言,配置表键名 default_language
timezoneStringNOUTC 时区(留空则使用默认时区,配置表键名 default_timezone
uidStringYES/NO用户参数(用户主表 users > uuid 字段)
midNumberYES/NO成员参数(成员主表 members > uuid 字段)
tokenStringYES/NO身份凭证(凭证表 session_tokens > token 字段)
deviceInfoStringYES交互设备信息 session_logs > device_info
以字符串传参压缩后的 Object 对象信息

使用 API 阅读

运行模式介绍

  • 配置表键名 site_mode
    • 公开模式,键值为 public
    • 私有模式,键值为 private

签名生成规则

  • 1、参与签名的 header 参数
// header 中参与签名的参数
const SIGN_FIELD_ARR = [
    'platform',
    'version',
    'versionInt',
    'appId',
    'timestamp',
    'uid',
    'mid',
    'token'
];
1
2
3
4
5
6
7
8
9
10
11
  • 2、获取签名 App Secret,该值配置在客户端中
  • 3、签名方法
    • 3.1、将 SIGN_FIELD_ARR 中的参数按照参数名 ASCII 码从小到大排序(字典序),使用 URL 键值对的格式(即 key1=value1&key2=value2… )拼接成字符串 stringA
    • 3.2、在 stringA 最后拼接上 &key={app_secret} 得到待签名字符串 stringSignTemp
    • 3.3、对 stringSignTemp 进行 MD5 运算(32 位小写),得到签名值 signValue

生成签名 PHP 示例:

//对数组的值按key排序
ksort($dataMap);

//生成 url 的形式
$params = http_build_query($dataMap);

//生成 sign
$sign = md5($params . "&key={$app_secret}");
1
2
3
4
5
6
7
8

开发 API 阅读

基础参数说明

  • 平台编号、语义化版本号、整型版本号为必填项,交互日志表的对应字段也采用此处参数。
  • 请求权限验证要求
    • 1、验证 appIdplatform 参数
      • 1.1、是否存在 session_keys > app_id
      • 1.2、是否匹配 session_keys > platform_id
      • 1.3、是否启用 session_keys > is_enable
    • 2、验证 appId 是否有权请求 session_keys > type
      • 2.1、type = 1 有权
      • 2.2、type = 2 无权
    • 3、根据 timestampsign 参数,解析出 app_idapp_secret 信息
    • 4、验证 sign 是否正确
      • 4.1、解析出来的 app_id 是否和 header 里的 appId 一致
      • 4.2、解析出来的 app_secret 是否和该 app_id 记录的 session_keys > app_secret 一致

用户参数说明

  • uidmidtoken 三个参数为选填项,不填写代表未登录状态。
  • 未登录状态下,部分接口可以请求,部分接口不可请求,具体以接口文档页「用户参数」和「成员参数」描述为准。
  • 如果填写了 uid 值,则 token 值为必填项,用于验证账号交互凭证。如果填写了 mid,则 uidtoken 参数必填。
  • 不同情况下请求权限验证方式
    • 未登录uidmidtoken 未填写参数,视为未登录,返回未登录可输出的数据。
    • 用户和成员权限验证时,需要先到 users 或 members 表,获取真实的 ID 值 user_id 或 member_id
    • 用户权限:验证 platformuidtoken 参数,查验 session_tokensuser_idtokenplatform_id 字段是否匹配。
    • 成员权限:验证 platformuidmidtoken 四个参数,查验 session_tokensuser_idmember_idtokenplatform_id 字段是否匹配。
  • 填写用户和成员参数后,账号判断规则如下:
    • 1、用户状态 users > deleted_at 注销,不可请求需要用户参数的接口,但是可以请求「登录」、「恢复」、「用户基本信息」、「退出登录」接口。
    • 2、用户状态 users > is_enable 禁用,不可请求需要用户参数的接口,但是可以请求「用户基本信息」、「退出登录」接口。
    • 3、成员状态 members > deleted_at 注销,不可请求需要成员参数的接口。
    • 4、成员状态 members > is_enable 禁用,不可请求需要成员参数的接口。
    • 5、成员主角色权限 member_roles > permission > content_view 是否允许浏览,如果禁止浏览,不可请求「内容类」和「消息类」接口;如果主角色有过期时间,并且已经过期,则以继承角色权限为主;如果无继承角色(或者该继承 ID 找不到角色),则以配置表 default_role 键名键值的角色权限为准;如果配置表键值为空(或找不到角色),则当无权处理。
    • 6、站点模式配置键名 site_modeprivate 时,判断成员 members > expired_at 是否在有效期内,当过期后,以下接口按「到期后的状态」配置设置特殊处理(详情见相应接口描述)。
      • 操作标记内容 /api/fresns/member/mark
      • [会话]发送消息 /api/fresns/dialog/send
      • 获取帖子[列表] /api/fresns/post/lists
      • 获取帖子[单条] /api/fresns/post/detail
      • 获取帖子关注的[列表] /api/fresns/post/follows
      • 获取帖子附近的[列表] /api/fresns/post/nearbys
      • 获取评论[列表] /api/fresns/comment/lists
      • 获取评论[单条] /api/fresns/comment/detail
      • 创建新草稿 /api/fresns/editor/create
      • 获取上传凭证 /api/fresns/editor/uploadToken
      • 上传文件 /api/fresns/editor/upload
      • 更新草稿内容 /api/fresns/editor/update
      • 快速发表 /api/fresns/editor/publish
      • 提交内容 /api/fresns/editor/submit

运行模式介绍

  • 配置表键名 site_mode
    • 公开模式,键值为 public
    • 私有模式,键值为 private

签名验证规则

  • 1、获取 header 中参与签名的参数
// header 中参与签名的参数
const SIGN_FIELD_ARR = [
    'platform',
    'version',
    'versionInt',
    'appId',
    'timestamp',
    'uid',
    'mid',
    'token'
];
1
2
3
4
5
6
7
8
9
10
11
  • 2、获取 header 中传入的签名参数 sign 赋值给 inputSign
$inputSign = $request->header('sign');
1
  • 3、根据 header 中的 appId 参数,查询获得 app_secret
  • 4、生成比对的签名 compareSign
    • 4.1、将 SIGN_FIELD_ARR 中的参数按照参数名 ASCII 码从小到大排序(字典序),使用 URL 键值对的格式(即 key1=value1&key2=value2… )拼接成字符串 stringA
    • 4.2、在 stringA 最后拼接上 &key={app_secret} 得到待签名字符串 stringSignTemp
    • 4.3、对 stringSignTemp 进行 MD5 运算,得到签名值 signValue
//对数组的值按 key 排序
ksort($dataMap);

//生成 url 的形式
$params = http_build_query($dataMap);

//生成 sign
$sign = md5($params . "&key={$app_secret}");
1
2
3
4
5
6
7
8
  • 5、输入的签名和生成的签名做比对,如果相等,则返回验证正确。
if ($inputSign == $compareSign) {
    return true;
}
1
2
3