### 金蝶客户资料同步至简道云：技术案例分享 在本次的系统对接集成实践中，我们将重点探讨如何高效地将金蝶云星空中的客户资料同步到简道云。我们采用了“金蝶客户资料同步至简道云”的方案，通过轻易云数据集成平台进行配置，实现了多个关键技术点。 首先，为确保数据从金蝶云星空不漏单且完整无误地抓取下来，我们调用了金蝶API接口`executeBillQuery`，并在相关操作中处理分页和限流问题。这不仅有效避免因请求过多而导致的数据丢失或错误，也保障了数据获取的稳定性与可靠性。 其次，在向简道云写入数据时，我们利用其提供的API接口 `/api/v2/app/{app_id}/entry/{entry_id}/data_create` 实现大量数据快速写入。同时，通过定制化的数据映射功能，使得两套系统之间的数据格式差异得到妥善处理，确保每一条记录都能准确存储于简道云之中。 值得一提的是，为进一步提升集成过程中的可维护性和透明度，我们实现了实时监控与日志记录功能，对整个数据处理流程进行全程跟踪。一旦出现异常情况，会触发自动重试机制，以便及时纠正错误，减少人工干预成本。 通过以上几个关键环节的配合，本方案实现了一站式、全自动化、高效稳健的数据同步，为企业更好地管理和利用客户信息提供坚实基础。在下文部分，将详细展示具体实施细节及代码示例。  ### 调用金蝶云星空接口executeBillQuery获取并加工数据 在数据集成过程中，调用源系统的API接口是至关重要的一步。本文将详细探讨如何使用轻易云数据集成平台调用金蝶云星空的`executeBillQuery`接口，以获取客户资料并进行初步加工。 #### 接口配置与调用 首先，我们需要配置元数据以便正确调用金蝶云星空的`executeBillQuery`接口。以下是关键的元数据配置： ```json { "api": "executeBillQuery", "effect": "QUERY", "method": "POST", "number": "FNumber", "id": "FCUSTID", "name": "FName", "idCheck": true, "request": [ {"field":"FCUSTID","label":"FCUSTID","type":"string","describe":"FCUSTID","value":"FCUSTID"}, {"field":"FNumber","label":"编码","type":"string","describe":"编码","value":"FNumber"}, {"field":"FName","label":"名称","type":"string","describe":"名称","value":"FName"}, {"field":"FCreateOrgId_FNumber","label":"创建组织","type":"string","describe":"创建组织","value":"FCreateOrgId.FNumber"}, {"field":"FUseOrgId_FNumber","label":"使用组织","type":"string","describe":"使用组织","value":"FUseOrgId.FNumber"}, {"field":"FDescription","label":"描述","type":"string","describe":"描述","value":"FDescription"}, {"field":"FIsTrade","label":"是否交易客户","type":"string","describe":"是否交易客户","value":"FIsTrade"}, {"field":"FCustTypeId_FNumber","label":"客户类别","type":"string","describe":"客户类别","value":"FCustTypeId.FNumber"}, {"field":"FGroup_FNumber","label":"客户分组","type":"string","describe":"客户分组","value":"FGroup.FNumber"}, {"field":...}, ... ], "otherRequest": [ {"field": "Limit", "label": "最大行数", "type": "string", "describe": "金蝶的查询分页参数", "value": "{PAGINATION_PAGE_SIZE}"}, {"field": "StartRow", "label": "开始行索引", "type": "string", "describe": "金蝶的查询分页参数", "value": "{PAGINATION_START_ROW}"}, {"field": ...}, ... ], ... } ``` #### 请求参数解析 在请求参数中，最重要的是`FieldKeys`和`FilterString`两个字段： - `FieldKeys`: 指定了需要查询的字段集合，例如 `"FieldKeys":["FCUSTID", "FNumber", ...]`。 - `FilterString`: 用于设置过滤条件，例如 `"FilterString" : “FSupplierId.FNumber = 'VEN00010' and FApproveDate>='{{LAST_SYNC_TIME|datetime}}'"`。 这些参数确保了我们能够精确地获取所需的数据，并且可以根据业务需求灵活调整。 #### 数据请求与清洗 一旦配置完成，我们可以通过POST方法发送请求到金蝶云星空的API端点。以下是一个示例请求体： ```json { "FormId": "BD_Customer", "FieldKeys": ["FCUSTID", "FNumber", ...], “FilterString”: “FSupplierId.FNumber = 'VEN00010' and FApproveDate>='2023-01-01'”, “Limit”: “100”, “StartRow”: “0” } ``` 在接收到响应后，我们需要对数据进行清洗和初步加工。这包括但不限于： - **数据格式转换**：将日期、数值等字段转换为目标系统所需的格式。 - **数据验证**：检查关键字段是否为空或不符合预期格式。 - **数据过滤**：根据业务规则过滤掉不必要的数据。 #### 实践案例 假设我们需要同步金蝶云星空中的客户资料到简道云系统。首先，通过上述配置和请求，我们从金蝶云星空获取了如下示例数据： ```json [ { “FCUSTID”: “C12345”, “FNumber”: “K001”, “FName”: “某某公司”, ... }, ... ] ``` 接下来，我们对这些数据进行清洗和转换。例如，将日期格式从“YYYY-MM-DD”转换为“DD/MM/YYYY”，并验证每个客户编号（`FCUSTID`）是否唯一且非空。 #### 数据转换与写入 经过清洗后的数据将被传递到下一阶段进行转换和写入。这一步通常涉及将清洗后的数据映射到目标系统的数据模型，并通过API或批量导入工具写入目标系统。 通过这种方式，我们实现了从源系统（金蝶云星空）到目标系统（简道云）的无缝数据集成，确保了数据的一致性和完整性。 总结来说，调用源系统API并进行初步的数据清洗和加工，是整个数据集成生命周期中的关键步骤。通过合理配置元数据和灵活运用API接口，可以大大提升集成效率和准确性。  ### 金蝶客户资料同步简道云的ETL转换技术案例 在数据集成生命周期的第二步，我们需要将已经从源平台（金蝶）获取的数据进行ETL转换，以适应目标平台（简道云API接口）的格式要求，并最终写入简道云。本文将详细探讨如何利用轻易云数据集成平台配置元数据，完成这一过程。 #### 元数据配置解析 首先，我们来看一下元数据配置的具体内容： ```json { "api": "/api/v2/app/{app_id}/entry/{entry_id}/data_create", "effect": "EXECUTE", "method": "POST", "idCheck": true, "request": [ {"field":"_widget_1670211164732","label":"ERP编码（客户编码）","type":"string","value":"{FNumber}","parser":{"name":"ConvertObjectParser","params":"value"}}, {"field":"_widget_1670211164733","label":"客户名称","type":"string","value":"{FName}","parser":{"name":"ConvertObjectParser","params":"value"}}, {"field":"_widget_1670211164737","label":"客户简称","type":"string","value":"{FShortName}","parser":{"name":"ConvertObjectParser","params":"value"}}, {"field":"_widget_1670211164734","label":"创建组织","type":"string","value":"{FCreateOrgId_FNumber}","parser":{"name":"ConvertObjectParser","params":"value"}}, {"field":"_widget_1670211164735","label":"使用组织","type":"string","value":"{FUseOrgId_FNumber}","parser":{"name":"ConvertObjectParser","params":"value"}}, {"field":"_widget_1670211164736","label":"客户类别","type":"string","value":"{FCustTypeId_FNumber}","parser":{"name":"ConvertObjectParser","params":"value"}}, {"field":"_widget_1670211164738","label":"发票抬头","type":"string","value":"{FINVOICETITLE}","parser":{"name":"ConvertObjectParser","params":"value"}}, {"field": "_widget_1670211164740", "label": "通讯地址", "type": "string", "value": "{FINVOICEADDRESS}", "parser": { "name": "ConvertObjectParser", "params": "value" }}, {"field": "_widget_1683680135441", "label": "联系电话", "type": "string", "value": "{FINVOICETEL}", "parser": { "name": "ConvertObjectParser", "params": "value" }}, {"field": "_widget_1683680135440", "label": "公司网址", "type": "string", "parser": { "name": "ConvertObjectParser", "params": "value" }}, {"field": "_widget_1683680135438", "label": "国家", "type": "string", "parser":{"name" : "ConvertObjectParser" , "params" : "value"} }, {"field" : "_widget_1683680135439" , "label" : "地区" , "type" : "string" , "parser":{"name" : "ConvertObjectParser" , "params" : "value"} }, {"field" : "_widget_1683680135442" , "label" : "公司类别" , "type" : "string", "value" : "{FCompanyClassify_FNumber}" ,"parser":{"name":"","params":"","description":"","defaultValue":"","required":"","minLength":"","maxLength":"","pattern":"","format":"","enum":[],"enumNames":[],"enumDescriptions":[],"additionalProperties":"","example":"","xmlNamespacePrefix":"","xmlNamespaceUri":"","xmlAttributeName":"","xmlWrappedElementName":"","xmlWrappedElementWrapperName":"","xmlWrappedElementNamespacePrefix":"","xmlWrappedElementNamespaceUri":"","xmlWrappedElementAttributeName":"","xmlWrappedElementWrapperNamespacePrefix":"","xmlWrappedElementWrapperNamespaceUri":"","mediaType":[],"contentEncoding":[],"contentMediaType":[],"contentSchema":[],"contentEncodingProperty":[],"contentMediaTypeProperty":[],"contentSchemaProperty":[]}}, {"field"_widget:1683680135443,label:"公司性质"，type:"string"， value:"{FCompanyNature_FNumber}"， parser:{"name: ConvertObjectParser"， params: value}}, {"field"_widget:1683680135444,label:"公司规模"， type:"string"， value:"{FCompanyScale_FNumber}"， parser:{"name: ConvertObjectParser"， params: value}}, {"field"_widget:1683680135445,label:"纳税登记号"， type:"string"， value:"{FTAXREGISTERCODE}"， parser:{"name: ConvertObjectParser"， params: value}}, {"field"_widget:1683680135446,label:"结算币别"， type:"string"， value:"{FSETTLETYPEID_FNumber}"， parser:{"name: ConvertObjectParser"， params: value}}, {"field"_widget:1683680135447,label:"结算方式"， type:"string"， value:"{FSETTLETYPEID_FNumber}"， parser:{"name: ConvertObjectParser"， params: value}}, {"field"_widget:1683680135448,label:"收款条件"， type:"string"， value:"{FRECCONDITIONID_FNumber}"， parser:{ name： ConvertObjectParser ， params： value } }, { field:_ widget： 1683680135449 ， label： 默认税率 ， type： string ， parser： { name： ConvertObjectParser ， params： value } }， { field:_ widget： 1683680135450 ， label： 发票类型 ， type： string ， value： { FInvoiceType } ， parser： { name： ConvertObjectParser ， params： value } }， { field:_ widget： 1683680135451 ， label： 税分类 ， type： string ， value： { FTaxType_FNumber } ， parser:{ name ： ConvertObjectParser ， params ： value } }, { field:_ widget ： 1683680135452 ， label ： 发票抬头 ， type ： string ， value ： { FINVOICETITLE } ， parser ： { name ： ConvertObjectParser, params:value }}, { field:_ widget ： 1683680135437, label ： 禁用状态, type:string, parser:{ name ： ConvertObjectParser, params:value }}, { field:_ widget ： 1683680135436, label ： 单据状态, type:string, parser:{ name ： ConvertObjectParser, params:value }} ], 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:“应用ID”, type：“string”， describe：“111”， value：“63899c8e6705fb000870437d” }, { field：“entryId”， label：“表单ID”， type：“字符串”， describe：“111”， value：“638d60affade39000a66838a” } ] } ``` #### 数据转换与写入 在上述元数据配置中，我们可以看到每个字段都被映射到简道云API接口所需的格式。以下是具体操作步骤： 1. **字段映射与转换**： - 使用`ConvertObjectParser`解析器，将金蝶中的字段值转换为简道云所需的格式。例如： - `ERP编码（客户编码）` 对应 `金蝶` 中的 `{FNumber}`。 - `客户名称` 对应 `金蝶` 中的 `{FName}`。 - 每个字段都有一个对应的解析器来确保数据格式正确。 2. **API请求构建**： - API请求采用POST方法，通过`/api/v2/app/{app_id}/entry/{entry_id}/data_create`接口，将转换后的数据发送到简道云。 - 请求体中包含所有需要同步的数据字段。 3. **其他请求参数**： - `is_start_workflow`: 是否启动工作流。 - `is_start_trigger`: 是否启动触发器。 - `transaction_id`: 事务ID，用于追踪和管理数据同步事务。 - `appId`: 应用ID，指定目标应用。 - `entryId`: 表单ID，指定目标表单。 #### 实际操作示例 假设我们从金蝶获取了一条客户信息，如下所示： ```json { “FNumber”: “C001”, “FName”: “某某公司”, “FShortName”: “某某”, “FCreateOrgId_FNumber”: “ORG001”, “FUseOrgId_FNumber”: “ORG002”, “FCustTypeId_FNumber”: “TYPE001”, “FINVOICETITLE”: “某某公司发票抬头”, “FINVOICEADDRESS”:“某某市某某区某某路123号”, “FINVOICETEL”：“12345678901” } ``` 根据上述元数据配置，该信息将被转换为以下格式，并通过API接口发送至简道云： ```json { "_widget_1670211164732”:“C001”, “ _ widget _1670211164733 ”:“ 某某公司 ”, “ _ widget _1670211164737 ”:“ 某某 ”, “ _ widget _1670211164734 ”:“ ORG001 ”, “ _ widget _1670211164735 ”:“ ORG002 ”, “ _ widget _1670211164736 ”:“ TYPE001 ”, “ _ widget _1670211164738 ”:“ 某某公司发票抬头 ”, “ _ widget _1670211164740 ”:“ 某某市某某区某某路123号”, “ _ widget _1683680135441”：12345678901 } ``` #### 总结 通过上述步骤，我们成功地将金蝶中的客户资料进行ETL转换，并通过轻易云数据集成平台写入到简道云。这一过程不仅确保了数据格式的一致性，还提高了系统间的数据交互效率。