Viedoc Web API を使用したデータ出力

このレッスンでは、ViedocのWeb APIを使ってデータをエクスポートする方法を説明します。3つの例を示します： Windowsコマンドプロンプト、Python、Rです。

注意！ API設定フィールドを表示するには、API Managerロールが必要です。

API クライアント設定

重要！ データをエクスポートするには、APIクライアント設定のエクスポートスコープを有効にし、正しいステータスを選択してください。デモと本番の2つのモードがあります。

デモ - デモ/トレーニングモードで動作する施設にアクセスするために使用します。
本番 - 本番モードで動作する施設にアクセスするために使用します。

APIクライアントを作成したら、次の手順で必要になる以下の情報をメモしてください：

クライアントシークレット - トークンを取得するために必要です。ヒント！ 一度しか表示されないので、必ずコピーしてください。必要であれば、再生成することができます。
クライアントID - トークンを取得するために必要です。
トークンURL - トークンを取得するために使用します。トークンは、その後のすべてのAPIコールを認証するために必要です。
API URL - 他のすべてのAPIコールは、エンドポイントを変えながらこのベースURLに行われます。

注意！

エクスポート対象として、関連ロールと関連施設を選択する必要があります。
API経由でエクスポートする場合は、ロールIDを任意で選択できます。ロールIDを選択する場合は、Web APIクライアントのエクスポートスコープを設定する際に選択したロールと一致している必要があります。

APIクライアントの設定方法の詳細については、このリンクを選択してください： API設定。

エクスポート例

Windows コマンドプロンプト

このセクションでは、Windowsのコマンドプロンプトを使用してデータをエクスポートする手順を説明します

トークンの取得

トークンを取得するには、以下のコードを使用します:

curl -X POST -d "grant_type=client_credentials" -d "client_id=xxxx" -d "client_secret=yyyy" TokenURL

注意！ xxxx をあなたのクライアントIDに、yyyyをあなたのクライアントシークレットにき置き換えてください。TokenURLはViedoc Adminから取得します。

これはエクスポートを含むテンプレートの例です。

エクスポートプロセスの開始

To start the export process, you can use the following code as a template:
curl -X POST -H "Authorization: Bearer xxxx --json "yyyy" APIURL/clinic/dataexport/start

注意！ xxxxは、上記のステップで生成されたトークンに置き換えてください。yyyyには希望のJSONエクスポート形式を指定します。APIURLには、Viedoc Adminから取得したURLを指定します。

これはエクスポートを含むテンプレートの例です。

注意！ JSON形式でエクスポートを指定する必要があります。以下は、利用可能なエクスポートプロパティをすべて示したテンプレートです。適用されるプロパティはオプションです。エクスポート設定の詳細については、Swaggerページを参照してください。

{'roleId':'','siteIds':[],'eventDefIds':[],'formDefIds':[],'itemDefIds':[],'includeVisitDates':true, 'includeNotSigned':true,'includeSignedOnly':false,'includeSDVPerformedOrNA':true, 'includeSDVPending':true,'includeEditStatus':true,'grouping':'GroupByForm','rowLayout':'RowPerActivity', 'outputFormat':'CSV','timePeriodDateType':'EventDate','timePeriodOption':'Between','includeHistory':true, 'includeMedicalCoding':true,'includeSignatures':true,'includeReviewStatus':true,'includeSdv':false, 'includeQueries':true,'includeQueryHistory':false,'includeViedocExtensions':true,'fromDate':'','toDate':'', 'exportVersion':'','includeSubjectStatus':true,'includeBookletStatus':false,'includeBookletStatusHistory':false, 'includeSasScript':false,'includePendingForms':true}

エクスポートプロセスの確認

エクスポートプロセスを確認するには、以下のコードをテンプレートとして使用します:

curl -X GET -H "Authorization: Bearer xxxx" APIURL/clinic/dataexport/status?exportId=yyyy

Note! Replace xxxx with the token and the APIURL with the API URL obtained from Viedoc Admin. Replace yyyy with the export ID obtained in the previous step.

注意！ xxxxをトークンに、APIURLをViedoc Adminから取得したAPI URLに置き換えてください。yyyyは前のステップで取得したエクスポートIDに置き換えてください。

これはエクスポートを含むテンプレートの例です。

エクスポートのステータスがReady表示されたら、次のステップに進みます。

エクスポートをダウンロードする

エクスポートをダウンロードするには、以下のコードをテンプレートとして使用します:

curl -X GET -H "Authorization: Bearer xxxx" APIURL/clinic/dataexport/download?exportId=yyyy --output path\where\to\save\file.zip

注意！xxxxをトークンに、APIURLをViedoc Adminで取得したAPI URLに置き換えてください。yyyyはエクスポートIDに置き換えてください。最後に、ファイルを保存するパスを名前と拡張子（CSVエクスポートの場合は.zip、Excelの場合は.xlsx、XMLの場合は.xml）とともに指定する必要があります。

これはエクスポートを含むテンプレートの例です。

Python

このセクションでは、Python を使用してデータをエクスポートする手順を説明します。

注意！この例では、Python の requests パッケージを使用します。以下のコードを実行する前に、このパッケージがインストールされていることを確認してください。 requests パッケージをインストールするには、コマンドプロンプトまたはターミナルを開き、pip install requestsと入力します。

トークンの取得

このセクションでは、Pythonを使ってデータをエクスポートする手順を説明します。

import requests

						clientId = "xxxx"

						clientSecret = "xxxx"

						tokenURL = "xxxx"

						apiURL = "xxxx"

						params = {"grant type": "

client_credentials

", "client_id": clientId, "client_secret": clientSecret}

						response = requests.post(tokenURL, data = params)

						token = response.json() .get("access_token")

注意！xxxx はViedoc AdminでAPIを設定する際に取得した情報に置き換えてください。

これはPythonでトークンのリクエストをどのように構成するかの例です：

エクスポートの開始

エクスポート処理を開始するには、以下のコードをテンプレートとして使用します:

header = {"Accept": "application/json", "Authorization": "Bearer " + token} params = {

"roleId":"", "siteIds":[], "eventDefIds":[], "formDefIds":[], "itemDefIds":[], "includeVisitDates":"True", "includeNotSigned":"True", "includeSignedOnly":"False", "includeSDVPerformedOrNA":"True", "includeSDVPending":"True", "includeEditStatus":"True", "grouping":"GroupByForm", "rowLayout":"RowPerActivity", "outputFormat":"CSV", "timePeriodDateType":"EventDate", "timePeriodOption":"Between", "includeHistory":"True", "includeMedicalCoding":"True", "includeSignatures":"True", "includeReviewStatus":"True", "includeSdv":"False", "includeQueries":"True", "includeQueryHistory":"False", "includeViedocExtensions":"True", "fromDate":"", "toDate":"", "exportVersion":"", "includeSubjectStatus":"True", "includeBookletStatus":"False", "includeBookletStatusHistory":"False", "includeSasScript":"False", "includePendingForms":"True"} response = requests.post("apiURL/clinic/dataexport/start", jason=params,headers=header) exportId = response.json().get("exportId")

注意！ params 辞書はエクスポート設定を指定します。キーと値のペアはオプションです。エクスポート設定の詳細については、Swaggerページを参照してください。

これはエクスポート処理の開始例です：

エクスポートステータスの確認

エクスポートステータスをチェックするには、以下のコードをテンプレートとして使用できます。

from time import sleep while(response.json().get("progressPercent") != 100 and response.json().get("exportStatus") != "Error"): sleep(3) response = requests.get(apiURL + "/clinic/dataexport/status?exportId=" + exportId,headers=header)

注意！ 上記のコードでは、3秒ごとにエクスポート処理の完了をチェックしています。

これはエクスポートプロセスチェックの例です：

エクスポートをダウンロード

エクスポートをダウンロードするには、以下のコードをテンプレートとして使用できます。

if response.json().get("exportStatus") == "Error":

print("Export failed!")

elif response.json().get("exportStatus") == "Ready":

print("Downloading and saving the export.\\n")

response = requests.get(apiURL + "/clinic/dataexport/download?exportId=" + exportId, headers=header)

if params["outputFormat"] == "CSV":

extension = ".zip"

elif params["outputFormat"] == "Excel":

extension = ".xlsx"

with open("path/where/to/save/file" + extension, "wb") as output:

output.write(response.content)

print("Output saved: " + "path/where/to/save/file" + extension)

注意！ ファイルを保存するファイルパスとファイル名を指定する必要があります。

これはエクスポートダウンロードの例です：

R

このセクションでは、Rを使ってデータをエクスポートする方法を説明します。

注意！ この例では、Rのhttrパッケージとjsonliteパッケージを使用しています。この例のコードを実行する前に、これらをインストールする必要があります。インストールするには、Rのコンソールに (install.packages(c("httr", "jsonlite"))と入力してください。この作業は一度だけでよいです。

トークンの取得

トークンを取得するには、以下のコードをテンプレートとして使用できます:

library(httr) library(jsonlite) clientId <- "xxxx" clientSecret <- "xxxx" tokenURL <- "xxxx" apiURL <- "xxxx" params <- list("grant_type" = "client_credentials", "client_id" = clientId, "client_secret" = clientSecret) response <- POST(url = tokenURL, body = params, encode = "form") response <- fromJSON(content(response, "text")) token <- response$access_token

注意！xxxxフィールドをViedoc Adminから取得した情報に置き換えてください。

これはトークンリクエストの構成例です。

エクスポートプロセスの開始

エクスポート処理を開始するには、以下のコードをテンプレートとして使用できます:

params <- list( "roleId"="", "siteIds"=list(), "eventDefIds"=list(), "formDefIds"=list(), "itemDefIds"=list(), "includeVisitDates"="True", "includeNotSigned"="True", "includeSignedOnly"="False", "includeSDVPerformedOrNA"="True", "includeSDVPending"="True", "includeEditStatus"="True", "grouping"="GroupByForm", "rowLayout"="RowPerActivity", "outputFormat"="Excel", "timePeriodDateType"="EventDate", "timePeriodOption"="Between", "includeHistory"="True", "includeMedicalCoding"="True", "includeSignatures"="True", "includeReviewStatus"="True", "includeSdv"="False", "includeQueries"="True", "includeQueryHistory"="False", "includeViedocExtensions"="True", "fromDate"="", "toDate"="", "exportVersion"="", "includeSubjectStatus"="True", "includeBookletStatus"="False", "includeBookletStatusHistory"="False", "includeSasScript"="False", "includePendingForms"="True") response <- POST( url = paste(apiURL, "/clinic/dataexport/start", sep = ""), accept_json(), add_headers(Authorization = paste("Bearer", token, sep = " ")), body= params, encode = "json") response <- fromJSON(content(response, "text")) exportID <- response$exportId

注意！params リストはエクスポート設定を指定します。すべてのオプションを指定する必要はありません。エクスポート設定の詳細についてはSwagger ページを参照してください。

これはデータエクスポート処理の開始例です。

エクスポートステータスの確認

エクスポートステータスをチェックするには、以下のコードをテンプレートとして使用できます:

exportStatus <- 0 while(exportStatus != "Ready" && exportStatus != "Error"){ Sys.sleep(3) response <- GET( url = paste(apiURL, "/clinic/dataexport/status?exportId=", exportID, sep = ""), accept_json(), add_headers(Authorization = paste("Bearer", token, sep = " ")) response <- fromJSON(content(response, "text")) exportStatus <- response$exportStatus }

以下はエクスポート状況のスクリーンショットです。

注意！上記のコードでは、4秒ごとにエクスポート処理の完了をチェックしています。

エクスポートをダウンロード

エクスポートをダウンロードするには、以下のコードをテンプレートとして使用できます:

if(exportStatus == "Ready"){

						response <- GET(

						url= paste(apiURL, "/clinic/dataexport/download?exportId=", exportID,

						sep = ""),

						accept_json(),

						add_headers(Authorization = paste("Bearer", token, sep = " "))

						)

						writeBin(response$content, "path/where/to/save/file.extension")

						}

注意！ファイルを保存するファイルパスとファイル名を指定する必要があります。

下記はエクスポートダウンロードのスクリーンショットです。

分析

Rでデータを分析したい場合は、以下のコードをテンプレートとして使うことができます:

library(readxl)

						if(exportStatus == "Ready"){

						response <- GET(

						url = paste(apiURL, "/clinic/dataexport/download?exportId=", exportID, sep = ""),

						accept_json(),

						add_headers(Authorization = paste("Bearer", token, sep = " ")))

						tf <- tempfile()

						writeBin(response$content, tf)

						sheets <- readxl::excel_sheets(tf)

						for(i in 2:length(sheets)){

						assign(sheets[i],read_xlsx(tf,sheet=sheets[i],.name_repair = ~make.unique(.x, sep = "_")))

						}

						unlink(tf)

						}

注意！Excelでデータを分析するには、ステップ2のoutputFormatをExcelに設定する必要があります。

これは分析用にエクスポートされたデータのスクリーンショットです。