钉钉开发文档

应用管理

更新时间: 2018-11-12

创建应用

仅限企业调用该接口,ISV无权限调用。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/microapp/create?access_token=ACCESS_TOKEN
请求包结构体

{
    "appIcon": "@HIdsabikkhjsdsas",
    "appName": "测试应用",
    "appDesc": "测试使用的应用",
    "homepageUrl": "http://oa.dingtalk.com/?h5",
    "pcHomepageUrl": "http://oa.dingtalk.com/?pc",
    "ompLink": "http://oa.dingtalk.com/?omp"
}

参数说明

参数
参数类型
必须
说明
access_token
String
调用接口凭证
appIcon
String
应用的图标,
需要调用 上传媒体文件接口将图标上传到钉钉服务器后获取到的mediaId
appName
String
应用的名称,长度限制为1~10个字符
appDesc
String
应用的描述,长度限制为1~20个字符
homepageUrl
String
应用的移动端主页,必须以http开头或https开头
pcHomepageUrl
String
应用的PC端主页,必须以http开头或https开头,如果不为空则必须与homepageUrl的域名一致
ompLink
String
应用的OA后台管理主页,必须以http开头或https开头。

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/microapp/create");
OapiMicroappCreateRequest req = new OapiMicroappCreateRequest();
req.setAppName("SDK测试应用");
req.setAppIcon("@lADPBY0V4sh3bVvMl8yV");
req.setAppDesc("SDK测试新建应用");
req.setHomepageUrl("http://open-dev.dingtalk.com/#/overview?_k=4dqois222");
req.setPcHomepageUrl("http://open-dev.dingtalk.com/#/overview?_k=4dqois444");
req.setOmpLink("http://open-dev.dingtalk.com/#/overview?_k=4dqois333");
OapiMicroappCreateResponse response = client.execute(req, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "created",
    "agentid": 2
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
agentid 应用实例化 id

更新应用

仅限企业调用该接口,ISV无权限调用,且企业只能更新自建应用。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/microapp/update?access_token=ACCESS_TOKEN
请求包结构体

{
    "appIcon": "@HIdsabikkhjsdsas",
    "appName": "测试应用",
    "appDesc": "测试使用的应用",
    "homepageUrl": "http://oa.dingtalk.com/?h5",
    "pcHomepageUrl": "http://oa.dingtalk.com/?pc",
    "ompLink": "",
    "agentId":111
}

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
appIcon String 应用的图标。需要调用上传媒体文件接口将图标上传到钉钉服务器后获取到的mediaId
appName String 应用的名称。长度限制为1~10个字符
appDesc String 应用的描述。长度限制为1~20个字符
homepageUrl String 应用的移动端主页,必须以http开头或https开头
pcHomepageUrl String 应用的PC端主页,必须以http开头或https开头,如果不为空则必须与homepageUrl的域名一致
ompLink String 应用的OA后台管理主页,必须以http开头或https开头
agentId int 应用实例化id

SDK请求示例(JAVA)

DingTalkClient  client = new DefaultDingTalkClient("https://oapi.dingtalk.com/microapp/update");
OapiMicroappUpdateRequest req = new OapiMicroappUpdateRequest();
req.setAppName("SDK测试应用更新");
req.setAppIcon("@lADPBY0V4sh3bVvMl8yV");
req.setAppDesc("描述_更新");
req.setHomepageUrl("http://open-dev.dingtalk.com/#/overview?_k=4dqois4");
req.setOmpLink("http://open-dev.dingtalk.com/#/overview?_k=4dqois5");
req.setPcHomepageUrl("http://open-dev.dingtalk.com/#/overview?_k=4dqois6");
req.setAgentId(174633150L);
OapiMicroappUpdateResponse response = client.execute(req,accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "agentid": 2
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
agentid 更新的应用实例化id

删除应用

仅限企业调用该接口,ISV无权限调用,且企业只能删除自建应用。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/microapp/delete?access_token=ACCESS_TOKE
请求包结构体

{
    "agentId": 2
}

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
agentId int 应用实例化id,企业只能删除自建应用

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/microapp/delete");
OapiMicroappDeleteRequest req = new OapiMicroappDeleteRequest();
req.setAgentId(174633150L);
OapiMicroappDeleteResponse response = client.execute(req,accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容

列出应用

仅限企业调用该接口,ISV无权限调用。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/microapp/list?access_token=ACCESS_TOKEN

如果希望在企业自定义工作台中添加钉钉原生应用(如审批、日志等)或已上架的第三方应用,只需将文字、图标或按钮的对应的跳转url设置为:
dingtalk://dingtalkclient/action/switchtab?index=2&name=work&scene=1&corpid=<企业corpid>&agentid=<跳转到应用的agentid>

SDK请求示例(JAVA)

DefaultDingTalkClient  client = new DefaultDingTalkClient("https://oapi.dingtalk.com/microapp/list");
OapiMicroappListRequest req = new OapiMicroappListRequest();
OapiMicroappListResponse response = client.execute(req,accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "appList": [
        {
            "appIcon": "http://static.dingtalk.com/media/szIzMg_200_200.png",
            "agentId": 111,
            "appDesc": "应用描述",
            "isSelf": true,
            "name": "应用名称",
            "homepageLink": "http://oa.dingtalk.com/?h5",
            "pcHomepageLink": "http://oa.dingtalk.com/?pc",
            "appStatus": 1,
            "ompLink": "http://oa.dingtalk.com/index"
        }
}
参数
说明
errcode
返回码
errmsg
对返回码的文本描述内容
appIcon
应用图标
agentId
应用实例化id
appDesc
应用描述
isSelf
表示是否是自建应用
name
应用名称
homepageLink
应用的移动端主页
pcHomepageLink
应用的pc端主页
appStatus
应用状态,
1表示启用
0表示停用
ompLink
应用的OA后台管理主页

员工可见应用列表

仅限企业调用该接口,ISV无权限调用。

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/microapp/list_by_userid?access_token=ACCESS_TOKEN

如果希望在企业自定义工作台中添加钉钉原生应用(如审批、日志等)或已上架的第三方应用,只需将文字、图标或按钮的对应的跳转url设置为:
dingtalk://dingtalkclient/action/switchtab?index=2&name=work&scene=1&corpid=<企业corpid>&agentid=<跳转到应用的agentid>

SDK请求示例(JAVA)

DingTalkClient  client = new DefaultDingTalkClient("https://oapi.dingtalk.com/microapp/list_by_userid");
OapiMicroappListByUseridRequest req = new OapiMicroappListByUseridRequest();
req.setUserid("01376814877479");
req.setHttpMethod("GET");
OapiMicroappListByUseridResponse response = client.execute(req,accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "appList": [
        {
            "appIcon": "http://static.dingtalk.com/media/szIzMg_200_200.png",
            "agentId": 111,
            "appDesc": "应用描述",
            "isSelf": true,
            "name": "应用名称",
            "homepageLink": "http://oa.dingtalk.com/?h5",
            "pcHomepageLink": "http://oa.dingtalk.com/?pc",
            "appStatus": 1,
            "ompLink": "http://oa.dingtalk.com/index"
        }
}
参数
说明
errcode
返回码
errmsg
对返回码的文本描述内容
appIcon
应用图标
agentId
应用实例化id
appDesc
应用描述
isSelf
表示是否是自建应用
name
应用名称
homepageLink
应用的移动端主页
pcHomepageLink
应用的pc端主页
appStatus
应用状态,
1表示启用
0表示停用
ompLink
应用的OA后台管理主页

获取应用的可见范围

仅限企业调用该接口,ISV无权限调用。

获取企业管理员设置的应用的可见范围(可见用户列表、可见部门列表)。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/microapp/visible_scopes?access_token=ACCESS_TOKEN
请求包结构体

{
    "agentId": 16691682,
}

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
agentId Long 需要查询的应用实例化agentId

SDK请求示例(JAVA)

DingTalkClient  client = new DefaultDingTalkClient("https://oapi.dingtalk.com/microapp/visible_scopes");
OapiMicroappVisibleScopesRequest req = new OapiMicroappVisibleScopesRequest();
req.setAgentId(173398001L);
OapiMicroappVisibleScopesResponse response = client.execute(req, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "isHidden":false,
    "deptVisibleScopes": [1265,9634],
    "userVisibleScopes": ["manager6577","766578"]
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
isHidden 是否仅限管理员可见
deptVisibleScopes 应用的可见部门id列表,格式为JSON数组
userVisibleScopes 应用的可见用户id列表,格式为JSON数组

设置应用的可见范围

仅限企业调用该接口,ISV无权调用。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/microapp/set_visible_scopes?access_token=ACCESS_TOKEN
请求包结构体

{
    "agentId": 16691682,
    "isHidden":false,
    "deptVisibleScopes":[1,2],
    "userVisibleScopes":["userId1","userId2"]
}

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
agentId Long 应用实例化id
isHidden Boolean 是否仅限管理员可见,true代表仅限管理员可见
deptVisibleScopes JSON数组 设置可见的部门id列表,格式为JSON数组
userVisibleScopes JSON数组 设置可见的员工id列表,格式为JSON数组

SDK请求示例(JAVA)

DingTalkClient  client = new DefaultDingTalkClient("https://oapi.dingtalk.com/microapp/set_visible_scopes");
OapiMicroappSetVisibleScopesRequest req = new OapiMicroappSetVisibleScopesRequest();
req.setAgentId(173398001L);
req.setDeptVisibleScopes(Arrays.asList(0L));
req.setUserVisibleScopes(Arrays.asList("01376814877479"));
OapiMicroappSetVisibleScopesResponse response = client.execute(req, accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容