查询关键词

大约 4 分钟

查询关键词

功能说明

  • 在单个关键词名单中查询关键词。
  • 该接口为模糊查询。例如，若传入关键词 message，响应中会返回关键词名单中包含该关键词的词条，包括 message``messageid、addmessage 和 deletemessage 等词条。

调用频率上限：100 次/秒/App Key

前提条件

要调用环信即时通讯 RESTful API，请确保满足以下要求：

认证方式

环信即时通讯 REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 Authorization 字段：

Authorization: Bearer YourAppToken

为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。本文介绍的即时通讯所有 RESTful API 均需使用 App Token 的鉴权方式，详见 使用 App Token 鉴权。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/moderation/text/list/{list_id}/word

路径参数

参数类型是否必需描述
hostString是环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 获取环信即时通讯 IM 的信息。
org_nameString是环信即时通讯 IM 为每个公司（组织）分配的唯一标识。详见 获取环信即时通讯 IM 的信息。
app_nameString是你在环信即时通讯云控制台创建应用时填入的应用名称。详见 获取环信即时通讯 IM 的信息。
list_idString是关键词名单 ID。查询该名单中的关键词。

请求 header

参数类型是否必需描述
Content-TypeString是内容类型。请填 application/json。
AcceptString是内容类型。请填 application/json。
AuthorizationString是App 管理员的鉴权 token，格式为 Bearer YourAppToken，其中 Bearer 为固定字符，后面为英文空格和获取到的 app token。

请求 body

参数类型是否必需描述
wordString是要查询的关键词名称。
pageInt否当前页码，默认值为 0。
sizeInt否每页返回的关键词数量，取值范围为 [1,200]，默认值为 10。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

字段类型描述
statusString请求状态。若请求成功，返回 OK。
entitiesJSON Array查询详情。
- idString关键词 ID。
- wordString关键词名称。
- userIdString查询关键词的用户。
- listIdString关键词名单 ID。
- createDateTimeLong关键词添加时间。
- updateDateTimeLong关键词修改时间。
firstBoolean当前页面是否为首页：
- true：是
- false：否
lastBoolean当前页面是否为最后一页：
- true：是
- false：否
sizeInt当前页面返回的与查询关键词模糊匹配的词条。
numberInt当前页码。
numberOfElementsInt当前页面中获取的词条数量。
totalPagesInt页面总数。
totalElementsInt与查询关键词匹配的词条总数量。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 错误码 了解可能的原因。

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST 'https://XXXX/XXXX/XXXX/moderation/text/list/{list_id}/word' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
      "word": "music",
      "size": "3",
      "page": "0"
    }'

响应示例

{
    "status": "OK",
    "entities": [
        {
            "id": "1xXXXX7uZXqAfXzk0Y2OZ3JOhJt",
            "appId": "1DHFtAi7XXXXqsrjCV449Kljh98",
            "word": "musicvideo",
            "userId": "v1",
            "listId": "1r14SOXXXXiSBbR3WTczWj92qsq",
            "status": true,
            "createDateTime": 1752501847581,
            "updateDateTime": 1752501847581
        },
        {
            "id": "1xXXXXUjdvN1LE68wFeILywpks2",
            "appId": "1DHFtAi7XXXXqsrjCV449Kljh98",
            "word": "musicraudio",
            "userId": "v1",
            "listId": "1r14SOXXXXiSBbR3WTczWj92qsq",
            "status": true,
            "createDateTime": 1752501847581,
            "updateDateTime": 1752501847581
        },
        {
            "id": "1xXXXXNiiIOSZmGNMBGgNEZ6jj9",
            "appId": "1DHFtAi7XXXXqsrjCV449Kljh98",
            "word": "music",
            "userId": "v1",
            "listId": "1r14SOXXXXiSBbR3WTczWj92qsq",
            "status": true,
            "createDateTime": 1752489316741,
            "updateDateTime": 1752490995382
        }
    ],
    "first": true,
    "last": true,
    "size": 3,
    "number": 0,
    "numberOfElements": 3,
    "totalPages": 1,
    "totalElements": 3
}

错误码

如果返回的 HTTP 状态码非 200，表示请求失败，可能提示以下错误码：

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)token 不合法，可能过期或 token 错误。使用新的 token 访问。
400Bad requesttextList data is empty未传 list_id。请传入有效的 list_id。
400Bad requestappkey is not existApp Key 是环信即时通讯 IM 分配给每个应用的唯一标识，由 orgname 和 appname 参数的值组成。上报该错误表示 org_name 或者 app_name 不正确。请传入正确的 org_name 和 app_name 参数。

关于其他错误，你可以参考 响应状态码 了解可能的原因。

环信 IM 文档 Version: 1.0.0 ©️环信