contactAdd 添加联系人

函数功能:

向通讯录添加一个联系人。

对应JS API:
contactAdd(obj)
是否支持多设备:

不支持

适用版本:

Total Control 6.9.0 及以后版本

请求方式:POST
http://IP:8090/TotalControl/v1/devices/:device/contacts?token=:token&type=add&contact_data=:contact_data
参数说明:
参数名 类型 必选 描述
IP string Y 访问 Total Control 服务器的 IP 地址
token string Y Total Control TOKEN
type string Y 固定值: add
contact_data 对象 Y 添加联系人的信息,contact_data 是 json 对象,格式就是json格式,例如:
contact_data 包含很多字段,不是所有的字段都需要填写,你只需要添加你需要的字段即可,当然,也可以将所有字段都添加。contact_data 格式如下:
{
	"displayName": "杰华科技",
	"phone": [{
		"phoneNumber": "028 8533 2200",
		"phoneType": "3"
	}, {
		"phoneNumber": "8533 2200",
		"phoneType": "2"
	}],
	"email": [{
		"emailValue": "sales@sigma-rt.com",
		"emailType": "1"
	}, {
		"emailValue": "support@sigma-rt.com",
		"emailType": "2"
	}],
	"organization": [{
		"company": "成都杰华科技",
		"title": "工程师"
	}],
	"iconBytes": "\/9j\/4AAQSkZJRgABAQAAAQABAAD\/2wBDAAMCAgMCAgMDAwMEAwMEBQgFBQQEBQoHBwYIDAoMDAsK\nCwsNDhIQDQ4RDgsLEBYQERMUFRUVDA8XGBYUGBIUFRT\/2wBDAQMEBAUEBQkFBQkUDQsNFBQUFBQU\nFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBT\/wAARCABgAGADASIA\nAhEBAxEB\/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL\/8QAtRAAAgEDAwIEAwUFBAQA\nAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3\nODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWm\np6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6\/8QAHwEA\nAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL\/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSEx\nBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElK\nU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3\nuLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6\/9oADAMBAAIRAxEAPwD57Ddq\nkU8cHNVlfkjrUiP1wa\/aEz+Z3EsBjUsbY5qqjZOKnV8ZrWLMmi1HJjgmpFk96pq\/BpwkPOKtGDgX\n45O1WEkxWdFJxzU6ycYq0znlAt+dk0CXrVUS1DealDp9nPdXD7IIEaWRj2UDJP6UOSSu2Sqbk+VL\nU8h+Oy2v\/CRWLxfLetbYlx0K7iE\/H734YrF8O+DZrjQ5tVfS7vVrq8f7Lp8CBvLQ9HuHIwAAflG4\n4zk4PUJoWn3XxU8b3d7J5iWjPueT\/nlGOFXPTdgYHvk9jX0Baww2FtFbW6CKCFBGkY6KoGAP0r43\nDYNZjXq4mStBvTz6X\/rr6H6Hi8fLJ8NRwUXzVElza7dbXWvl6adTk0lPOMVIkpA5rGstWiuZJITm\nK4Thon6\/Ueo96vq+R1zXvQqKSumeFOk4u0kXo58Z9KnSbI\/xrGvdTTTbVp3G4AgbQcE5Pb8Mn8Ku\nrOrqGUhlIyCDnNaqabsc8qTtzW0L3mcGpEkGc5rPSYHvUiS9a0TMXTNFZMVHd6lDYwNNPKI414JP\n8vf6VSmRLmLY7SBc5\/dyMh\/NSDWVbeHIpmle\/kmuSXLRRSTORCvYA5znGM8\/\/XznUqJ8sEVTpUnr\nUb08iKfx5LIT9ktcAnAMxwT+A6Vd1nSZvGmgrZXc0umxPKrTLDy0kY\/h5+7k4PQ9KtWun2loytDb\nxxuowH25YevJ5q2svBrKFKclJV5XT6dDeVWnTlGWHjyta33f+Q\/w\/o9j4d06OxsIFggTnA5LHuxP\nUnj+VaYl64NZqz1IJutd0FGEVGKskebUUqknObu2ec61pcl7qFs0G6ORfvzA4Cjt+PWi40vUg8ss\nV4xYgADIUsBnjpj\/APXW+B1oHGa8V4aLbfc+nWJmko6aHIXWnaxIoMqtMF5wzBsfgDVnT9dv9PCJ\ncxN5I4AMZGMdhmunxzSY49ay+quL5oSaNHi1OPLOCa+4LHUY7+ESRk+4IwRVtJDjg1UBwMinBiRX\noQbSszzpRTemxcWUjNPE3HPFUhJweaUSYGM1qpmXIXRLkdc0qy9eapCWnLJ19aakTyF1ZiM04Tcd\nao+Z7mlWU+tUpIn2ZVA4IpcZzSDp9KXsfSuc6xBSg9qTvSjkfWgBCMUoHBo9qB3oAQDg54oNA70o\n65oAbg807kUnbpSg470AJuI78UoJ5pPU96WgAA680A4z9aQcClHGf60AAoAoFAGBQIPWjsfajHWg\nAYNAwxjNA6cUL3yKBz+FACevrQDjPvQBz1zS4oAPakHI\/GlHtQO9ACZ7UoxzQO9GMk0AAoHTH4UU\nDp\/WgAHejPSjGDR2NACdzSgGjOc0DuBQAnY0o5pAOuO9KBx60AHt\/KgcCigDHpQB\/9k=\n"
}

