docs: update api documents (#55)

docs/.vuepress/config.js

@@ -12,6 +12,13 @@ module.exports = {
     docsDir: "docs",
     editLinkText: "编辑",
     lastUpdatedText: "最近更新时间",
+    locales: {
+      '/': {
+        tip: '说明',
+        warning: '注意',
+        danger: '警告',
+      },
+    },
     sidebar: [
       {
         text: "指南",

docs/guide/README.md

 # 介绍
 
-本文档基于 QCloud IM Server SDK Java <Badge type="tip" text="v0.2.5" vertical="top" /> 编写。
+本文档基于腾讯云 IM Server SDK Java <Badge type="tip" text="v0.2.5" vertical="top" /> 编写。
 
-## 环境依赖
+## 前提条件
+
+- 已 [注册腾讯云](https://cloud.tencent.com/document/product/378/17985) 账号并完成 [实名认证](https://cloud.tencent.com/document/product/378/3629)。
+- 已登录 [即时通信 IM 控制台](https://console.cloud.tencent.com/im) 并创建了应用。创建完成后，可以拿到 `sdkAppId` 以及 `key`。
+- 已创建 App 管理员帐号 `userId`，也即 `identifier`。
+
+    <img src="https://cdn.jsdelivr.net/gh/doocs/qcloud-im-server-sdk-java@main/docs/assets/create_identifier.png" />
+
+::: tip
+“App 管理员”是对 App 具有最高管理权限的角色，可调用 [REST API 接口](https://cloud.tencent.com/document/product/269/1519?from_cn_redirect=1)，进行创建/解散群组、发送全员推送消息等操作。每个应用最多支持配置 10 个管理员。
+:::
+
+## SDK 环境依赖
 
 - Java 8 及以上版本
 - Maven
@@ -11,7 +23,6 @@
 
 SDK 源码请参见 [GitHub](https://github.com/doocs/qcloud-im-server-sdk-java)。
 
-
 ## 项目贡献者
 
-<a href="https://github.com/doocs/qcloud-im-server-sdk-java/graphs/contributors" target="_blank"><img src="https://cdn.jsdelivr.net/gh/doocs/qcloud-im-server-sdk-java@main/docs/assets/contributors.svg" /></a>
\ No newline at end of file
+<a href="https://github.com/doocs/qcloud-im-server-sdk-java/graphs/contributors" target="_blank"><img src="https://cdn.jsdelivr.net/gh/doocs/qcloud-im-server-sdk-java@main/docs/assets/contributors.svg" /></a>

docs/guide/account.md

@@ -4,7 +4,7 @@
 
 本接口用于将 App 自有帐号导入即时通信 IM 帐号系统，为该帐号创建一个对应的内部 ID，使该帐号能够使用即时通信 IM 服务。
 
-::: tip 说明
+::: tip
 同一个帐号重复导入仅会创建 1 个内部 ID。
 :::
 
@@ -78,7 +78,7 @@ AccountCheckResult result = client.account.accountCheck(request);
 
 例如，开发者判断一个用户为恶意帐号后，可以调用本接口将该用户当前的登录状态失效，这样用户使用历史 UserSig 登录即时通信 IM 会失败。
 
-::: warning 注意
+::: warning
 支持一次失效一个帐号，用户可以使用重新生成的 UserSig 登录即时通信 IM
 :::
 

docs/guide/group.md

@@ -4,7 +4,7 @@
 
 App 管理员可以通过该接口获取 App 中所有群组的 ID。
 
-::: tip 说明
+::: tip
 即时通信 IM 内置多种群组类型，详情请参见 [群组系统](https://cloud.tencent.com/document/product/269/1502)。
 :::
 
@@ -46,7 +46,7 @@ CreateGroupResult result = client.group.createGroup(request);
 
 App 管理员可以根据群组 ID 获取群组的详细信息。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -71,7 +71,7 @@ GetGroupInfoResult result = client.group.getGroupInfo(request);
 
 App 管理员可以根据群组 ID 获取群组成员的资料。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -100,7 +100,7 @@ GetGroupMemberInfoResult result = client.group.getGroupMemberInfo(request);
 
 App 管理员可以通过该接口修改指定群组的基础信息。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -134,7 +134,7 @@ ModifyGroupBaseInfoResult result = client.group.modifyGroupBaseInfo(request);
 
 App 管理员可以通过该接口向指定的群中添加新成员。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -165,7 +165,7 @@ AddGroupMemberResult result = client.group.addGroupMember(request);
 
 App 管理员可以通过该接口删除群成员。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -196,7 +196,7 @@ DeleteGroupMemberResult result = client.group.deleteGroupMember(request);
 
 App 管理员可以通过该接口修改群成员资料。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -227,7 +227,7 @@ ModifyGroupMemberInfoResult result = client.group.modifyGroupMemberInfo(request)
 
 App 管理员通过该接口解散群。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -252,7 +252,7 @@ DestroyGroupResult result = client.group.destroyGroup(request);
 
 App 管理员可以通过本接口获取某一用户加入的群信息。默认不获取用户已加入但未激活好友工作群（Work）以及直播群（AVChatRoom）群信息。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                                                                                                               |
@@ -277,7 +277,7 @@ GetJoinGroupListResult result = client.group.getJoinGroupList(request);
 
 App 管理员可以通过该接口获取一批用户在群内的身份，即“成员角色”。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -309,7 +309,7 @@ GetRoleInGroupResult result = client.group.getRoleInGroup(request);
 - App 管理员取消对某些用户的禁言。
 - 被禁言用户退出群组之后再进入同一群组，禁言仍然有效。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -340,7 +340,7 @@ ForbidSendMsgResult result = client.group.forbidSendMsg(request);
 
 App 管理员可以根据群组 ID 获取群组中被禁言的用户列表。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -365,7 +365,7 @@ GetGroupShuttedUinResult result = client.group.getGroupShuttedUin(request);
 
 App 管理员可以通过该接口在群组中发送普通消息。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -395,7 +395,7 @@ SendGroupMsgResult result = client.group.sendGroupMsg(request);
 
 App 管理员可以通过该接口在群组中发送系统通知。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -429,7 +429,7 @@ SendGroupSystemNotificationResult result = client.group.sendGroupSystemNotificat
 - 没有群主的群，App 管理员可以通过此接口指定他人作为群主。
 - 新群主必须为群内成员。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -459,7 +459,7 @@ ChangeGroupOwnerResult result = client.group.changeGroupOwner(request);
 
 App 管理员通过该接口撤回指定群组的消息，消息需要在漫游有效期以内。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -488,7 +488,7 @@ GroupMsgRecallResult result = client.group.groupMsgRecall(request);
 App 管理员可以通过该接口导入群组，不会触发回调、不会下发通知；
 当 App 需要从其他即时通信系统迁移到即时通信 IM 时，使用该协议导入存量群组数据。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -519,7 +519,7 @@ ImportGroupResult result = client.group.importGroup(request);
 - 该 API 接口的作用是导入群组的消息，不会触发回调、不会下发通知。
 - 当 App 需要从其他即时通信系统迁移到即时通信 IM 时，使用该协议导入存量群消息数据。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -555,7 +555,7 @@ ImportGroupMsgResult result = client.group.importGroupMsg(request);
 - 该 API 接口的作用是导入群组成员，不会触发回调、不会下发通知。
 - 当 App 需要从其他即时通信系统迁移到即时通信 IM 时，使用该协议导入存量群成员数据。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -591,7 +591,7 @@ ImportGroupMemberResult result = client.group.importGroupMember(request);
 - App 管理员使用该接口设置群组成员未读消息数，不会触发回调、不会下发通知。
 - 当 App 需要从其他即时通信系统迁移到即时通信 IM 时，使用该协议设置群成员的未读消息计数。
 
-::: tip 说明
+::: tip
 该文档仅限迁移用户使用，线上用户不能使用。
 
 适用的群组类型
@@ -624,7 +624,7 @@ SetUnreadMsgNumResult result = client.group.setUnreadMsgNum(request);
 
 该 API 接口的作用是撤回最近 1000 条消息中指定用户发送的消息。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -661,7 +661,7 @@ App 管理员可以通过该接口拉取群组的历史消息。
 - 如果用户想拉取一个群的全量消息，首次拉取时不用填拉取 Seq，Server 会自动返回最新的消息，以后拉取时拉取 Seq 填上次返回的最小 Seq 减 1。
 - 如果返回消息的 IsPlaceMsg 为 1，表示这个 Seq 的消息或者过期、或者存储失败、或者被删除了。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                      |
@@ -692,7 +692,7 @@ GroupMsgGetSimpleResult result = client.group.groupMsgGetSimple(request);
 
 App 管理员可以根据群组 ID 获取直播群在线人数。
 
-::: tip 说明
+::: tip
 适用的群组类型
 
 | 群组类型 ID | 是否支持此 REST API                          |
@@ -705,7 +705,7 @@ App 管理员可以根据群组 ID 获取直播群在线人数。
 即时通信 IM 内置上述群组类型，详情介绍请参见 [群组系统](https://cloud.tencent.com/document/product/269/1502)。
 :::
 
-::: warning 注意
+::: warning
 
 - 在线人数总体更新粒度为 10s。
 - 当群人数大于等于 300 或群内有 Web 端用户的时候，出现群成员上下线或者进退群的时候，由于当前 10s 周期内已经统计了用户在线状态的原因，会在下一个 10s 周期才会统计到剔除状态用户变更的在线人数，所以会出现调用接口 10s - 20s 才会更新的现象。

docs/guide/member.md

@@ -117,7 +117,7 @@ ImGetTagResult result = client.member.imGetTag(request);
 
 管理员给用户添加标签。
 
-::: warning 注意
+::: warning
 
 - 每次请求最多只能给 100 个用户添加标签，请求体中单个用户添加标签数最多为 10 个。
 - 单个用户可设置最大标签数为 100 个，若用户当前标签超过 100，则添加新标签之前请先删除旧标签。

docs/guide/message.md

@@ -115,10 +115,10 @@ AdminRoamMsgResult result = client.message.getRoamMsg(request);
 - 调用该接口撤回消息后，该条消息的离线、漫游存储，以及消息发送方和接收方的客户端的本地缓存都会被撤回。
 - 该接口可撤回的单聊消息没有时间限制，即可以撤回任何时间的单聊消息。
 
-::: warning 注意
+::: warning
 
 使用该接口撤回单聊消息后，被撤回的消息不能恢复，请谨慎调用该接口。
-  :::
+:::
 
 使用示例：
 

docs/guide/operation_2.md

@@ -17,7 +17,7 @@ GetAppInfoResult result = client.operation.getAppInfo(request);
 
 App 管理员可以通过该接口获取 App 中最近 7 天中某天某小时的所有单发或群组消息记录的下载地址。
 
-::: warning 注意
+::: warning
 
 - 下载消息记录里的图片、语音、文件和短视频，此功能仅适用于 4.X 版本 IM SDK，可通过聊天记录中的 URL 字段进行下载。如您使用 2.X 或 3.X 版本的 IM SDK，您将无法通过该方法获取到以上信息，如您需要此功能，请您升级至 4.X 版本。
 - 消息记录以日志文件形式保存并使用 GZip 压缩，通过该接口获取到下载地址后，请自行下载并处理；消息记录文件每小时产生一次，例如 0 点（00:00~00:59）的数据在 01:00 后开始处理，一般 1 小时内处理完毕（消息较多则处理时间较长）；文件有效期 7 天，无论是否下载过，都会在 7 天后删除，被删除后不支持重新导出；获取到的下载地址存在有效期，请在过期前进行下载，若地址失效，请通过该接口重新获取。
@@ -39,7 +39,7 @@ GetHistoryResult result = client.operation.getHistory(request);
 
 基于安全等考虑，您可能需要获知服务器的 IP 地址列表，以便进行相关限制。App 管理员可以通过该接口获得 SDK、第三方回调所使用到的服务器 IP 地址列表或 IP 网段信息。
 
-::: warning 注意
+::: warning
 此接口仅支持获取中国大陆地区的所有 IM 接入方式的 IP 地址或 IP 网段信息。
 :::
 

docs/guide/sns.md

@@ -163,7 +163,7 @@ FriendGetListResult result = client.sns.friendGetList(request);
 
 添加黑名单，支持批量添加黑名单。
 
-::: warning 注意
+::: warning
 
 - 如果用户 A 与用户 B 之间存在好友关系，拉黑时会解除双向好友关系。
 - 如果用户 A 与用户 B 之间存在黑名单关系，二者之间无法发起加好友请求。