### 案例：客户信息对接 - 小满OKKICRM到简道云
在企业管理系统中，实现不同平台间的数据集成是提效升级的关键一步。本案例聚焦于如何通过轻易云数据集成平台，将小满OKKICRM中的客户信息高效、准确地同步至简道云，从而帮助企业实现在不同系统间无缝衔接其数据资产。
#### 确保数据不漏单与可靠抓取
为了确保每一条客户记录都能无遗漏地从小满OKKICRM转移至简道云，我们需要定时可靠地调用小满OKKICRM的接口`/v1/company/updates`。通过配置定时任务机制，可以按需设定抓取频率，并且在每次请求后确认返回结果，保证所有更新的数据都被成功处理并传递到目标系统。
#### 接口分页与限流问题的解决
处理大量数据批量迁移时，小满OKKICRM API接口可能会遇到分页和限流的问题。为此，本方案采用了自动分页技术，在首次获取API响应的总条数后，循环发送分页请求直至全部记录获取完毕，同时利用速率限制策略避免触发API访问限制。在实现过程中，还设计了重试机制，避免由于临时性网络或服务故障导致任务失败。
#### 数据格式差异及映射转换
由于小满OKKICRM与简道云使用的是两种不同格式的数据结构，在进行数据对接前必须做好字段及类型的映射转换。例如，小满OKKICRM输出字段名称如“company_name”需要映射为简道云所需的“enterprise_title”。这是通过轻易云提供的自定义脚本功能来实现，将复杂多变的数据结构灵活转换，以确保写入操作能够顺利进行。
### 快速写入与异常处理
大量客户信息从源端快速稳定同步至目的端，是整个集成流程中的核心环节之一。借助轻易云强大的批量写入能力，每次将大批量已整理好的数据发送到简道云对应应用下的一张表格，通过调用其接口 `/api/v2/app/{app_id}/entry/{entry_id}/data_create` 来完成数据库插入操作。同时，为应对可能发生的各种错误情况，如网络连接中断、服务器异常等，我们设计了一套完善的错误捕捉和重试机制，对未成功执行部分进行补偿式重试，以保障整体流程具有高度鲁棒性和容错性。
### 调用源系统小满OKKICRM接口/v1/company/updates获取并加工数据
在数据集成的生命周期中，调用源系统接口获取数据是至关重要的一步。本文将深入探讨如何通过轻易云数据集成平台调用小满OKKICRM的接口`/v1/company/updates`来获取客户更新信息，并进行必要的数据加工。
#### 接口配置与请求参数
首先，我们需要配置API接口及其请求参数。根据提供的元数据配置，`/v1/company/updates`接口采用GET方法，主要用于获取客户更新信息。以下是该接口的主要请求参数：
- `start_index`: 第几页，默认值为1。
- `count`: 每页记录数，默认值为20，这里设置为200以提高效率。
- `removed`: 是否查询已删除数据，默认值为0，设置为1时查询已删除的数据列表。
- `all`: 查询所有客户，默认值为1，设置为0只查询私海客户。
- `group_id`: 客户分组ID，用于筛选特定分组的客户。
- `date`: 查询从此日期到今天为止有更新的客户列表。
- `start_time`: 开始日期，使用变量`{{LAST_SYNC_TIME|datetime}}`表示上次同步时间。
- `end_time`: 结束日期，使用变量`{{CURRENT_TIME|datetime}}`表示当前时间。
此外，还有两个辅助请求参数：
- `info_api`: 详情接口，用于获取客户详细信息，这里设置为`/v1/company/info`。
- `info_key`: 详情主键，对应于客户ID，这里设置为`company_id`。
#### 数据请求与清洗
在实际操作中，我们首先需要构建HTTP GET请求，并附带上述参数。以下是一个示例请求URL：
```
https://api.okkicrm.com/v1/company/updates?start_index=1&count=200&removed=0&all=1&start_time={{LAST_SYNC_TIME|datetime}}&end_time={{CURRENT_TIME|datetime}}
```
通过这个URL，我们可以获取到符合条件的客户更新列表。接下来，需要对返回的数据进行清洗和预处理，以确保数据质量和一致性。
清洗步骤包括但不限于：
1. **去重**：确保没有重复记录。
2. **格式化**：将日期、时间等字段格式化为统一标准。
3. **过滤**：根据业务需求过滤掉不必要的数据，例如已删除的记录（如果不需要）。
#### 数据转换与写入
在完成数据清洗后，需要将数据转换为目标系统所需的格式，并写入目标系统。在本案例中，我们将数据写入简道云平台。
转换步骤可能包括：
1. **字段映射**：将源系统字段映射到目标系统字段。例如，将小满OKKICRM中的`company_id`映射到简道云中的对应字段。
2. **数据类型转换**：确保所有字段的数据类型符合目标系统要求，例如将字符串类型的日期转换为日期类型。
最后，通过轻易云平台提供的数据写入功能，将处理后的数据批量写入简道云，实现完整的数据集成流程。
#### 实时监控与异常处理
为了确保整个过程顺利进行，需要实时监控数据流动和处理状态。一旦发现异常情况（如网络错误、数据格式错误等），应及时记录日志并发送告警通知，以便快速响应和处理。
通过以上步骤，我们可以高效地调用小满OKKICRM接口获取并加工客户更新信息，实现不同系统间的数据无缝对接。这不仅提升了业务透明度和效率，也确保了数据的一致性和准确性。
### 使用轻易云数据集成平台实现客户信息对接至简道云API接口
在数据集成生命周期的第二步中，我们需要将已经从源平台（如小满）集成的数据进行ETL转换，转为目标平台（如简道云）API接口能够接收的格式，并最终写入目标平台。本文将详细探讨如何使用轻易云数据集成平台完成这一过程。
#### 配置元数据
首先，我们需要配置元数据，以便将源数据转换为目标格式。以下是我们使用的元数据配置：
```json
{
"api": "/api/v2/app/{app_id}/entry/{entry_id}/data_create",
"effect": "EXECUTE",
"method": "POST",
"idCheck": true,
"request": [
{"field":"_widget_1720322268295","label":"客户公司名称","type":"string","value":"{name}","parser":{"name":"ConvertObjectParser","params":"value"}},
{"field":"_widget_1720322268296","label":"简称","type":"string","value":"{short_name}","parser":{"name":"ConvertObjectParser","params":"value"}},
{"field":"_widget_1720322268297","label":"国家地区","type":"string","value":"{country_name}","parser":{"name":"ConvertObjectParser","params":"value"}},
{"field":"_widget_1720322268298","label":"客户来源","type":"string","value":"{{基本信息客户来源}}","parser":{"name":"ConvertObjectParser","params":"value"}},
{"field":"_widget_1720322268299","label":"客户标签","type":"string","value":"_function CASE WHEN '{{tag.3.tag_name}}'!='' THEN '{{tag.0.tag_name}}、{{tag.1.tag_name}}、{{tag.2.tag_name}}、{{tag.3.tag_name}}' WHEN '{{tag.2.tag_name}}'!='' THEN '{{tag.0.tag_name}}、{{tag.1.tag_name}}、{{tag.2.tag_name}}' WHEN '{{tag.1.tag_name}}'!='' THEN '{{tag.0.tag_name}}、{{tag.1.tag_name}}' ELSE '{{tag.0.tag_name}}' END","parser":{"name":"ConvertObjectParser","params":"value"}},
{"field":"_widget_1720322268300","label":"客户分组","type":"string","value":"{{管理信息客户分组}}","parser":{"name":"ConvertObjectParser","params":"value"}},
{"field":"_widget_1720322268301","label":"客户阶段","type":"string","value":"{{管理信息客户阶段}}","parser":{"name":"ConvertObjectParser","params":"value"}},
{"field":"_widget_1720322268302","label":"客户星级","type": "string", "value": "{{管理信息客户星级}}星", "parser": {"name": "ConvertObjectParser", "params": "value"}},
{"field": "_widget_1720322268303", "label": "公海分组", "type": "string", "value": "{pool_name}", "parser": {"name": "ConvertObjectParser", "params": "value"}},
{"field": "_widget_1720322268304", "label": "座机", "type": "string", "value": "_function CASE WHEN '{{联系信息座机.tel_area_code}}'!='' and '{{联系信息座机.tel}}'!='' THEN '{{联系信息座机.tel_area_code}}-{{联系信息座机.tel}}' ELSE '{{联系信息座机.tel}}' END", "parser":{"name": "ConvertObjectParser", "params": "value"}},
{"field": "_widget_1720322268305", "label": "年采购额", "type": "string", "value": "_function CASE {{特征信息年采购额}} WHEN '0' THEN '无采购额' WHEN '1' THEN '0~1千美元' WHEN '2' THEN '1千~5千美元' WHEN '3' THEN '5千美元~1万美元' WHEN '4' THEN '1万~3万美元' WHEN '5' THEN '3万~5万美元' WHEN '6' THEN '5~10万美元' WHEN '7' THEN '10万~30万美元' WHEN '8' THEN '30万~50万美元' WHEN '9' THEN '50~100万美元WHEN ‘10’THEN‘500万美元以上’ELSE900END”,“解析器”:{“名称”:“对象解析器转换”,“参数”:“值”}},
{“字段”:“ _ widget _ 1720322268306 ”,“标签”:“昵称”,“类型”:“字符串”,“值”:“ {{ customers . name }} ”,“解析器”:{“名称”:“对象解析器转换”, “参数”：“值”}},
{“字段”: “ _ widget _ 1720322268307 ”,“标签”： “电子邮件”，“类型”： “字符串”，“值”： “ {{ customers . email }} ”，“解析器”： { “名称”： “对象解析器转换”， “参数”： “值”}},
{“字段”: “ _ widget _ 1720322268308 ”，“标签”： “联系电话”，“类型”： “字符串”，“值”： “ _ function CASE 当‘ {{ customers . tel_list _ 0 }} ’！= '' 和‘ {{ customers . tel_list _ 1 }} ’！= '' 然后‘ {{ customers . tel_list _ 0 }} - {{ customers . tel_list _ 1 }} ’ ELSE ‘ {{ customers . tel_list _ 1 }} ’ END”，“解析器”： { “名称”： “对象解析器转换”， “参数”： “值”}}
],
otherRequest: [
{ field: is_start_workflow, label: is_start_workflow, type: string, describe: 111, value: true },
{ field: is_start_trigger, label: is_start_trigger, type: string, describe: 111, value: false },
{ field: transaction_id, label: transaction_id, type: string, describe: 111, value: 1 },
{ field: appId, label: appId, type: string, describe: 111, value: 647efacc2a57bd0008e51e9e },
{ field： entryId， label： entryId， type： string， describe：111， value：668a08beaf5a1cb83e659b52}
]
}
```
#### 数据请求与清洗
在进行ETL转换之前，我们需要确保从源系统获取的数据是干净且符合要求的。这一过程包括：
- **数据请求**：通过API或其他方式从源系统获取原始数据。
- **数据清洗**：对原始数据进行处理，去除冗余或错误的数据，确保数据质量。
#### 数据转换与写入
在完成数据请求与清洗后，我们进入ETL流程的关键步骤，即将清洗后的数据转换为目标格式并写入简道云。以下是详细步骤：
##### 数据映射与转换
根据元数据配置，将源系统的数据字段映射到目标系统的相应字段。例如：
- 将源系统中的`{name}`映射到简道云中的`客户公司名称`。
- 将`{short_name}`映射到`简称`。
- 使用条件语句和函数处理复杂的数据转换，如处理`联系电话`和`年采购额`。
##### API接口调用
使用HTTP POST方法调用简道云的API接口，将转换后的数据发送到目标系统。具体调用示例如下：
```http
POST /api/v2/app/647efacc2a57bd0008e51e9e/entry/668a08beaf5a1cb83e659b52/data_create HTTP/1.1
Host: api.jiandaoyun.com
Content-Type: application/json
Authorization: Bearer <Your_Access_Token>
{
"_widget_1720322268295": "{name}",
"_widget_1720322268296": "{short_name}",
"_widget_1720322268297": "{country_name}",
"_widget_1720322268298": "{{基本信息客户来源}}",
"_widget_1720322268299":
"_function CASE WHEN '{{tag.3.tag_name}}'
!='' THEN '{{tag.0.tag_name}},{{tag.1.tag_name}},{{tag.2.tag_name}},{{tag.3.tag_name}}
ELSE
'{{tag.0.tag_name}},{{tag.1.tag_name}},{{tag.2.tag_name}}
END"
}
```
##### 参数配置与验证
确保所有必要的参数都已正确配置，并在调用前进行验证。例如：
- `is_start_workflow`: true
- `is_start_trigger`: false
- `transaction_id`: 1
- `appId`: `647efacc2a57bd0008e51e9e`
- `entryId`: `668a08beaf5a1cb83e659b52`
#### 实时监控与日志记录
为了确保整个ETL过程顺利进行，需要实时监控API调用的状态，并记录日志以便后续分析和排错。
通过上述步骤，我们成功地将源平台的小满客户信息通过轻易云数据集成平台转化为简道云API接口可接受的格式，并写入到简道云中。这一过程不仅提高了数据处理效率，还保证了业务流程的透明度和可追溯性。
