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

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

使用程序化使用方式

SFF API 设计为通过程序化方式访问，而不是通过手动读取文件。SFF 软件包中包含的清单文件列出了每列的 CSV 文件和元数据，每个研究数据（Study Data）部分都有自己的区组。清单文件中单独列出了研究设计（Study Design）部分。临床数据部分中包含条目定义（Item Definition）数据，因为每个条目（Item）均为 CSV 文件中的一列。

SFF 列标题也被设计为机器可读的。JSON 格式的属性不能保证以特定的顺序排列，因此以程序化方式解析列非常重要。除临床数据部分中的 itemgroups 数组属性外，该属性会维持每个条目定义在条目组中的显示顺序。

高效跟踪更改

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

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

如果发生了错误阻止增量软件包捕获更改，则仍将生成软件包，但将为空。这与软件包为空不同，因为未对文件进行更改。

利用创建日期

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

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

首次启用完整 SFF 软件包时进行检索。如果还启用了增量 SFF，则最初只需检索完整软件包。之后，如果数据变得不同步并且需要完全刷新，可以再次检索完整软件包。