研究形式 API に関するヒントとベストプラクティス

このページでは、スタディファイル形式 API を使用するためのヒントとベストプラクティスを紹介します。

プログラム上の消費を使用

SFF API は、手動でファイルを読み込むのではなく、プログラムでアクセスするように設計されています。SFF パッケージに含まれるマニフェストファイルは、各列の CSV ファイルとメタデータを整理し、各スタディデータセクションは独自のブロックを持ちます。スタディデザインセクションは、マニフェストファイル内で個別に構成されています。各項目は CSV ファイルの列であるため、項目定義データは臨床データセクションに含まれます。

また、SFF の列の見出しは機械が読みとれるように設計されています。JSON 形式の属性は、特定の順序であることが保証されていないため、プログラムで列のパースを行うことが重要です。これは臨床データセクションの itemgroups 配列属性を例外とし、各項目定義が項目グループ内に現れる順序を維持します。

効率的に変更を追跡

SFF の各ファイルには ROWID 列があり、これは各行の一意識別子として機能します。この列を使用して、あらゆる行レベルの変更を追跡します。

各変更を UPSERT として扱う: インクリメンタル SFF ファイルに行が表示された場合、その行に追加または変更が加えられたことを示します。
DELETES CSV ファイルは、最新の変更で削除された行をリストアップします。

エラーによってインクリメンタルパッケージが変更を取り込むことができない場合、パッケージは生成されますが、空になります。これは、ファイルに変更がないため、パッケージが空であることとは異なります。

作成済み日付の活用

ファイル名には、インクリメント抽出の場合は 15 分ごと、完全抽出の場合は 24 時間ごとで、定義された各インクリメントの公開時間が含まれます。SFF の ZIP パッケージは、API が返す created_date の順番で利用するのがベストプラクティスです。created_date を使用すると、特にインクリメンタル SFF 消費の場合、下流のシステムに変更を適用する順序を理解し、同期を保つのに役立ちます。例えば、created_date は UTC の 00:30 でも、公開時間は 00:45 を示す場合があります。これは、システムが 00:30 から 00:45 までの時間間隔を取り込んでいるためです。

セットアップとリフレッシュのための SFF フルパッケージを取得

初めて有効化する時、SFF フルパッケージを取得します。インクリメンタル SFF も有効な場合、最初はフルパッケージを取得するだけで十分です。その後、データの同期が取れなくなり、完全なリフレッシュが必要になった場合は、再度フルパッケージを取得することができます。