批量校验黑名单

大约 3 分钟

批量校验黑名单

功能说明

批量校验是否在用户的黑名单中。

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

前提条件

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

认证方式

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

Authorization: Bearer YourAppToken

为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 推荐使用 app token 的鉴权方式,详见 使用 App Token 鉴权

HTTP 请求

POST https://{host}/{org_name}/{app_name}/blocks/check

路径参数

参数及描述详见 公共参数

请求 header

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

请求 body

参数类型是否必需
描述
usernameString要校验该用户 ID 的黑名单。
check_listJSON Array要校验的黑名单中用户 ID 列表,每次请求最多可传 100 个用户 ID。

HTTP 响应

响应 body

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

字段类型描述
entitiesJSON Array校验结果的详情。
- usernameString校验的用户 ID。
- relationString用户是否在黑名单中:
- blacklist:是
- not_blacklist:否

其他字段及描述详见 公共参数

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

示例

请求示例

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

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/blocks/check' -d '{
    "username": "user1", 
    "check_list": [ 
    "user2",
    "user3"
    ]
  }'

响应示例

{
  "action": "post",
  "application": "8bXXXX402",
  "path": "/contacts/check",
  "uri": "https://XXXX/XXXX/XXXX/blocks/check",
  "entities": [
    {
        "username":"user2",
        "relation":"blacklist"
    },
    {
        "username":"user3",
        "relation":"not_blacklist"
    }
  ],
  "timestamp": 1542598913819,
  "duration": 63,
  "organization": "XXXX",
  "applicationName": "testapp"
}

错误码

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

HTTP 状态码错误类型错误提示可能原因处理建议
401unauthorizedUnable to authenticate (OAuth)Token 不合法,可能过期或 Token 错误。使用新的 Token 访问。
429reach_limitThis request has reached api limit.接口调用超过频率限制。联系商务调整限流或者控制调用速率。
403forbidden_service_operationService operation not allowedapp 或用户被封禁。先解禁 app 或用户后再调用该接口。
400illegal_argumentusername cannot be blank校验的用户 username 不能传空。确认参数 username 是否正确填写。
400illegal_argumentcheck_list size must be between 1 and 100被校验的用户列表只能包含 1 到 100 个用户。确认 check_list 参数是否正确填写。

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