关于研究文件格式 API 的实用提示和最佳实践

此页面列出了使用研究文件格式（SFF）API 的一些技巧和最佳实践。

使用程序化使用方式

最佳实践：使用代码从 SFF API 访问数据，而不是尝试手动读取文件。

SFF API 设计为通过程序化方式访问，而不是通过手动读取文件。SFF 软件包中的清单文件列出了每列的 CSV 文件和元数据，每个研究数据（Study Data）部分都有自己的区组。

清单文件中单独列出了研究设计（Study Design）部分。Clinical Data 部分中包含项目定义（Item Definition）数据，因为每个项目（Item）均为 CSV 文件中的一列。清单应被视为 SFF 元数据和架构的真实来源。

列标题

SFF 列标题也被设计为机器可读的。JSON 格式的属性不能保证以特定的顺序排列，因此以程序化方式解析列非常重要。Clinical Data 部分中的 itemgroups 数组是唯一的例外。此数组会保持每个条目定义 在条目组中出现的顺序。这可以防止在多个条目组定义中使用相同的条目定义。

高效跟踪更改

最佳实践：使用行 ID（Row ID）列跟踪更改，并查看 Deletes 文件以获取已删除的行。

SFF 中的每个文件都包含一个行 ID（Row ID）列，该列用作每行的唯一标识符。使用此列可跟踪任何行级更改。

将每个更改视为更新并插入：如果增量 SFF 文件中出现一行，则表示对该行进行了添加或修改。
Deletes CSV 文件列出了在最新更改增量中删除的所有行。

映射引用数据

最佳实践：使用 Labels 文件通过类型（Type）列将对象名称链接到其标签，并使用 Override Labels 文件来识别对象关系中的显示覆盖。

完整的 SFF 软件包包括两个 CSV 文件：Labels 和 Override Labels。这些文件为 Veeva EDC 中配置的标签（Labels）和显示覆盖标签（Display Override Labels）提供了额外的数据。

Labels 文件

在 Labels CSV 文件中，使用类型列来标识标签的类别，并将其映射到对象的原始名称（Name）。

例如，如果类型为“事件（Event）”，则指的是 event definition label。event definition name 是 SFF 文件中的事件名称（Event Name）列。因此，Labels 文件可用于在事件定义名称（Event Definition Name）和事件定义标签（Event Definition Label）之间进行映射。

Override Labels 文件

如果在 EDC 工作室中为特定对象关系配置了显示覆盖标签，则使用 Override Labels 文件来识别它。

有五种类型的覆盖标签，每种都链接到一个研究定义对象：

事件组
事件
表单
项组
条目

源定义（Source Definition）列将源定义名称映射到目标定义（Target Definition）列中对应的目标定义名称。

例如：

源定义值为“form_A”，源标签类型（Source Label Type）为“form”。目标定义名称为“ig_A”，目标标签类型为“itemgroup”。

这意味着名为“ig_A”的条目组定义（Item Group Definition）属于名为“form_A”的表单定义，并且设置了显示覆盖标签，其值显示在目标覆盖标签（Target Override Label）列中。

利用创建日期

最佳实践：按照 API 的 created_date 提供的顺序处理 SFF 软件包。

文件名中包括了每个规定增量的发布时间：增量提取每 15 分钟一次，完整提取每 24 小时一次。在处理 SFF 压缩包时，最佳实践是按照 API 返回的 created_date 顺序来使用。使用 created_date（尤其是对于增量 SFF 使用）有助于了解将更改应用于下游系统以使其保持同步的顺序。例如，created_date 可能在 00:30 UTC 左右，但发布时间可能显示 00:45。这是因为系统已捕获 00:30 和 00:45 之间的时间间隔。了解有关文件名的更多信息。

检索完整 SFF 软件包以进行设置和刷新

最佳实践：在设置时检索一次完整的 SFF 软件包，若需要完全刷新，则再次检索。

首次启用完整 SFF 软件包时应进行检索。如果还启用了增量 SFF，则除非需要第三方数据，否则只需在初始时检索完整数据包。第三方数据仅在完整包中可用。如果您的数据变得不同步并且您需要完全刷新，您可以再次检索完整软件包。