想给联系人添加哪些字段,就填哪些字段即可,不需要将所有字段都填。其中,各个字段表示的意思为:

  • displayName: 字符串, 联系人姓名
  • phone: 数组,数组里面是 json 对象,包含字段 phoneNumber 和 phoneType
    phoneNumber: 整型,联系人电话号码
    phoneType: 整型,电话号码类型,其中,
    1 表示住宅电话
    2 表示手机号码
    3 表示单位电话
    4 表示单位传真
    5 表示住宅传真
  • email: 数组,数组里面是 json 对象,包含字段 emailValue 和 emailType
    emailValue:字符串, 电子邮箱
    emailType: 整型,邮箱类型,其中
    1 表示私人邮箱
    2 表示单位邮箱
  • organization,数组,数组里面是 json 对象,包含字段 company 和 title
    company: 单位名称
    title: 职位
  • iconBytes: 字符串,联系人头像,这里用的 base64 表示。
响应参数:

Total Control 提供的 REST API 响应格式都是 JSON ,返回值通常由关键字 "status" 和 "value" 组成,
status: 接口执行成功与否
value: 执行接口的返回信息

(一)执行接口成功的返回字段说明

字段 类型 描述
status boolean 执行接口成功,则返回:true
value int 联系人的 contact_id


返回示例:

{
	"status": true,
	"value": 753
}

(二)执行接口返回 HTTP 状态码为 200,但是结果有误的返回字段说明

字段 类型 描述
status object 执行接口失败,则返回:null 对象
value string 返回失败的具体信息


返回示例:

{
    "status":null,
    "value":"......"
}
请求示例:
http://localhost:8090/TotalControl/v1/devices/device@1174886816/contacts
{
	"token": "pxExMsRv92aHuaJO",
	"type": "add",
	"contact_data": "{'displayName':'杰华科技','phone': [{'phoneNumber': '028 8533 2200','phoneType': 3}, {'phoneNumber': '8533 2222','phoneType': 1}]}"
}
示例:添加联系人,联系人姓名为'杰华科技',单位电话为'028 8533 2200',住宅电话为'8533 2222'

注意:下列示例是通过本机访问 Total Control 服务器,所以 IP 都是用的 "localhost"。

RingoJS 请求示例:

可以复制下面的代码,在 Total Control 的脚本终端中执行,也可以保存为后缀为 js 的文件, 例如:example.js,在Total Control 执行器中执行。

//导入一些 ringoJS 的包
var {request} = require('ringo/httpclient');
var base64 = require('ringo/base64');
//将用户名密码编码,'sigma:3D391497'是用户名和密码,在Total Control系统设置里面可以看到
var userpass = base64.encode('sigma:3D391497');

//第一步:获取 Total Control 脚本开发所用的开发 token
var gettoken = request({
    method: 'GET',
    url: 'http://localhost:8090/TotalControl/v1/login',
    headers: {'Authorization': userpass}
	});
//将获取的响应内容转换成json对象
var ret_token = eval('(' + gettoken.content + ')'); 
var token = ret_token.value.token; 
print("//获取 token 的值为:" + token);

//第二步:获取当前主控设备 ID 值
var getdevice = request({
    method: 'GET',
    url: 'http://localhost:8090/TotalControl/v1/devices/main?token=' + token
	});
var device = eval('(' + getdevice.content + ')').id; 
print("//获取到设备的 ID:"+ device);

//第三步:添加联系人
var ret = request({
    method: 'POST',
    url: 'http://localhost:8090/TotalControl/v1/devices/'+ device + '/contacts',
    data: {
	"token": token,
	"type": "add",
	"contact_data": "{'displayName':'杰华科技','phone': [{'phoneNumber': '028 8533 2200','phoneType': 3}, {'phoneNumber': '8533 2222','phoneType': 1}]}"
    }
	});
