Cmdlets for FHIR

Build 24.0.9062

接続の確立

CData Cmdlets ユーザーは、データモジュールをインストールし、接続プロパティを設定してスクリプトを開始できます。このセクションでは、CSV インポートおよびエクスポートcmdlet などのネイティブPowerShell cmdlet でFHIR Cmdlets を使用する例を示します。

インストールおよび接続

PSGet がある場合は、PowerShell Gallery から次のコマンドを使ってcmdlet をインストールできます。CData サイトからセットアップを取得することもできます。 

Install-Module FHIRCmdlets

プロファイルに以下を追加すると、次のセッションでcmdlet がロードされます。 

Import-Module FHIRCmdlets;

Connect-FHIR cmdlet を使って、別のcmdlet に渡すことができる接続オブジェクトを作成します。 

$conn = Connect-FHIR -URL "http://test.fhir.org/r4b/" -ConnectionType "Generic" -ContentType "JSON" -AuthScheme "None"

FHIR への接続

Url をFHIR サーバーのService Base URL に設定します。これは接続したいFHIR サーバーでリソースが定義されているアドレスです。

汎用、Azure ベース、AWS ベース、およびGoogle ベースのFHIR サーバー実装がサポートされます。

各実装についてのサンプルUrl は以下のとおりです。

  • 汎用：http://my_fhir_server/r4b/
  • Azure：https://MY_AZURE_FHIR.azurehealthcareapis.com/
  • AWS：https://healthlake.REGION.amazonaws.com/datastore/DATASTORE_ID/r4/
  • Google：https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/

FHIR への認証

汎用FHIR インスタンス

本製品 はFHIR のカスタムインスタンスへの接続をサポートします。

カスタムFHIR サーバーへの認証はOAuth で行います。

カスタムFHIR インスタンスに接続する前に、ConnectionType をGeneric に設定する必要があります。

OAuth

AuthScheme をOAuth に設定します。

OAuth では認証するユーザーにブラウザでFHIR との通信を要求します。次のセクションで説明するとおり、本製品 はさまざまな方法でこれをサポートします。

次の手順に従う前に、サービスにOAuth アプリを登録してOAuthClientId およびOAuthClientSecret を取得する必要があります。

デスクトップアプリケーション

OAuth アクセストークンの取得およびリフレッシュ

次を設定して、接続してください。

  • OAuthClientId：アプリの登録時に割り当てられたクライアントId に設定。
  • OAuthClientSecret：アプリの登録時に割り当てられたクライアントシークレットに設定。
  • CallbackURL：アプリの登録時に定義されたリダイレクトURL に設定。例：https://localhost:3333
  • OAuthAuthorizationURL：これは、ユーザーがサービスにログインして、アプリケーションにアクセス許可を与えるURL です。
  • OAuthAccessTokenURL：これは、アクセストークンがリクエストされるURL です。
  • OAuthRefreshTokenURL：古いトークンの期限が切れたときは、このURL でリフレッシュトークンを新しいアクセストークンと交換します。データソースによっては、アクセストークンと同じURL の場合がありますので、留意してください。
接続すると、本製品 はデフォルトブラウザでFHIR のOAuth エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。 本製品 はアクセストークンの期限が切れると自動的にリフレッシュします。
ヘッドレスマシン

ヘッドレスマシンのユーザーアカウントでOAuth を使用するようにドライバーを設定するには、インターネットブラウザに対応した別の端末で認証する必要があります。

  1. 以下のオプションから選択します。
    • オプション1：後述の「Verifier code を取得および交換」に従い、OAuthVerifier 値を取得します。
    • オプション2：インターネットブラウザに対応したマシンに本製品 をインストールし、後述の「OAuth 設定を転送」の説明に従い、通常のブラウザベースのフローで認証後にOAuth 認証値を転送します。
  2. ヘッドレスマシンからアクセストークンを自動的にリフレッシュするように本製品 を設定します。

オプション1：Verifier code を取得および交換

