APIの設定

  • Published by Viedoc System 2024-11-12
  • Print

API設定機能へのアクセス

Viedoc AdminでAPI設定機能にアクセスし、試験のAPIクライアントを管理するには、試験のAPI管理者ロールを持つ必要があります。

API クライアント ID

APIを使用してViedoc試験に関連するAPIエンドポイントに接続して通信するには、APIクライアントIDが必要です。クライアントIDは以下のように使用されます。

  • クライアントIDは、Viedocのユーザー名とパスワードとともに、ユーザー認証に使用されます。
  • 認証にクライアントIDとクライアントシークレットが使用されます。ユーザコンテキストは必要ありません。

ID.Viedocの旧バージョンとの後方互換性を確保するために、APIクライアントIDの作成時にどのバージョンのデータ構造を使用するかを選択できます。

Viedoc WCF APIクライアントの追加とAPIクライアントIDの取得

以下のように、APIクライアントを追加しクライアントIDを取得します。

1 Viedoc ようこそページで、Adminアイコンをクリックし、Viedoc Adminを開きます。

2 対象の試験を開き、API設定の編集ボタンをクリックして、API設定ダイアログを開きます。

注意！ API設定にアクセスするには、試験のAPI管理者ロールを持つ必要があります。

4 API クライアントの名前を入力し、ステータスドロップダウンメニューからクライアントを本番試験とデモ試験のどちらに紐付けるかを選択します。追加をクリックします。

5 クライアントIDが生成され、WCF APIクライアントの一覧に表示されます (1).

6 データ構造のバージョンドロップダウンメニュー (2)から、どのデータ構造のバージョンに対応させるかを選択します。クライアントのステータスは、ステータスドロップダウンメニューから新しいステー タス（本番環境、無効、デモ）を選択することにより、いつでも編集することが ます。

バージョンについての詳細については、PIクライアントIDのデータ構造バージョンについてを参照ください。

7 クライアントIDを後で使用するためにメモしておきます。

Viedoc Web APIクライアントの追加とAPIクライアントIDの取得

Viedoc Web APIクライアントを追加し、APIクライアントIDを取得します。

1 Viedocランディングページで、Adminアイコンをクリックし、Viedoc Adminを開きます。

2 作業したいスタディーを開き、API設定欄の編集ボタンをクリックして、API設定ダイアログを開きます。

注意！API設定フィールドを表示するには、API管理者のユーザーロールが必要です。

3 Web APIクライアントタブで、新しいWeb APIクライアントを追加をクリックします。

4 APIクライアントの名前を入力します。

5 どのデータ構造のバージョンに対応させるかを選択します。

6 ステータスドロップダウンメニューから、クライアントを本番環境とデモのどちらの試験にリンクさせるかを選択します。クライアントのステータスは、ドロップダウンメニューから新しいステータス（本番環境またはデモ）を選択することで、いつでも編集することができます。

有効/無効ボタンで試験のステータスを切り替えることもできます。これは、Web API クライアントを無効にする迅速な方法です。無効なクライアントをAPIコールで使用すると拒否されます。

注意！ PMS試験用にAPIを設定する場合、データコントローラードロップダウンから企業側または施設側を選択し、スコープを絞り込むことができます。

7 ユーザーに対して適用可能なスコープを選択します。利用可能なスコープは以下の通りです。

  • エクスポート
  • 施設を作成/アップデート
  • 施設情報を入手
  • Clinicユーザーを招待 - クライアントのステータスが本番環境であることが必要
  • Adminユーザーを招待 - クライアントのステータスが本番環境であることが必要
  • 契約管理
  • ユーザー情報を取得

注記！エクスポートスコープの定義方法の詳細については、下記を参照してください。

8 オプションで、Web API エンドポイントへのリクエストが許可されている IP アドレスを入力します。

注意！

  • セミコロンで区切ることによって、複数のIPアドレスを追加できます。
  • すべてのIPアドレスからの呼び出しを許可する場合、IPアドレスのフィールドは空白のままにできます。

9 クライアントシークレットの有効期限は、デフォルトで1年先に設定されています。必要に応じて、別の日付を設定することができますが、現在の日付から1年以上先の日付にすることはできません。

10 PI クライアントを追加をクリックします。

11 APIクライアントが追加されると、以下のフィールドが表示されます。

  • クライアントシークレット - ヒント! 一度しか表示されないので、必ずコピーしてください。必要であれば、再生成することができます。
  • クライアントID
  • トークンURL
  • grant_type
  • API URL

12 クライアントIDを後で使用するためにメモしておきます。

13 必要に応じて、スコープ、ステータス、データ構造のバージョンなどの設定を変更することができます。

14 保存をクリックします。

APIクライアントIDのデータ構造バージョンについて

APIクライアントIDを作成する際に、どのデータ構造のバージョンを使用するかを選択する必要があります。選択できるViedocのバージョンは、データ構造の変更が導入されたバージョンだけです。

Viedoc 4.77時点では、以下のデータ構造バージョンが利用可能です。

データ構造バージョン データ構造の変更内容
最新 Viedoc バージョン

最新のViedocバージョンを選択すると、Viedoc APIが通信するデータ構造は、データ構造への変更が導入された最新のViedocリリースの構造に自動的に従います。
Viedoc 4.77 項目レベルの SDV が有効になっている試験では、レビュー状況をエクスポートする際、CSV および Excel データエクスポートの SDV シートには、SDV が必要な項目のみが表示されます。Revew Statusシートでは、SDVを必要としない項目はN/Aで表示されます。
Viedoc 4.68