print(ret.content);
温馨提示:
获取 Total Control 脚本开发所用的开发 token 请看这里
获取主控设备 id 值 请看这里

RingoJS 示例运行结果:

成功,则返回:

//获取 token 的值为:m195zZEgY91PMcbo
//获取到设备的 ID:device@230441652
{
	"status": true,
	"value": 753
}
易语言请求示例:

温馨提示,关于易语言的更多信息,请看:
如何安装易语言
学写第一个易语言程序
如何使用易语言控制一台设备
如何使用易语言控制多台设备


.版本 2

.程序集 窗口程序集_启动窗口

.子程序 __启动窗口_创建完毕
.局部变量 base64, 文本型
.局部变量 token, 文本型
.局部变量 device, 文本型
.局部变量 j_token, 类_json, , , 用来解析获取 token 的 json
.局部变量 j_dev, 类_json, , , 用来解析获取设备ID 值的 json
.局部变量 j_ret, 类_json, , , 用来解析 REST API 接口的json
.局部变量 bool, 逻辑型
.局部变量 bool_dev, 逻辑型
.局部变量 bool_ret, 逻辑型
.局部变量 status, 文本型


base64 = 到文本 (编码_BASE64编码 (到字节集 (“sigma:3D391497”)))
输出调试文本 (“将用户名和密码组装成 sigma:3D391497 进行 base64 编码生成的字符串为: ” + base64)
bool = j_token.解析 (到文本 (网页_访问_对象 (“http://localhost:8090/TotalControl/v1/login”, 0, , , , “Authorization:” + base64, , , , , , , , , )))
.如果 (bool)
    输出调试文本 (“第一步,获取 token,返回值为:” + j_token.取数据文本 ())
    token = j_token.取通用属性 (“['value'].token”)
    输出调试文本 (“获取的 token 值为: ” + token)
    bool_dev = j_dev.解析 (编码_utf8到gb2312 (到文本 (网页_访问_对象 (“http://localhost:8090/TotalControl/v1/devices/main?token=” + token, 0))))
    .如果 (bool_dev)
        输出调试文本 (“第二步,获取设备 ID 值,返回值为:” + j_dev.取数据文本 ())
        device = j_dev.取通用属性 (“['id']”)
        输出调试文本 (“获取的设备 ID 值为: ” + device)
        bool_ret = j_ret.解析 (编码_utf8到gb2312 (到文本 (网页_访问_对象 (“http://localhost:8090/TotalControl/v1/devices/” + device + “/contacts?type=add&contact_data={'displayName':'杰华科技','phone': [{'phoneNumber': '028 8533 2200','phoneType': 3}, {'phoneNumber': '8533 2222','phoneType': 1}]}&token=” + token, 1))))
        .如果 (bool_ret)
            输出调试文本 (“第三步,添加联系人,返回值为: ” + j_ret.取数据文本 ())
            status = j_ret.取属性对象 (“status”)
            .如果 (status = “true”)
                输出调试文本 (“恭喜你,成功了!”)
            .否则
                输出调试文本 (“不好意思,失败了!”)
            .如果结束

        .否则
            输出调试文本 (“该 API 执行失败”)
        .如果结束

    .否则
        输出调试文本 (“获取设备 ID 值失败”)
    .如果结束


.否则
    输出调试文本 (“获取 token 失败”)
.如果结束

易语言代码运行结果:

成功,则返回:

* 将用户名和密码组装成 sigma:3D391497 进行 base64 编码生成的字符串为: c2lnbWE6M0QzOTE0OTc=
* 第一步,获取 token,返回值为:{"status":true,"value":{"token":"U56adwI779838M6F"}}
* 获取的 token 值为: U56adwI779838M6F
* 第二步,获取设备 ID 值,返回值为:{"id":"device@33254183"}
* 获取的设备 ID 值为: device@33254183
* 第三步,添加联系人,返回值为: {"status":true,"value":2579}
* 恭喜你,成功了!


注意事项:
如果返回值为 {"status": false},可能是 TC 没有操作手机联系人的权限。
提供下面两种解决方法:
(一)如果您在执行该 API 的时候,手机屏幕弹出下图中的对话框时,点击图中的 "允许" 按钮。


(二)打开手机的设置应用,进入手机的设置应用界面,找到“权限管理”或者 “应用管理“ 里面的 TC 应用程序,跟联系人,通讯录相关的权限,请都设置成 "允许"。