Verifier code を取得するには、OAuth Authorization URL で認証する必要があります。

インターネットブラウザに対応したマシンから認証してOAuthVerifier 接続プロパティを取得する方法は次のとおりです。

  1. 以下のオプションから選択します。
    • 以下のプロパティを設定し、認証URL を作成します。
      • InitiateOAuth：OFF に設定。
      • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId に設定。
      • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
      適切なCallbackURL を指定してGetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。
  2. ログインして、本製品 にアクセス許可を与えます。すると、verifier code を含むリダイレクトURL にリダイレクトされます。
  3. verifier code の値を保存します。後ほどこれをOAuthVerifier 接続プロパティに設定します。
次に、OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換する必要があります。次のプロパティを設定します。

ヘッドレスマシンでは、次の接続プロパティを設定してOAuth 認証値を取得します。

  • InitiateOAuth：REFRESH に設定。
  • OAuthVerifier：verifier code に設定。
  • OAuthClientId：カスタムOAuth アプリケーション設定のクライアントId に設定。
  • OAuthClientSecret：カスタムOAuth アプリケーション設定のクライアントシークレットに設定。
  • OAuthSettingsLocation：これを設定すると、暗号化されたOAuth 認証値が指定された場所に永続化されます。

OAuth 設定ファイルが生成されたら、以下のように接続プロパティをリセットする必要があります。

  • InitiateOAuth：REFRESH に設定。
  • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId に設定。
  • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
  • OAuthSettingsLocation：暗号化されたOAuth 認証値を含む場所に設定。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。

オプション2：OAuth 設定を転送

ヘッドレスマシンでの接続に先立ち、インターネットブラウザに対応したデバイスでドライバとの接続をインストールし、作成する必要があります。上述の「デスクトップアプリケーション」の説明に従って、接続プロパティを設定します。

「デスクトップアプリケーション」の手順が完了すると、生成された認証値は、OAuthSettingsLocation で指定された場所に暗号化されて書き込まれます。デフォルトのファイル名はOAuthSettings.txt です。

接続が正常にテストされたら、OAuth 設定ファイルをヘッドレスマシンにコピーします。

ヘッドレスマシンで、次の接続プロパティを設定し、データに接続します。

  • InitiateOAuth：REFRESH に設定。
  • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId に設定。
  • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
  • OAuthSettingsLocation：OAuth 設定ファイルの場所に設定。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。

Azure FHIR インスタンス

本製品 はMicrosoft Azure がホストするFHIR インスタンスへの接続をサポートします。

Azure Active Directory、Azure サービスプリンシパル、およびAzure MSI を利用して認証できます。

Azure がホストするFHIR インスタンスに接続する前に、ConnectionType をAzure に設定する必要があります。

Azure Active Directory

Azure Active Directory に登録されたOAuth アプリを使用して、Azure がホストするFHIR インスタンスに接続できます。

AuthScheme をAzureAD に設定します。

埋め込みアプリ

CData は、OAuth デスクトップ認証を簡略化する埋め込みOAuth アプリケーションを提供します。埋め込みOAuth アプリを使用して認証する場合、ほかの接続プロパティは設定せずに接続します。

カスタムアプリ

代わりに、カスタムOAuth アプリケーションを作成することも可能です。カスタムアプリケーションの作成およびその理由については、カスタムOAuth アプリの作成 を参照してください。

OAuth アプリが作成できたら、以下を設定して接続します。

  • OAuthClientId：OAuth アプリの概要ページにある、アプリケーション（クライアント）ID に設定。
  • OAuthClientSecret：OAuth アプリの証明書とシークレットページで生成されたクライアントシークレットの値に設定。
  • AzureTenant（シングルテナントアプリのみ）：OAuth アプリの概要ページにある、ディレクトリ（テナント）ID に設定。
  • CallbackURL：カスタムOAuth アプリの作成時にリダイレクトURI に指定した値に設定。

Azure MSI

