拉取指定好友

最近更新时间:2019-08-01 09:51:26

功能说明

支持拉取指定好友的好友数据和资料数据。
建议每次拉取的好友数不超过100,避免因数据量太大导致回包失败。

接口调用说明

请求 URL

https://console.tim.qq.com/v4/sns/friend_get_list?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

请求参数说明

下表仅列出调用本接口时涉及修改的参数及其说明,更多参数详情请参考 REST API 简介

参数 说明
v4/sns/friend_get_list 请求接口
sdkappid 创建应用时即时通信 IM 控制台分配的 SDKAppID
identifier 必须为 App 管理员帐号,更多详情请参见 App 管理员
usersig App 管理员帐号生成的签名,具体操作请参见 生成 UserSig
random 请输入随机的32位无符号整数

最高调用频率

100次/秒。如需提升调用频率,请根据 工单模板 提交工单申请处理。

请求包示例

  • 基础形式
    {
      "From_Account":"UserID_1",
      "To_Account":
      [
          "UserID_2"
      ],
      "TagList":
      [
          "Tag_Profile_Custom_Test",
          "Tag_Profile_IM_Image",
          "Tag_Profile_IM_Nick",
          "Tag_SNS_Custom_Test",
          "Tag_SNS_IM_Remark",
          "Tag_SNS_IM_Group"
      ]
    }
  • 批量形式
    {
      "From_Account":"UserID_1",
      "To_Account":
      [
          "UserID_2",
          "UserID_3",
          "UserID_4"
      ],
      "TagList":
      [
          "Tag_Profile_Custom_Test",
          "Tag_Profile_IM_Image",
          "Tag_Profile_IM_Nick",
          "Tag_SNS_Custom_Test",
          "Tag_SNS_IM_Remark",
          "Tag_SNS_IM_Group"
      ]
    }

请求包字段说明

字段 类型 属性 说明
From_Account String 必填 指定要拉取好友数据的用户的 UserID
To_Account Array 必填 好友的 UserID 列表
建议每次请求的好友数不超过100,避免因数据量太大导致回包失败
TagList Array 必填 指定要拉取的资料字段及好友字段:
  • 标配资料字段
  • 自定义资料字段
  • 标配好友字段
  • 自定义好友字段
  • 应答包体示例

    • 基础形式、完备形式

      {
        "InfoItem": [
            {
                "To_Account": "UserID_2",
                "SnsProfileItem": [
                    {
                        "Tag": "Tag_SNS_IM_Remark",
                        "Value": "remark_2"
                    },
                    {
                        "Tag": "Tag_SNS_IM_Group",
                        "Value": ["group1","group2"]
                    },
                    {
                        "Tag": "Tag_Profile_IM_Nick",
                        "Value": "nick_2"
                    },
                    {
                        "Tag": "Tag_SNS_Custom_Test",
                        "Value": "custom_sns_2"
                    },
                    {
                        "Tag": "Tag_Profile_Custom_Test",
                        "Value": "custom_profile_2"
                    }
                ],
                "ResultCode": 0,
                "ResultInfo": ""
            }
        ],
        "ActionStatus": "OK",
        "ErrorCode": 0,
        "ErrorInfo": "",
        "ErrorDisplay": ""
      }
    • 批量拉取指定好友

    {
        "InfoItem": [
            {
                "To_Account": "UserID_2",
                "SnsProfileItem": [
                    {
                        "Tag": "Tag_SNS_IM_Remark",
                        "Value": "remark_2"
                    },
                    {
                        "Tag": "Tag_SNS_IM_Group",
                        "Value": ["group1","group2"]
                    },
                    {
                        "Tag": "Tag_Profile_IM_Nick",
                        "Value": "nick_2"
                    },
                    {
                        "Tag": "Tag_SNS_Custom_Test",
                        "Value": "custom_sns_2"
                    },
                    {
                        "Tag": "Tag_Profile_Custom_Test",
                        "Value": "custom_profile_2"
                    }
                ],
                "ResultCode": 0,
                "ResultInfo": ""
            },
            {
                "To_Account": "UserID_3",
                "SnsProfileItem": [
                    {
                        "Tag": "Tag_SNS_IM_Remark",
                        "Value": "remark_3"
                    },
                    {
                        "Tag": "Tag_Profile_IM_Nick",
                        "Value": "nick_3"
                    },
                    {
                        "Tag": "Tag_Profile_Custom_Test",
                        "Value": "custom_profile_3"
                    }
                ],
                "ResultCode": 0,
                "ResultInfo": ""
            },
            {
                "To_Account": "UserID_4",
                "ResultCode": 30001,
                "ResultInfo": "Err_SNS_FriendGetList_Friend_Not_Exist"
            }
        ],
        "Fail_Account": [
            "UserID_4"
        ],
        "ActionStatus": "OK",
        "ErrorCode": 0,
        "ErrorInfo": "",
        "ErrorDisplay": ""
    }

    应答包字段说明

    字段 类型 说明
    InfoItem Array 好友对象数组,每一个好友对象都包含一个 To_Account 字段和一个 SnsProfileItem 数组
    To_Account String 好友的 UserID
    SnsProfileItem Array 保存好友数据的数组,数组每一个元素都包含一个 Tag 字段和一个 Value 字段
    Tag String 字段的名称
    Value String/Integer/Array 字段的值
    ResultCode Integer To_Account 的处理结果,0表示成功,非0表示失败
    ResultInfo String To_Account 的错误描述信息,成功时该字段为空
    Fail_Account Array 返回处理失败的 UserID 列表,仅当存在失败用户时才返回该字段
    ActionStatus String 请求处理的结果,OK 表示处理成功,FAIL 表示失败
    ErrorCode Integer 错误码,0表示成功,非0表示失败
    ErrorInfo String 详细错误信息
    ErrorDisplay String 详细的客户端展示信息

    错误码说明

    除非发生网络错误(例如502错误),否则该接口的 HTTP 返回码均为200;真正的错误码、错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。
    公共错误码(60000到79999)参见 错误码 文档。
    本 API 私有错误码如下:

    错误码 描述
    30001 请求参数错误,请根据错误描述检查请求参数
    30003 请求的用户帐号不存在
    30004 请求需要 App 管理员权限
    30006 服务器内部错误,请重试
    30007 网络超时,请稍后重试

    接口调试工具

    通过 REST API 在线调试工具 调试本接口。

    参考