PDFアーカイブ・エクスポート・システム・チェックを導入し、アーカイブを科目ごとに1つのPDFファイルに分割し、結果のPDFをZIPファイルに格納します。
Viedoc 4.67

医療コーディングの承認に2つの新しいカラムを導入。"approved by" および "approved on date"。
Viedoc 4.51

3つの新しいフォームリピートキーとPDFエクスポートの目次を導入。詳しくは下記テーブルを参照ください。
Viedoc 4.39

繰り返しフォームと繰り返しイベントの導入。詳細は以下の表をご覧ください。
Viedoc 4.38

オリジナル出力フォーマット(Viedocバージョン4.38以前)。

Viedoc 4.51では、エクスポート出力に次のような変更がありました。

ファイルタイプ

 エクスポート出力フォーマットの変更内容
Excel

Addition of three columns for the new form sequence numbers introduced:

  • SubjectFormatFormSeqNo- 対象者レベルで特定のフォームのインスタンスを一意に識別するカウンタで、 1から始まり、その対象者にフォームの新しいインスタンスが作成されるたびに増分されます。
  • OriginSubjectFormSeqNo - コピーされたフォーム インスタンスについて、データが最初にコピーされたフォーム インスタンスを識別します。フォームの最初のインスタンス(つまりコピーされていない)については、SubjectFormSeqNoの値が取得されます。
  • SourceSubjectFormSeqNo - コピーされたフォームインスタンスについて、コピー元のフォームインスタンス (データがコピーされたフォームインスタンス) を識別するためのカウンタです。フォームインスタンスのコピー元の SubjectFormSeqNo の値を取得します。フォームの最初のインスタンス (つまり、コピーされていない) では、これは空です。
ODM

Viedoc拡張機能として、FormData内のFormRepeatKeyの直後に、v4:SubjectFormSeqNo, v4:OriginSubjectFormSeqNo, v4:SourceSubjectFormSeqNo という3つの新しいフォームシーケンス番号が導入されました。
PDF

PDFアーカイブのファイルの2ページ目から目次が追加されました。

Viedoc 4.39では、エクスポート出力形式について、以下のような変更がありました。。

File type Changes in the export output format
Excel FormRepeatKey.FormRepeatKey を含むフォームシーケンス番号(FormSeq)のカラムを追加する。
ODM

FormRepeatKeyにアクティビティIDが含まれるようになり、以下のフォーマットになりました。FormRepeatKey$ActivityId. ODM に ExportVersion 属性が追加されました。
PDF

サマリーフォーマットが、イベント名とフォーム名を表示するために使用されます。

Web APIクライアントのエクスポートスコープの定義

APIマネージャーとして、Web APIを通じてエクスポート可能なデータを制限するために、Web APIクライアントを設定する際にはエクスポートスコープを定義する必要があります。
これは、Web APIクライアントにロールおよびサイトを関連付けることで行います。関連付けられたロールと施設の1つでアクセス可能なデータのみが、エクスポートされるデータに含まれます。

APIエクスポートのエンドポイントは、特定のロールおよびサイトに関連付けられた場合のみアクセス可能になります。

注意！ Web APIクライアントごとに選択できる関連ロールは1つだけです。

エクスポート範囲を定義する：

1.

Web APIクライアントの追加で、Scopesフィールドにてエクスポートを選択してください

関連ロールと関連施設のドロップダウンメニューが表示されます。
2.

関連ロールと関連施設を選択します。

選択可能な関連ロールは、データエクスポート権限を持つクリニックユーザーのロールです。

選択可能なサイトは、試験デザインが割り当てられたサイトと、それに対応するサイトグループです。

注意！ Web APIクライアントの設定に準拠していないロールまたはサイトが指定されると、Web APIリクエストはエラーコードを返します。

例：Web APIクライアントの設定が次のような場合：

  • Web APIクライアントのロールが「Role 1」に設定され、関連サイトが「全ての本番サイト」に設定されている場合、リクエストで「Role 1」が指定され、サイトが指定されていない場合、そのロールとサイトでアクセス可能なデータ（返されるデータ）は「Role 1」と「全ての本番サイト」に対応するデータです。

  • Web APIクライアントの関連サイトが特定の国に設定され、関連ロールが「Role 1」に設定されている場合、特定のサイトを指定したが関連ロールが指定されていないリクエストは、そのサイトが同じ国グループ内にある限り、「Role 1」とそのサイトのデータを返します。

  • Web APIクライアントのロールが「Role 1」に設定され、関連サイトが特定のサイトに設定されている場合、リクエストで「Role 2」と同じサイトを指定した場合は、エラーコードが返されます。

  • Web APIクライアントに設定された関連サイトとは異なるサイトをリクエストすると、関連ロールが同じ場合でもエラーコードが返されます。

  • Web APIクライアントのサイトが特定の国に設定され、ロールが「Role 1」に設定されている場合、別の国にあるサイトを関連ロールなしでリクエストした場合、エラーコードが返されます。

  • Web APIクライアントのサイトが特定の国に設定され、関連ロールが「Role 1」に設定されている場合、リクエストで「Role 1」を指定し、同じ国にあるサイトと別の国にあるサイトの両方を含めてリクエストした場合も、エラーコードが返されます。

注意！

  • 試験にエクスポート範囲を持つ既存のWeb APIクライアントがある場合、APIマネージャーが「編集」を選択すると、関連ロールと関連施設のドロップダウンメニューが赤い枠で強調表示されます。有効な関連ロールと関連施設が選択されるまで、Web APIクライアントの編集内容は保存できません。
  • Web APIクライアントのロール情報（名前 / RoleID）および関連ロールへのすべての変更は、Admin監査証跡レポートに記録されます。