Nailing open platform - applet development practice (nailing applet server side)

Nailing applet server side

Refer to the official website ： https://ding-doc.dingtalk.com/doc#/serverapi2/gh60vz

One 、 Nailing service api The interface specification

Nailing has opened a wealth of server interface capabilities , Developers can use these interface capabilities , Realize the integration of enterprise system and nail .

When calling the pin interface , Need to use HTTPS agreement 、JSON data format 、UTF8 code , The domain name is https://oapi.dingtalk.com.POST Please go to HTTP Header Set in Content-Type:application/json.

Return results / Parameter description , Indicate return parameter examples and descriptions . The returned results of all interfaces contain errcode、errmsg. Developers need to follow errcode Is it 0 Determine whether the call is successful （errcode See the global error code for the meaning ）. and errmsg For reference only , There may be changes in the future , Therefore, it can not be used as a criterion for whether the call is successful .

summary ： The unified request is json, In return code errcode by 0 Bit normal call .

Two 、 Third party personal applications 、 Third party enterprise applications 、 Enterprise internal application difference

1. Third party personal applications

    Frequency limit 
    When a user uses a third-party personal application , Submitted the form , When a message needs to be sent to the user after the form is submitted , There are the following restrictions ：
   
   （1） Every third-party personal application , You can tell users in 7 Push a limited number of messages within days ;
   （2） Submit 1 This form can be sent 1 strip , Submit multiple times and send multiple ;
   

   Above , According to the official description , Can summarize and understand , Personal applications There is a big limitation in sending messages . According to the official description ： Submit 1 This form can be sent 1 strip , Submit multiple times and send multiple ;

   Applet personal application , Applet client through e.detail.formId Get the temporary authorization code of push message , The server must obtain the authorization code , To send messages , And it's a one-off . And this temporary authorization code should have a time limit .

   summary ： So personal application is not suitable for that kind of , The scenario that requires the server to take full control of sending messages . Third party personal applets need to submit forms to send messages , Enterprise internal application , You can use the server interface to actively send messages .

   Enter the corresponding documents according to the official website , Find out Personal applet documents are connected to the server API There is no menu , Visual measurement The open interface of personal applet is very limited .

   After testing , You adjust the internal interface of the enterprise https://oapi.dingtalk.com/gettoken Will be submitted to the FALSE appKey and appSecrect. That is, your personal application appKey and appSecrect It can't be adjusted Enterprise internal application interface .

2. Third party enterprise applications
   Third party enterprise application development , It means that developers use nails 、 Third party identity outside the enterprise , Development and application based on the open capability of nails , It can also be used by other tissues on nails .
   

3. Enterprise internal application
   Official reference https://ding-doc.dingtalk.com/doc#/bgb96b/ok9au2

   Enterprise internal application To send a message, you need to call https://oapi.dingtalk.com/gettoken Interface acquisition access_token.
   All send message interfaces need access_token.

summary ： The three application scenarios are different .

 Next , We mainly use  ** Enterprise internal application **  Mainly for analysis and learning .

Situations where nail clouds must be used

Refer to the official website https://ding-doc.dingtalk.com/doc#/ln6dmh/wbhq0x/ker7fv

• Third party enterprise applications （ On the shelf to the nail application market ）

Third party enterprise applications , If you need to put it on the nail application market , You must use a nail cloud . At the same time, you also need to purchase the nail cloud solution and deploy the application on the nail cloud . The reasons mainly include the following ： First, enterprise data should be used in a controllable environment , Can not cause serious accidents of enterprise information leakage ; In addition, it is very important to ensure the stability and availability of applications , Nail cloud will be in the framework 、 There are corresponding requirements for monitoring and alarm .

• Personal applet

If a personal applet needs to be put on the shelves in the nailing application market , You also need to use the nail cloud , Deploy through pinning cloud solutions . This is because nailing personal applets are more work-related scenes , The requirements for safety and stability will be higher .

summary ： Personal applet 、 Third party enterprise applications You have to upload the two to the application market , You have to use nail cloud .

3、 ... and 、 Enterprise internal application service API

1. Address book management

Get Department list

Root hilum ID by 1

Interface
https://oapi.dingtalk.com/department/list
Parameters

among fetch_child Parameters are important , The default is false, Whether to recurse all sub departments of the Department ,ISV Micro application fixed delivery false.

For example, set to true, Return as follows ：

{
	"errcode":0,
	"errmsg":"ok",
	"department":[
		{
			"createDeptGroup":true,
			"name":" Ministry of Finance ",
			"id":285358123,
			"autoAddUser":true,
			"parentid":1
		},
		{
			"createDeptGroup":false,
			"name":" Finance Department ",
			"id":286635451,
			"autoAddUser":false,
			"parentid":1
		}
	]
}

Open platform application background , as follows Need to open Address book read-only permission .

It returns the Department list information containing , department id Information .

User management

The relevant interfaces are as follows ：

• Create user
• Update user
• Delete user
• Get user details
• Get department users userid list
• Get department users
• Get department user details
• Get the list of Administrators
• Get the administrator address book permission range
• according to unionid obtain userid
• Get according to mobile phone number userid
• Get the number of employees in the enterprise
• List of employees who are not logged in to nailing

According to the Department id Get employees ID list

Interface ：
https://oapi.dingtalk.com/user/getDeptMember

return

{
	"errcode":0,
	"userIds":[
		"manager36299"
	],
	"errmsg":"ok"
}

summary ： This interface directly obtains the information under a department userid list .

Get department users

Interface ：
https://oapi.dingtalk.com/user/simplelist

The return message is as follows ：

