V5 API
您的 V5 集成指南！
引言
V5 Traceability Gateway 允许 V5 Traceability 产品系列与其他解决方案之间进行双向数据交换。 该网关高度灵活，可快速部署多种不同的 ERP 和外部系统，使客户能够高效地集成整个工厂。 V5 产品系列具有广泛的 API 可用于集成。
本指南将详细概述如何使用各种方法导入和导出数据。 它还将详细说明可以导入的每个实体以及这些实体的可能字段。
网关可以通过两种主要方式使用：
- 通过使用 JSON 或 XML 文件的 Web 界面 REST API。
- 通过与 CSV 或 XML 文档的直接文件共享。
本指南将介绍这两种方法，并提供数据集成主要领域的示例。
目录
1. V5网关的作用是什么？
V5 Traceability集成服务可以部署覆盖一系列数据点，每个客户可以根据自己的需求完全定制这些数据点。 这些要求将在 V5 Traceability 实施的初始阶段进行讨论。
根据客户要求，V5 Traceability 可以设置为集成任意数量的领域，例如配方/物料清单、作业调度、采购和销售订单以及库存水平和位置。
2. 数据流程图示例
下面的数据流图举例说明了主机 ERP 系统和 V5 Traceability 的无缝集成。 从收货和库存管理到批次制定、产品创建、销售订单拣选和运输。 V5 网关使企业能够有效地简化运营，提高生产可视性并防止可追溯过程中的错误。
3. 集成指南
4.V5集成参考文档
5. 方法论 – V5 API
如果使用此方法，则 V5 API 将作为 Web 服务安装以方便数据传输。 从这里开始，事务由不同的可用模块类处理。
要了解有关这些类、不同端点/URI 的更多信息，以及有关我们在使用 V5 API 时将要处理的各种数据库类的信息，我们可以使用 'V5 集成映射工作表和 V5 API网站 来协助我们。 从这里，我们可以利用该窗口左上角的包浏览器来导航 API 手册的不同部分。
当我们在下面讨论数据集成的各个方面时，我们将利用这些部分来创建示例。
安装后，可以通过浏览器或 REST 客户端访问 API 端点：
http://{hostname:port}/V5-API/api
IntegrationImport 模块的路径为 /integrate/import/
IntegrationExport 模块的路径为 /integrate/export/
“交易”模块路径是 /integrate/export/transactions/
每个方法都有自己的路径，在 V5 API 目录中列为 ‘Target URI’. 可以将其附加到上述路径的末尾以便执行该方法。
每个方法描述还包含一个 ‘request type’，表示它是 GET 还是 POST 请求以及该给定方法的 URI。
任何 GET 或 POST 请求都将以 JSON 格式处理。 所有字段和对象都在数据库包中定义，您可以通过 服务包.
5.1. 导出/获取请求
如上所述，V5 API导出模块的路径为：
http://{hostname:port}/V5-API/api/integrate/export/
所以实际上这看起来像这样（如果通过本地安装的 V5 API 实例进行交互）：
http://127.0.0.1:8080/V5-API/api/integrate/export/
此后会发生什么取决于我们想要从 V5 中提取哪些数据。 然后，我们将通过使用主 API 窗口左侧的窗口来选择服务包，然后选择下面的“IntegrationExport”来引用服务包。
我们还可以使用索引页面上的服务链接，然后该链接将加载该包的类摘要，然后我们可以在其中选择“IntegrationExport”类。
然后我们将看到导出目标 URI (1) 以及导出模块类的可用端点列表。 我们可以通过单击“IntegrationExport”构造函数 (2) 来详细查看所有这些内容，或者我们可以使用 ‘Method Summary’ 下表(3)可快速找到所需的终点。 我们还可以在页面顶部看到该模块的目标 URI，因此我们现在需要做的就是识别所需的对象、字段和值。
因此，我们采用方法摘要表中的第一个条目， ‘Batch’. 单击右侧列 (4) 中的链接将直接带到我们想要了解的端点。
这为我们提供了需要了解的信息，包括将调用哪些数据、请求类型，以及最重要的请求的目标 URI。
所以我们现在知道，如果我们想从 V5 API 中提取批次，我们需要访问的端点是：
http://127.0.0.1:8080/V5-API/api/integrate/export/batch/{batchNumber}
让我们快速看看这在实践中是如何运作的。 我们可以首先找到我们想要通过 API 拉取的批次，让我们寻找批次“50009622”，我们可以在此处看到 控制中心.
利用我们上面学到的知识，我们可以在 REST 客户端中完成 URI，如下所示：
现在运行此进程将为该批次生成详细的 JSON 文件，然后客户端应用程序可以使用和解析该文件。 此请求的典型返回可能如下所示。
在许多情况下，多元化适用于我们正在处理的端点，例如这里批次可以成为批次，我们可以使用它来调用批次列表 ‘export/batches’ URI.
5.2. 导入/POST 请求
如上所述，V5 API导入模块的路径为：
http://{hostname:port}/V5-API/api/integrate/import/
接下来的内容取决于我们希望通过 API 导入哪些数据。 我们将返回到服务包部分 API手册 这次单击“IntegrationImport”(1)。
这与导出页面的布局方式相同，包含导入 URI (2)、下面摘要页面顶部的链接 (3) 以及方法摘要表 (4)，我们可以在其中看到所有可用端点。
和以前一样，我们只需要找到与我们希望通过 API 发布到系统的数据相关的端点。
请注意，大多数导入 POST 端点都需要一个数组，以便可以在一个请求中发送多条记录。 通过查看导入端点的参数类型可以看出这一点 ‘Method Summary’.
我们以商品为例：
这告诉我们的是，我们可以使用此端点导入商品/成分列表，然后将其用于配方。 我们为此使用的 URI 是：
http://127.0.0.1:8080/V5-API/api/integrate/import/commodity
我们可以在下面看到这个端点的使用情况，以及一个非常基本的 JSON 格式的示例导入文件：
为了帮助我们构建 JSON 导入文件，我们可以使用服务摘要中 API 手册的相关数据库包部分的链接：
或者，我们可以通过从以下位置选择数据库类摘要部分来手动导航到相关部分： API主页.
如果我们导航到下面的数据库类页面 ‘Commodity’, 我们可以如何构建 JSON 文件。 例如，如果我们想在使用这个URI时定义一个商品代码，这将是 ‘code’, 同样对于商品的描述，这将是 ‘description’.
请注意这些字段如何位于上面示例 JSON 文件的最左侧，以及我们可以在屏幕截图中看到的其他字段，例如 ‘defExpiryDays’. 我们还可以将商品的默认成本添加到我们的文件中，检查下面我们可以看到，这只是 ‘cost’ (1). 另请注意，此处列出的任何内容都是 ‘primary key’ (2) 是该端点的必填字段，即如果该字段不存在，则文件将不会导入。
我们还可以从这个数据库类遍历不同级别的 API，所以让我们看看如何做到这一点，以包含有关我们商品的更多信息 ‘units’.
在本页底部，我们会遇到 ‘WeightUnit’, 我们可以将其用作商品 URI 中的嵌套类。
这为我们提供了数据库类 ‘units’, 它可以与我们已经定义的其他类处于同一级别。 要发现我们可以在此处嵌套哪些数据，我们可以单击 ‘WeightUnit’ 在这里浏览该类的定义。
正如我们所看到的，此类中只有 3 个数据点，而在我们的 JSON 示例中，我们将全部使用它们， ‘code’, ‘description’, 以及 ‘conversionRate’. 这 3 个数据点将嵌套在 ‘units’ 字段，如图所示。
如果我们像上面那样运行这个 JSON 文件，我们将（取决于我们使用的客户端）看到来自 API 的响应，并且我们还可以看到该商品导入到我们的“大宗商品' 控制中心的表。
5.3. 插入还是更新？
当使用 POST 函数访问 V5 API 的端点时，这可以更新或插入记录。 这里发生的事情是由我们尝试发布的主键定义的。
如果我们以上面的商品为例，我们在数据库类定义中看到商品的代码是其主键。 当我们发布时，如果此代码已经存在，那么我们将使用该类别级别中包含的新值来更新该商品的记录。
相反，如果V5数据库中当前不存在该代码，则将创建一条新记录。
然而，如果我们看看我们的 ‘units’ 嵌套类，请注意，虽然如果此类的主键尚不存在，我们可以插入新的单位数据，但我们无法使用 ‘commodity’ 端点。 相反，我们必须解决 ‘import/unit’ 取而代之的是 URI。
5.4. 导出标记
V5 API 利用导出标记来区分已导出或尚未导出到客户 ERP 系统的数据。 默认情况下，启用此功能是为了协助导出外部 ERP 尚未看到的数据，并且一旦在 V5 数据库中标记为导出，该数据将不会包含在将来的导出中。
但是，可以根据客户偏好禁用此功能。 如果正在使用的 ERP 系统可以将导出标记返回到 V5 API 以确认它已经收到了相关数据，则也可以禁用此功能。
在这种情况下，接收确认用于通知 V5 API 数据已收到，可用于控制该数据的端点已记录 开始.
如果 V5 API 和 ERP 均未设置为提供导出标记，则根据所使用的端点，这可能会返回大量数据。 在这些情况下，我们可以使用 URI 参数来过滤导出的数据量。
5.5. URI参数
V5 API 还利用各种 URI 参数，可用于进一步缩小系统请求的范围。
我们可以通过检查所需服务下的方法摘要来查看这些参数是否可用于我们的端点。 如果我们能看到 ‘int’ 后面跟着一个参数，然后我们可以使用这个参数来过滤我们将从 API 收到的结果。
例如，我们在上面看到这适用于 ‘batch’ 允许我们按批次号进行过滤。
其他示例可能包括按日期提取批处理日志，我们可以在其中使用 ‘batch_system_logs/filterFrom/{filterDate}’ （使用纪元约会约定）。
5.6. 日志、事务和系统描述符
6. 方法论——CSV文件共享
V5 文件共享方法利用 csv 和 csvh“标头”文件与 V5 Traceability 执行数据交换。 对于这些交换，我们将利用“标头”文件来确定导入和导出数据的顺序，然后我们将导入或接收遵循此顺序的导出 csv。 我们可以在下面看看这在实践中是如何运作的。
6.1. 数据和头文件的排序
无论我们是使用csv文件共享方法导入还是导出数据，我们都会利用头文件来确定数据的顺序。 就我们如何构建它们而言，这里我们可以同时利用 'V5 集成映射工作表'以及网上的 API手册 帮助我们解决这个问题。 让我们看一个例子 ‘Commodities’ 从工作表导入。
正如我们在这里看到的，SG已经在这里构建了一个基本的头布局，如果我们查看这个特定数据库类的API手册，我们可以看到这里的大部分字段都存在于这个类中，允许我们简单地使用 ‘code’, ‘cost’, ‘bulkUnit’ 等等，正如它们在这里定义的那样。
请注意，与我们在上面构建 JSON 文件时类似，主键 (code) 必须包括在内。
我们还可以以与上面构造 JSON 导入时看到的类似方式遍历数据库类。 我们可以在上面的示例中看到这一点 ‘units.code’。 内 ‘Commodity’ 类我们有 ‘WeightUnits’ 类（定义为 ‘units’).
通过此链接访问 ‘WeightUnit’ 类将向我们展示定义重量单位的代码，这是 ‘code’ 在这个类中，所以从我们的 ‘Commodity’ 起点是 ‘units.code’.
我们可以在这里遍历任意多个级别，只需在 API 手册中链接它们即可。
我们将对用于导出的结构标头执行相同的操作，使用适当的数据库类定义来确定我们想要从系统接收回的数据以及按什么顺序。
头文件应构建为 csv 文件，顶行的每个单元格中都有 1 个值，直到我们定义了要导入或导出的所有数据。 然后必须保存此 csv 文件，然后将其扩展名编辑为 ‘csvh’ 文件（必须启用 Windows 中的文件扩展名查看才能执行此操作）。
对 csvh 文件的任何编辑都应在将其更改回 csv 文件并以此格式进行编辑后进行。
用于导入的标头应放置在：
<installdir>\SG Control Center\gateway\import\column_defs
用于导出的标头应放置在：
<installdir>\SG Control Center\gateway\export\order
我们现在可以看看如何进行进出口。
6.2. 进口
一旦我们的相关头文件就位，我们需要完成我们的 csv 文件以供导入。
如前所述，csv 文件中的数据必须遵循与其相应头文件相同的结构，即正确的数据必须位于正确的列中，才能成功导入。 继续我们的商品示例，我们可以看到在下面的示例中，我们包含了标题数据来帮助我们输入数据。 然而，这并不需要包含在内（请参阅下面的“忽略标头”）。
设置完成后，我们可以继续填充 csv 以包含我们想要导入的所有商品。
csv 完成后，可以通过将适当格式和命名的 csv 文件放入其中来执行导入 ‘\SG Control Center\gateway\import’。 这些文件的命名约定在 V5 集成映射工作表中定义，因此对于商品，我们可以看到：
例如，我们的文件名可以命名为“commodity-0530231803.csv”，以告诉我们这是在 30th 2023 年 18 月 @ 03:XNUMX。 没有设定的日期/时间订单首选项，因此 SG 建议使用最适合每个客户的格式（这可能最终由所使用的外部 ERP 确定）。
将我们的文件放入正确的文件夹后，控制中心将自动处理这些文件，前提是在网关中启用了导入。 系统将提供对话来告知我们该过程是否成功。 有关此问题的更多信息（包括日志）可以在控制中心的“网关”部分中找到。
还可以通过右键单击系统中的控制中心图标并选择“网关”>“导入文件”，从其他位置手动导入文件。
然后，这将在控制中心内打开一个对话框以选择适当的 csv 文件。
在网关本身内，我们可以针对导入过程设置选项：
这里的设置可以定义如下：
- 启用导入 – 启用导入，允许网关扫描导入文件夹中的 csv 文件（当它们放入其中时）。
- 插入子实体 – 允许网关动态创建内部实体（如果它们在 csv 文件中链接）。 一个很好的例子是公式导入，其中列出了数据库中尚未存在的商品。 在这种情况下，如果提供了商品（代码）的主键，网关将为我们创建这些“子”实体。
- 忽略标头 – 强制网关跳过导入的 csv 的第一行（行）。 如果头文件包含在 csv 导入文件中，这非常有用。
- 验证等级 – 设置网关导入数据时如何验证数据。 这里有 2 个选项：
- 警告 – 如果文件中存在错误并且无法导入某一行，系统会告诉您相关情况，但会继续尝试处理文件的其余部分。
- 流产 – 如果文件中存在错误并且无法导入该行，系统将中止该过程并通知您该错误。
然后可以在此面板的右上角应用对设置的更改。 必须重新启动控制中心才能使任何更改生效。
6.3. 出口
通过 csv 文件共享方法导出主要由头文件以及从系统请求的信息来管理。 如果我们使用 API 手册正确构建这些数据，那么我们应该以正确的顺序收到我们想要的所有数据。
在网关本身内，我们还可以针对导出过程设置选项：
在这里，我们可以使用提供的复选框来选择我们希望导出的数据，具体取决于我们希望查看的数据点。
注意这里的起始数据库类，比如 ‘BatchConsumption’ 以及 ‘SystemLogs’ 与我们开始导入时不同，但只要我们能够成功浏览这些类的 API 手册，我们就可以生成合适的头文件。
选择要导出的内容后，只需在左上角输入导出间隔（以毫秒为单位）并在右上角应用该值（0 将永远不会导出）即可。 必须重新启动控制中心才能使任何更改生效。
导出的 csv 文件将放置在 ‘<installdir>\SG Control Center\gateway\export’ by default.
7. 频率和顺序
无论使用何种方法与 V5 Traceability 集成，数据导入和导出的频率和自动化水平都是流程的一个要素，可以根据每个客户的要求进行构建。
这可以由客户手动完成，也可以自动从客户服务器上的特定位置捕获外部 ERP 的输出。
在此阶段还可以施加特定的导入顺序，例如，我们可能会在与该 BOM 相关的工作订单之前导入物料清单。 我们可以通过按顺序将文件加载到导入目录或 API URI 端点来做到这一点。
如上图，我们还可以设置Gateway以特定的时间间隔导出，将数据发送回ERP系统。
导入和导出可以近乎实时地管理或按设定的时间间隔执行。 使用 API 路径，可以更轻松地近乎实时地管理导入和导出。 csv 文件共享方法的导入频率取决于正在实施的各个 ERP/中间件解决方案，导出频率通过如上所述的控制中心进行管理。
8。 联系我们
对 V5 Traceability 及其提供的数据集成感兴趣？ 联系我们的销售团队 开始!