Azure VM 上でFHIR を実行している場合は、AuthScheme をAzureMSI に設定し、Managed Service Identity（MSI）の資格情報を利用して認証します。

MSI 資格情報が認証用に自動的に取得されます。

Azure サービスプリンシパル

Azure サービスプリンシパルを使用して、Azure がホストするFHIR インスタンスを認証できます。

カスタムアプリケーションの作成およびその理由については、カスタムOAuth アプリの作成 を参照してください。

OAuth アプリが作成できたら、以下を設定して接続します。

  • AuthScheme：AzureServicePrincipal に設定。
  • OAuthClientId：Azure 上のFHIR への認証に使用するOAuth アプリの概要ページにある、アプリケーション（クライアント）ID に設定。
  • OAuthClientSecret：認証するOAuth アプリの証明書とシークレットページで生成されたクライアントシークレットの値に設定。
  • CallbackURL：カスタムOAuth アプリの作成時にリダイレクトURI に指定した値に設定。
  • OAuthJWTCert：サービスプリンシパルの証明書のパスに設定。
  • OAuthJWTCertType：サービスプリンシパルの証明書のタイプに設定。

AWS FHIR インスタンス

本製品 はAWS がホストするFHIR インスタンスへの接続をサポートします。

AWS ルートキー、AWS EC2 ロール、およびAWS IAM ロールで認証できます。

AWS がホストするFHIR インスタンスに接続する前に、ConnectionType をAWS に設定する必要があります。

AWS ルートキー

AWS のルートユーザーのアクセスキーを使って認証することができます。以下を設定します。

  • AuthScheme：AwsRootKeys に設定。
  • AWSAccessKey：AWS アカウントのアクセスキーに設定。この値には、［AWS セキュリティ認証情報］ページからアクセスできます。
  • AWSSecretKey：AWS アカウントのシークレットキーに設定。この値には、［AWS セキュリティ認証情報］ページからアクセスできます。

AWS IAM ロール

IAM ロールを使用してAWS がホストするFHIR に認証するには、以下を設定します。

  • AuthScheme：AwsIAMRoles に設定。
  • AWSAccessKey：AWS アカウントのアクセスキーに設定。この値には、［AWS セキュリティ認証情報］ページからアクセスできます。
  • AWSSecretKey：AWS アカウントのシークレットキーに設定。この値には、［AWS セキュリティ認証情報］ページからアクセスできます。
  • AWSRoleARN：認証時に使用したいロールのAmazon リソースネームに設定。

AWS EC2 ロール

EC2 インスタンスから本製品 を使用していて、そのインスタンスにIAM ロールが割り当てられている場合は、 認証にIAM ロールを使用できます。

AuthScheme をAwsEC2Roles に設定します。

認証にIAM ロールも使用している場合は、さらにAWSRoleARN を認証したいロールのRole ARN に指定する必要があります。これにより、本製品 は指定されたロールの資格情報を取得しようと試みます。

Google FHIR インスタンス

本製品 はGoogle Cloud Platform がホストするFHIR インスタンスへの接続をサポートします。

標準的なOAuth またはサービスアカウント認証（JWT を使用）で認証できます。

Google Cloud Platform がホストするFHIR インスタンスに接続する前に、ConnectionType をGoogle に設定する必要があります。

OAuth

AuthScheme をOAuth に設定。

埋め込みアプリ

CData は、OAuth デスクトップ認証を簡略化する埋め込みOAuth アプリケーションを提供します。埋め込みOAuth アプリを使用して認証する場合、ほかの接続プロパティは設定せずに接続します。

カスタムアプリ

代わりに、カスタムOAuth アプリケーションを作成することも可能です。カスタムアプリケーションの作成およびその理由については、カスタムOAuth アプリの作成 を参照してください。

Generic の接続タイプとは異なり、ConnectionType をGoogle に設定した場合、OAuthAuthorizationURL、OAuthRefreshTokenURL、およびOAuthAccessTokenURL は設定する必要がありません。