{
	"errcode":0,
	"userlist":[
		{
			"name":" outer wall or surrounding area of a city xx",
			"userid":"022222223211111111"
		}
	],
	"hasMore":false,
	"errmsg":"ok"
}

summary ： Just like interface naming simple list , The personnel information under the Department returned by this interface is relatively simple , Only name and userid.

Get department user details

Interface ：
https://oapi.dingtalk.com/user/listbypage

The return message is as follows ：

{
    "errcode": 0,
    "errmsg": "ok",
    "hasMore": false,
    "userlist":[
        {
            "userid": "zhangsan",
            "unionid": "PiiiPyQqBNBii0HnCJ3zljcuAiEiE",
            "mobile": "1xxxxxxxxxx",
            "tel" : "xxxx-xxxxxxxx",
            "workPlace" :"",
            "remark" : "",
            "order" : 1,
            "isAdmin": true,
            "isBoss": false,
            "isHide": true,
            "isLeader": true,
            "name": " Zhang San ",
            "active": true,
            "department": [1, 2],
            "position": " The engineer ",
            "email": "[email protected]",
            "avatar":  "xxx",
            "jobnumber": "xxx",
            "extattr": {
                " hobby ":" tourism ",
                " Age ":"24"
                }
        }
    ]
}

summary ： This interface is the same as the previous interface , Obtain the personnel under the Department , However, it is more detailed than the personnel information obtained from the previous interface .

2. Notice of news

Nail message notice

• Work notice message ： It is a notification message pushed to employees in the name of a micro application in the enterprise work notification session , For example, birthday wishes 、 Induction reminder, etc .
• Group news ： It means that you can call the interface to push group chat messages to the group in the name of the system .
• General news ： It refers to the employee's personal use of the application , You can push messages to groups or other people's conversations through interface operation , For example, the scenario of sending logs .
• Task class notification ： It refers to the need to send a task reminder to employees , Such as approval tasks , In this case, you can refer to the to-do task case .

Work notice message

Refer to the official website ： https://ding-doc.dingtalk.com/doc#/serverapi2/pgoxpy/DgMTZ

Related interfaces ;

• Send job notification messages
• Query the sending progress of work notification message
• Query the sending result of the job notification message
• Job notification message recall

The work notification message is a notification message pushed to employees in the name of a micro application in the enterprise work notification session , For example, birthday wishes 、 Induction reminder, etc . The following figure is an example of a session and message for a job notification ：

To send a job notification message, you need to pay attention to the following ：

• The same user can only receive the same message content of the same micro application once a day .
• The same micro application sends messages to the same user , The internal development mode of the enterprise shall not exceed 500 Time
• By setting to_all_user Parameter all staff push message , The most in a day 3 Time .
• This interface sends messages asynchronously , The successful return of the interface does not necessarily mean that the user will receive a message , Need to pass through “ Query the sending result of the job notification message ” Whether the interface query is sent to the user successfully .
• Message types and examples can refer to message types

summary ： Work notice message Is to send messages in the name of the application , It can also send various message types , It depends on your communication .

Interface ：
https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2
The ginseng

{
	"agent_id":" Your micro app id",
	"msg":{
		"msgtype":"text",
		"text":{
			"content":"2020 An extraordinary year "
		}
	},
	"to_all_user":"true"
}

Group news

Group message related interfaces ：

• Send group messages
• Query the list of people who have read group messages
• Create a session
• Modify session
• Get session

Group conversation messages It means that you can call the interface to create an enterprise group chat session , Then you can In the name of the system Push group chat messages to the group .

Create a session （ Create group ）

Send group messages , Group sessions are required id.
Group session id, It can be obtained in the return result of calling the create group session interface , It can also be done through dd.chooseChat obtain

Request mode ：POST（HTTPS）

Request address ：https://oapi.dingtalk.com/chat/create?access_token=ACCESS_TOKEN

Request package structure ：

{
    "name": "groupName",
    "owner": "zhangsan",
    "useridlist": ["zhangsan","lisi"]
}

The parameters are as follows ：

summary ： By default , We generally only need to set the following 3 Parameters , Group name 、 Of the group leader userid、 Group members userid list
{
“name”: “groupName”,
“owner”: “zhangsan”,
“useridlist”: [“zhangsan”,“lisi”]
}

Be careful ： This interface also requires an open platform background , Special interface permission , otherwise , Return as follows ：

{
	"errcode":60011,
	"errmsg":" No permission to call this interface "
}

Be careful ： The permission to open is
High level authority - Application related permissions required for micro application development , Reasonably open according to the application function .
Under the Enterprise conversation jurisdiction .

The developer finds the application in the background , Enter application details , There are interface permissions , There is an enterprise session permission at the bottom to check whether it has been opened .

in addition , Current group session id（chatid） Only the front end is available api.

Create session creation failed , Common mistakes include ： illegal UserID list , Note that in the request parameters useridlist The value of must be an array .

{
    
	"name":"gggg",
	"owner":"aaa9876",
	"useridlist":"['aaa9876','081234232936594740']"
}

Send group messages

Request address ：https://oapi.dingtalk.com/chat/send?access_token=ACCESS_TOKEN

Group session id, It can be obtained in the return result of calling the create group session interface , It can also be done through dd.chooseChat obtain

Sample request parameters ：

{
    
	"chatid":"chat6aca4f0991afc7f3f635ee902ads31d2f",
	"msg":{
    
		"msgtype":"text",
		"text":{
    
			"content":"  Successful test passed "
		}
	}
}

Respond correctly to the results ：

{
    
	"errcode":0,
	"errmsg":"ok",
	"messageId":"msg6XMrDnA/DSAsdfaafsdfQ=="
}