钉钉是企业沟通与协作平台，在本文场景中为ONES提供企业内部应用的身份目录、登录入口和消息通知通道。本文按国内版公有云产品手册说明钉钉企业内部应用的创建顺序、email与org_email的映射选择、账号绑定与通知渠道启用，并给出上线验收项；私有部署需按实际环境条件核对，文中步骤未在目标环境实测。
要点总览（TL;DR）
- 钉钉接入ONES走企业内部应用路线：先在钉钉侧创建应用，填写网页地址与回调域、开通通讯录权限、设置发布可见范围，取得应用凭据后在ONES侧完成账号绑定。
- 账号匹配可按email或org_email进行，一次接入只采用一种口径；org_email对应企业邮箱字段，要求成员已开通企业邮箱，未统一开通时按org_email匹配会出现大量空值。
- 账号接入与Project/Wiki通知渠道启用是两个步骤，绑定成功只说明身份已对应，通知能否到达取决于通知渠道是否在对应项目或知识库中另行启用。
- 资料只证明钉钉侧更新用户接口面向企业内部应用并要求通讯录维护权限，不能据此认为ONES会反向更新钉钉通讯录成员。
- 验收以可观察结果为准：抽样成员登录、匹配名单比对、指定Project/Wiki通知可达、可见范围外成员被拦截，并记录本次邮箱字段口径与核验日期。
钉钉与ONES的对接方向和适用范围
这条连接的对象是钉钉企业内部应用。钉钉侧提供成员身份信息与消息通道，ONES侧完成账号绑定，并把业务通知投递到钉钉。配置入口在ONES的集成设置中，网页地址、回调域等取值需要从当前ONES租户的配置界面获取，不要套用其他租户或旧版文档中的示例地址。
数据方向可以按三个动作来理解：钉钉提供身份（成员及其邮箱字段），管理员在ONES侧发起并完成账号绑定，通知由ONES按项目或知识库的配置发出、经钉钉送达成员。整个过程里，钉钉是身份与通道的提供方，ONES是绑定与投递的执行方。
| 环节 | 提供方 | 动作发生位置 | 结果 |
|---|---|---|---|
| 身份目录 | 钉钉 | 钉钉企业内部应用 | 成员及其email/org_email可供匹配 |
| 账号绑定 | ONES | ONES集成配置 | 钉钉成员与ONES账号建立对应关系 |
| 通知投递 | ONES发起，钉钉送达 | Project/Wiki通知渠道 | 业务消息出现在钉钉中 |
适用范围限定为国内版公有云产品手册描述的流程，私有部署按实际环境条件核对。钉钉个人应用的接入方式不在本文范围内。需要特别说明：本文资料只证明钉钉侧存在更新用户信息的接口及其权限要求，不能据此认为ONES会把成员信息反向写回钉钉通讯录。
企业内部应用创建：网页地址、回调域与通讯录权限
钉钉侧配置按“创建应用—填写地址—开通权限—设置可见范围—取得凭据”的顺序推进，每一步的产出都是下一步的输入。建议由一名管理员统一操作并记录每项取值，避免多人分别填写造成地址不一致。
配置清单
- 创建企业内部应用。在钉钉开发者后台新建应用，应用类型选择企业内部应用，记录应用名称与用途，便于后续在ONES侧对应识别。
- 设置网页地址与回调域。两项取值均来自当前ONES租户的集成配置界面，按界面给出的地址原样填写。回调域需要与网页地址属于同一可信范围，填写后不要随意改动，否则已完成的绑定可能失效。
- 开通通讯录权限。为应用申请读取通讯录相关权限，用于获取成员及其邮箱字段。权限范围按实际需要的最小集合申请，避免过度授权。
- 设置发布可见范围。可见范围决定哪些钉钉成员能看到并使用该应用。范围之外的成员即使邮箱匹配成功，也无法完成绑定，因此范围应覆盖全部需要接入ONES的成员。
- 取得应用凭据。配置完成后获取应用凭据，在ONES侧绑定环节使用。凭据属于敏感信息，按企业内部密钥管理要求保存，不写入共享文档。
这五项完成后，钉钉侧的准备即告一段落。后续的账号匹配、绑定和通知启用都在ONES侧进行。
email与org_email怎么选：映射规则与开通条件
ONES支持按email或org_email匹配账号，两者对应钉钉成员资料中的不同邮箱字段。选择依据是成员实际开通并使用的邮箱类型，一次接入只采用一种口径，不要在同一批成员中混用。
| 对比项 | org_email | |
|---|---|---|
| 字段含义 | 成员的个人邮箱字段 | 企业邮箱字段 |
| 开通前提 | 成员资料中该字段有值 | 成员已开通企业邮箱 |
| 适用情形 | 成员以个人邮箱作为主要联系邮箱 | 企业已为成员统一开通企业邮箱 |
| 选择要点 | 核对两侧取值一致 | 先确认开通状态，再核对取值 |
两个字段在钉钉接口中的含义不同，不能把一方的email直接当作另一方的org_email使用。映射前建议做一次核对：导出待接入成员名单，逐人确认所选字段在钉钉侧有值、在ONES侧对应账号的邮箱值一致，再执行绑定。核对结果留档，作为后续排查的基线。
如果企业尚未统一开通企业邮箱，按org_email匹配会出现大量空值，此时应改用email口径，或先完成企业邮箱开通再切换。切换口径意味着重新核对全部成员，不宜在绑定进行到一半时临时更换。
账号绑定与通知渠道启用：两个独立步骤
账号接入和Project/Wiki通知渠道启用是两个步骤，绑定成功只说明成员身份已对应，通知能否到达取决于通知渠道是否另行启用。常见的情况是成员已经能通过钉钉登录ONES，但项目里的消息没有出现在钉钉中，原因通常就在这一步。
操作顺序
- 确认钉钉应用的发布可见范围已覆盖全部待接入成员。
- 在ONES侧完成账号绑定，按选定的email或org_email口径执行匹配。
- 抽查若干成员，确认可以通过钉钉登录并进入正确的ONES账号。
- 按项目或知识库的需要，分别启用Project/Wiki通知渠道。
- 在已启用渠道的项目中触发一条通知，确认成员能在钉钉中收到。
通知渠道按项目或知识库分别启用，意味着新开项目时需要重复这一步，不能依赖此前项目的配置自动生效。把“新项目启用通知渠道”写进项目初始化清单，可以减少漏配。
异常、重复与方向边界：哪些情况要停下来核对
接入过程中的失败大多集中在邮箱取值和可见范围两处。遇到问题时先定位现象属于哪一类，再按对应核对点处理，避免反复重试绑定。
| 现象 | 核对点 | 处理动作 |
|---|---|---|
| 部分成员匹配失败 | 所选邮箱字段在钉钉侧是否为空，两侧取值是否一致 | 补齐或更正邮箱值后重新匹配，不要改用另一字段绕过 |
| 按org_email匹配大面积失败 | 成员是否已开通企业邮箱 | 先完成企业邮箱开通，或评估改用email口径并重新核对全部成员 |
| 成员能看到应用但无法绑定 | 发布可见范围是否覆盖该成员 | 调整可见范围后重试 |
| 绑定成功但收不到通知 | 对应Project/Wiki的通知渠道是否已启用 | 在目标项目中启用通知渠道并触发测试消息 |
| 同一成员出现多条对应记录 | 两侧是否存在重复账号或重复邮箱 | 以唯一且有效的邮箱为准保留一条，清理重复记录后再绑定 |
关于同步方向，需要明确一条边界：钉钉的更新用户接口面向企业内部应用，并要求通讯录维护权限，这只能说明钉钉侧提供了更新成员的接口能力，不能作为ONES会反向更新钉钉通讯录成员的证据。如果业务上确实需要把ONES侧的成员变更写回钉钉，应作为独立需求评估，不能默认本次接入已经具备该能力。资料未覆盖的能力也不应直接判定为产品永久不支持，以当前官方文档和实际环境核验为准。
上线前的可验证结果
验收以可观察的结果为准，逐项确认通过后再宣布接入完成。建议由管理员和一名业务成员共同执行，避免只在一人账号上验证。
- 登录路径可用：抽样成员从钉钉进入ONES，能够登录到本人账号，页面与权限符合预期。
- 匹配名单一致：按所选邮箱字段匹配成功的成员名单，与事先整理的待接入名单逐条比对，差异项有明确原因。
- 通知可达：在指定的Project和Wiki中分别触发通知，成员在钉钉中收到，内容与来源项目对应。
- 范围外成员被正确拦截：选取一名不在发布可见范围内的成员，确认其无法完成接入。
- 口径留档：记录本次采用的邮箱字段（email或org_email）、应用可见范围、核验日期与核验人，便于后续复查和人员变动时对照。
验收通过后，把邮箱字段口径和通知渠道启用规则写入接入说明，后续新增成员或新开项目时按同一口径执行，可以减少重复排查。
常见问题
钉钉应用已经建好，成员也能看到应用，为什么绑定还是失败？
先核对两处：一是该成员是否在应用的发布可见范围内，范围之外的成员即使邮箱匹配成功也无法完成绑定；二是所选邮箱字段在钉钉侧是否有值、与ONES侧账号的邮箱值是否一致。两处都确认无误后再重试绑定，不要通过改用另一个邮箱字段来绕过问题，否则会造成同一批成员口径混用。
企业还没有统一开通企业邮箱，能不能直接用org_email匹配？
org_email对应企业邮箱字段，需要成员已开通企业邮箱。企业尚未统一开通时，按org_email匹配会出现大量空值，此时可以改用email口径，或先完成企业邮箱开通再切换。切换口径意味着全部成员需要重新核对，建议在绑定开始前确定，避免进行到一半临时更换。
成员已经能通过钉钉登录ONES，项目消息却收不到，问题出在哪？
账号接入和Project/Wiki通知渠道启用是两个步骤。登录可用说明绑定已完成，消息收不到通常是对应项目或知识库的通知渠道尚未启用。到目标项目中启用通知渠道，再触发一条测试消息确认可达。通知渠道按项目或知识库分别启用，新开项目时需要重复这一步。
ONES会把成员变更反向写回钉钉通讯录吗？
本文资料只说明钉钉侧存在更新用户信息的接口，该接口面向企业内部应用并要求通讯录维护权限，这只能证明钉钉提供了更新成员的接口能力，不能作为ONES反向更新钉钉通讯录成员的证据。如果业务上确实需要把ONES侧成员变更写回钉钉，应作为独立需求单独评估。资料未覆盖的能力也不宜直接判定为产品永久不支持，以当前官方文档和实际环境核验为准。
网页地址和回调域填好后还能改吗？
两项取值都应从当前ONES租户的集成配置界面获取并原样填写，回调域需要与网页地址属于同一可信范围。填写后随意改动可能导致已完成的绑定失效，因此建议由一名管理员统一操作并记录每项取值。确需变更时，先评估已绑定成员的影响范围，再安排变更与重新验证。