Google Cloud Platform がホストするFHIR インスタンスに接続する場合、これらのプロパティは本製品 にデフォルト値が埋め込まれているためです。

これらのプロパティを省略する以外は、FHIR の汎用の実装と同じ手順でOAuth 認証を設定します（上記の「汎用FHIR インスタンス」セクションの「OAuth」セクションを参照してください）。

サービスアカウント（OAuth JWT）

サービスアカウントを使用して認証するには、新しいサービスアカウントを作成し、アカウント証明書のコピーを用意する必要があります。

Google JSON 証明書

JSON ファイルを証明書として使用したい場合は、以下のプロパティを設定する必要があります。

  • AuthScheme：OAuthJWT に設定。
  • OAuthJWTCertType：GOOGLEJSON に設定。
  • OAuthJWTCert：Google が提供する.json ファイルへのパスに設定。
  • OAuthJWTSubject（オプション）：この値は、サービスアカウントがGSuite ドメインの一部で、委任を有効にする場合にのみ設定します。このプロパティの値は、データにアクセスしたいユーザーのE メールアドレスでなければなりません。
PFX ファイル証明書

PFX ファイルを証明書として使用したい場合は、代わりに以下のプロパティを設定する必要があります。

  • AuthScheme：OAuthJWT に設定。
  • OAuthJWTCertType：PFXFILE に設定。
  • OAuthJWTCert：Google が提供する.pfx ファイルへのパスに設定。
  • OAuthJWTCertPassword（オプション）：.pfx ファイルのパスワードに設定。Google はPFX 証明書を暗号化するため、ほとんどの場合、これを設定する必要があります。
  • OAuthJWTCertSubject（オプション）：複数の証明書を格納するOAuthJWTCertType を使用している場合にのみ設定します。Google によって生成されたPFX 証明書には設定しないでください。
  • OAuthJWTIssuer：サービスアカウントのE メールアドレスに設定。このアドレスには、通常iam.gserviceaccount.com ドメインが含まれます。
  • OAuthJWTSubject（オプション）：この値は、サービスアカウントがGSuite ドメインの一部で、委任を有効にする場合にのみ設定します。このプロパティの値は、データにアクセスしたいユーザーのE メールアドレスでなければなりません。

データの取得

Select-FHIR cmdlet はデータを取得するためのネイティブなPowerShell インターフェースを提供します。 

$results = Select-FHIR -Connection $conn -Table "Patient" -Columns @("Id, [address-city]") -Where "[name-use]='Bob'"
Invoke-FHIR cmdlet はSQL インターフェースを提供します。このcmdlet を使うと、Query パラメータを介してSQL クエリを実行できます。

cmdlet 出力のパイプ処理

cmdlet は行オブジェクトをパイプラインに一度に一行ずつ返します。以下は、結果をCSV ファイルにエクスポートします。 

Select-FHIR -Connection $conn -Table Patient -Where "[name-use] = 'Bob'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myPatientData.csv -NoTypeInformation

Select-FHIR からの結果をSelect-Object cmdlet にパイプして、Export-CSV cmdlet にパイプする前にいくつかのプロパティを実行していることがわかるでしょう。これをする理由は、CData Cmdlets は接続、テーブル、およびカラムの情報を結果セットの各行オブジェクトに追加しますが、必ずしもその情報がCSV ファイルに必要ではないからです。

ただし、これによってcmdlet の出力を別のcmdlet にパイプすることが容易になります。以下に、結果セットをJSON に変換する例を示します。 

 
PS C:\> $conn  = Connect-FHIR -URL "http://test.fhir.org/r4b/" -ConnectionType "Generic" -ContentType "JSON" -AuthScheme "None"
PS C:\> $row = Select-FHIR -Connection $conn -Table "Patient" -Columns (Id, [address-city]) -Where "[name-use] = 'Bob'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "Patient",
  "Columns":  [

  ],
  "Id":  "MyId",
  "[address-city]":  "My[address-city]"
}

Copyright (c) 2024 CData Software, Inc. - All rights reserved.
Build 24.0.9062