创建三方连接器
一、功能简介
第三方企业应用可以将应用的数据通过连接器的方式进行开放，第三方连接器发布成功后可以让其他组织使用。
接入流程
第三方连接器创建流程如下：
﻿﻿
说明 
如果需要接收到企业开通的通知，可以通过企业开通连接器订阅事件（main_data_subscribe），详情请参考>>>企业授权开通应用事件。
准备工作
使用连接平台之前，你需要有已有上架到应用市场的应用，详情请参考>>>应用上架全流程指引。
二、操作流程
连接器视频版
步骤一：创建连接器
登录开发者后台。
选择开放能力，然后选择连接平台。
选择我的连接，然后依次单击连接器 > 创建连接器。
﻿﻿
选择要关联的第三方企业应用，并输入连接器的基本信息，然后单击确定创建完成。
注意 
一个应用只能关联一个连接器。
﻿﻿
步骤二：配置连接器
一个连接器至少包含一个触发事件或一个执行动作，并定义使用的模型数据。
1. 配置触发事件
选择创建的连接器进入详情页面，单击触发事件，进入触发事件页面。
﻿﻿
单击创建触发事件，然后根据以下信息配置触发事件的基本信息。
填写触发事件的名称和描述，例如：采购单。
选择是否加入主数据联盟。
﻿﻿
选择加入主数据联盟。
选择需要的主数据模型，例如：钉钉官方采购单模型。
﻿﻿
使用直接拖拽的方式连接接口出参和主数据模型。
单击保存。
﻿﻿
选择不加入主数据联盟。
根据下图信息配置触发事件数据模型，最后单击保存。
﻿﻿
在触发事件列表，选择创建好的触发事件，依次单击更多 > 调试按钮进行调试。
﻿﻿
调用发送连接器事件将本地业务系统产生的事件发送到钉钉连接器服务中，钉钉会将这些事件再广播转发给订阅了此事件的其它业务系统。
2. 配置执行动作
单击已创建的连接器进入详情页面，然后单击执行动作，进入执行动作配置页面。
单击创建执行动作，然后根据以下信息进行配置。
输⼊执⾏动作的名称和描述。
输⼊API类型请求地址。
输⼊APISecret和动作类型。
说明 
APISecret可以由开发者自己定义，用来校验调用方是否为钉钉，用以保护用户接口的数据安全，避免接口被非钉钉方调用导致数据泄漏。
配置API⼊参数据模型。
启⽤⼊参映射（可选。在不改变API⼊参的情况下，重新定义该执⾏动作对外的⼊参模型）。
⾃定义（可以配置⾃定义出参数）。
主数据模型（基于钉钉标准的主数据模型进⾏配置）。
﻿﻿
配置API出参数据模型。
配置调⽤成功规范，对API出参进⾏校验，符合规范为成功调⽤。
HTTP状态码， 默认IN 200,202。
可选择API出参数据模型参数进⾏校验。
﻿﻿
启⽤出参映射（可选。在不改变API出参的情况下，重新定义该执⾏动作对外的出参
模型）。
⾃定义（可以配置⾃定义出参数）。
主数据模型（基于钉钉标准的主数据模型进⾏配置）。
在执行动作列表，选择创建好的执行动作，单击调试按钮进行调试。
步骤三：配置灰度企业
有灰度企业
如果你已经有自己的灰度测试组织，可以直接按照以下步骤添加灰度测试组织。
单击进入已创建的连接器页面，然后单击灰度企业。
单击右上角添加，然后在弹出的添加灰度组织页面，添加需要灰度的组织的corpId。
﻿﻿
步骤四：提交测试
测试目标
为保障上架连接器的质量，上架前要求必须通过平台基础准入测试以及做好完备自测。
测试用例包括：
类型
测试用例
触发事件
必填字段检测（包括自定义的或关联主数据定义的）
参数类型检测：调用时的传参与触发事件定义入参的字段类型完全匹配，不出现类似于定义入参类型为Number，传递过来值为非数字String类型的错误情况
应用内操作触发事件后，消息可触达连接平台（针对连接器关联应用的场景）
执行动作
“调用成功规范”状态码配置正确
接口能正常接收请求,并在正确处理请求后返回满足“调用成功规范”中所定义状态码的预期结果
并发10QPS的情况下，接口稳定
接口满足幂等性，正确入参重复请求不影响返回结果
接口RT < 2S
测试步骤
单击配置好的连接器，选择基本信息，在市场上架栏单击测试按钮。
﻿﻿
在列表页中，选择想要上架的触发事件和执行动作，选中后单击提交测试。
﻿﻿
选择的触发事件提交测试后,触发事件会变为待调用状态。
﻿﻿
此时如果连接器关联了应用，连接平台会在测试企业下安装该应用，并且给该应用发送测试企业开通该应用数据互通的消息通知。
用户申请加入钉钉官方测试组织，加入后登陆该测试组织，找到自己的应用，用户在自己应用内执行相应动作触发相应的触发事件。
如果消息能正常触达连接平台，连接平台接收到数据后会校验请求入参是否符合触发事件定义的入参结构，包括必填字段是否存在，字段类型是否准确等。
符合入参结构则测试通过，不符合则测试失败。
此时如果连接器未关联应用，则需通过API方式发起，详情请参考发送连接器事件。
选择的执行动作提交测试后，执行动作可能会有两个状态。
测试中：表示连接平台有自动化测试用例，会自动化完成测试，测试完成后会调整状态为测试通过或者测试失败，无需用户关心。
待调用：表示需要用户手动发起测试。
说明 
无论是否自动化测试，发起测试的时候都会以相同入参同时调用多次执行动作，因此用户需要保证接口的稳定性和幂等性，如果RT超过2S，或者接口因为幂等原因失败，连接平台则认为该执行动作不符合上架要求。
如果待调用的执行动作关联了主数据，调用时需填入系统参数和请求体，填写完成后，单击发送发起调试。
包含主数据系统参数的请求示例：
13
{
    "ddDataCreateAppType" : "premium_microapp",               // 新增应用类型
    "ddDataGmtCreate" : 1637633838685,              // 应用创建时间的时间戳
    "ddDataModifiedAppId" : "premium_microapp@1013",            // 创建的应用的id
    "ddDataAction" : "add",            // 触发类型， add 新增 update 更新 delete 删除
    "ddDataModifiedAppType" : "premium_microapp",            // 最后修改应用类型
    "ddDataGmtModified" : 1637633838704,               // 应用修改时间的时间戳
    "operateUserId" : "manager153",                // 操作人id
    "ddDataCorpId" : "ding1532454c0c169be84ac5d6980864d335",
    "ddDataCreateAppId" : "premium_microapp@1013",               // 最后修改的应用的id
    "ddDataModelId" : "EM-10149F1C2FAC0B1738B3000Z"                 // 主数据模型id
}
﻿﻿
包含主数据请求体的示例：
18
{
    "data":{
        "amount":"10.0",
        "code":"SO.23291313001",
        "customerCode":"XBB_CU.73532834",
        "billDate":1637683200000,
        "customerName":"雷霆羽",
        "coworkingEmpCodes":[],
        "empCode":"manager153",
        "empName":"霆羽",
        "name":"232232号新建合同",
        "signPersonName":"霆羽",
        "productList":[],
        "signPersonId":"manager153",
        "status":"签约"
    }
}
﻿﻿
如果待调用的执行动作未关联主数据，则按定义的入参结构填入需要的参数后发起测试，填写完成后单击发送发起调试。
﻿﻿
全部测试完成后，在测试列表页可以看到所有测试的结果。
﻿﻿
连接器上架的时候只有测试状态为测试成功的触发事件和执行动作才允许上架。
步骤五：上架连接器
请确保选择和定义正确的数据模型，所有执行动作通过测试以后，连接器应用达到待发布状态。
进入已完成配置的连接器基本信息页面，单击市场上架栏右侧上架。
﻿﻿
在上架连接器页面，填写上架说明。
说明 
上架说明需尽量详细描述业务场景。
例如：接收其他应用或系统的商机到博知CRM中进行客户的跟踪及管理，并可同步签署的订单数据到其他应用或系统中创建项目。
﻿﻿
提交连接器发布申请后，钉钉小二会在收到发布申请后的3个工作日内审核完成。你可以在开发者后台 > 连接器 > 连接器详情页面 >中查看审核状态。
连接器审核标准如下：
连接器名称、图标以及执行动作和触发动作的名称描述清晰易懂。
连接器触发事件、数据模型、执行动作确保可以和其他应用互通，功能没有缺陷。
连接器发布之后用户即可在开发者后台 > 连接平台页面或其他页面开通，确保连接器的描述清晰用户可以看得懂，明确的知道连接器发送的数据和接受的数据。
﻿
更新于：2022/12/12
﻿
﻿
﻿
﻿