Postman を使用して FHIR サービスにアクセスする

[アーティクル]
10/28/2024

この記事では、Postman を使用して Azure Health Data Services の FHIR® サービスにアクセスする手順について説明します。

前提条件

Azure にデプロイされた FHIR サービス。詳細については、「FHIR サービスを展開する」を参照してください。
Postman がローカルにインストールされています。詳細については、「Postman で開始する」を参照してください。
FHIR サービスへのロール割り当てを行うためのユーザーアクセス管理者ロール。

設定手順

Postman アプリケーションから FHIR サービスにアクセスするには、次の手順を確認します。

Microsoft Entra ID でクライアントアプリケーションを登録 (アプリ登録) する。
FHIR サービスの下で FHIR データ共同作成者ロールを割り当てる。
Postman の設定 - ワークスペース、コレクション、環境を作成する

Microsoft Entra ID でクライアントアプリケーションを登録する

Azure portal で、[Microsoft Entra ID] タイルを選択します。
[管理] セクションから [アプリの登録] を選択します。
[新しい登録] を選択します。
アプリ登録用の名前を入力します。 [サポートされているアカウントの種類] で、[この組織ディレクトリのみに含まれるアカウント] を選択します。 [登録] を選択します

アプリケーション ID (クライアント ID)

新しいアプリケーションを登録すると、[概要] セクションでアプリケーション (クライアント) ID とディレクトリ (テナント) ID を確認できるようになります。 これらの値は後で使用するので、書き留めておきます。Postman 環境を構成する際に必要になります。

認証設定: 機密かパブリックか

[認証] を選んで設定を確認します。 [パブリッククライアントフローを許可する] の既定値は [いいえ] です。
この既定値をそのままにした場合、アプリケーションの登録は機密クライアントアプリケーションになり、証明書またはシークレットが必要です。
詳細設定の [パブリッククライアントフローを許可する] オプションを既定値から [はい] に変更した場合、アプリケーションの登録はパブリッククライアントアプリケーションになり、証明書またはシークレットは必要ありません。
[はい] の値は、モバイルアプリまたはシークレットを格納したくない JavaScript アプリでクライアントアプリケーションを使う場合に便利です。
リダイレクト URL が必要なツールの場合は、[プラットフォームの追加] を選んでプラットフォームを構成します。
Postman の場合は、[モバイルアプリケーションとデスクトップアプリケーション] を選びます。 [カスタムリダイレクト URI] セクションに、「https://www.getpostman.com/oauth2/callback"」と入力します。 [構成] ボタンを選んで、設定を保存します。

証明書とシークレット

[証明書とシークレット] をクリックします。 [新しいクライアントシークレット] をクリックします。

[クライアントシークレットの追加] の [説明] フィールドにシークレットの名前を入力します。このガイダンスでは、シークレットの有効期限を 6 か月に設定します。追加をクリックします。

シークレット ID ではなく、シークレットの値を保存することが重要です。

Note

Postman や REST Client などのツールを使って FHIR サービス用のアクセストークンを取得する場合は、grant_type として client_credentials を使います。

FHIR サービスで FHIR データ共同作成者ロールを割り当てる

このセクションでは、Azure Health Data Services の FHIR® サービスに登録されたアプリケーションに FHIR データ共同作成者ロールを割り当てる手順を示します。

Azure portal で FHIR サービスに移動します。
左側のメニューで、[アクセス制御 (IAM)] ブレードを選択します。[追加] をクリックし、[ロールの割り当ての追加] を選択します。ロールの割り当てを追加するオプションが使用できない場合は、この手順を実行するためのアクセス許可を割り当ててもらうよう、Azure 管理者に依頼してください。
ロールの割り当ての [追加] の [ロール] タブで、一覧を下にスクロールし、[FHIR データ共同作成者] を選択します。続けて、 [次へ] をクリックします。
[メンバー] タブで [メンバーの選択] をクリックします。右側の [選択] フィールドに、Postman サービスクライアントアプリの名前を入力します。アプリを選びます。
同様に、[選択] にユーザー名を入力します。アプリの登録と共にリストに追加するユーザーを選択し、[選択] をクリックします。続けて、 [次へ] をクリックします。
[確認と割り当て] タブで [確認と割り当て] をクリックします。

Postman の設定 - ワークスペース、コレクション、環境を作成する。

Postman を初めて使用する場合は、次の手順に従ってワークスペース、コレクション、環境を作成します。

Postman では、自分とチームが API、コレクション、環境、およびその他のコンポーネントを共有できるようにするためのワークスペースの概念が導入されています。既定の [マイワークスペース] または [チームワークスペース] を使用するか、自分またはチーム用に新しいワークスペースを作成できます。

次に、関連するすべての REST API 要求をグループ化できる新しいコレクションを作成します。ワークスペースで [コレクションの作成] を選択します。既定の名前新しいコレクションを保持するか、名前を変更することができます。変更は自動的に保存されます。

Postman コレクションをインポートおよびエクスポートすることもできます。詳細については、Postman ドキュメントを参照してください。

環境変数を作成または更新する

要求では完全な URL を使用できますが、URL やその他のデータを変数に格納することをおすすめします。

FHIR サービスにアクセスするには、次の変数を作成または更新する必要があります。

変数	説明	ノート
tenantid	FHIR サービスがデプロイされている Azure テナント	[アプリケーションの登録の概要] にあります
subid	FHIR サービスがデプロイされている Azure サブスクリプション	[FHIR サービスの概要] にあります
clientid	アプリケーションクライアント登録 ID
clientsecret	アプリケーションクライアント登録シークレット
fhirurl	FHIR サービスの完全な URL (`https://xxx.azurehealthcareapis.com` など)	[FHIR サービスの概要] にあります
bearerToken	Microsoft Entra アクセストークンをスクリプトに格納します	空白のまま

Note

クライアントアプリケーションの登録でリダイレクト URL https://www.getpostman.com/oauth2/callback を構成したことを確認します。

機能ステートメントを取得する

GET 要求に「{{fhirurl}}/metadata」と入力した後、Send を選択します。 FHIR サービスの機能ステートメントが表示されます。

Microsoft Entra アクセストークンを取得する

サービスプリンシパルまたは Microsoft Entra ユーザーアカウントを使用して、Microsoft Entra アクセストークンを取得します。

クライアント資格情報付与タイプでサービスプリンシパルを使用する

FHIR サービスは Microsoft Entra ID によって保護されています。既定の認証を無効にすることはできません。 FHIR サービスにアクセスするには、まず Microsoft Entra アクセストークンを取得する必要があります。詳細については、「Microsoft ID プラットフォームアクセストークン」を参照してください。

新しい POST 要求を作成します:

要求ヘッダーを入力する: https://login.microsoftonline.com/{{tenantid}}/oauth2/token
[本文] タブを選択し、[x-www-form-urlencoded] を選択します。キーと値のセクションに次の値を入力します:
- grant_type: Client_Credentials
- client_id: {{clientid}}
- client_secret: {{clientsecret}}
- resource: {{fhirurl}}

Note

FHIR サービス対象ユーザーパラメーターが FHIR サービスエンドポイント URL にマップされていないシナリオでは、リソースパラメーターの値を FHIR サービス認証ペインの対象ユーザーの値にマップする必要があります。

[テスト] タブを選択し、テキストセクションに「pm.environment.set("bearerToken", pm.response.json().access_token);」と入力します。この値をコレクションで利用できるようにするには、pm.collectionVariables.set メソッドを使用します。 set メソッドとそのスコープレベルの詳細については、「スクリプトでの変数の使用」を参照してください。
[保存] を選択して設定を保存します。
[Send] を選択します。 Microsoft Entra アクセストークンを含む応答が表示され、それが変数 bearerToken に自動的に保存されるはずです。その後、すべての FHIR サービス API 要求でそれを使用できます。

アクセストークンは、https://jwt.ms などのオンラインツールを使用して調べることができます。 [要求] タブを選択すると、トークン内の各要求の詳細な説明が表示されます。

認可コード付与タイプでユーザーアカウントを使用する

Microsoft Entra アカウント資格情報を使用し、以下に示す手順に従うことで、Microsoft Entra アクセストークンを取得できます。

必要なアクセス許可を持つ Microsoft Entra テナントのメンバーであることを確認します。
クライアントアプリケーションの登録で Web プラットフォームのリダイレクト URL https://oauth.pstmn.io/v1/callback を構成したことを確認します。
クライアントアプリケーションの登録の [API アクセス許可] で、組織が使用する API から Azure Healthcare APIS に対する User_Impersonation の委任アクセス許可を追加します。

Postman で、コレクションまたは特定の REST 呼び出しの [認可] タブを選択し、[種類] で OAuth 2.0 を選択し、[新しいトークンの構成] セクションで、以下の値を設定します。
- コールバック URL: https://oauth.pstmn.io/v1/callback
- 認証 URL: https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/authorize
- アクセストークン URL: https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/token
- クライアント ID: アプリケーションクライアント登録 ID
- クライアントシークレット: アプリケーションクライアント登録シークレット
- スコープ: {{fhirurl}}/.default
- クライアント認証: 本文でクライアント資格情報を送信する

ページ下部にある [新しいアクセストークンの取得] を選択します。
サインイン用のユーザー資格情報を指定します。
トークンを受け取ったら、[トークンの使用] を選択します。
トークンが REST 呼び出しの Authorization ヘッダーにあることを確認します。

https://jwt.ms などのオンラインツールを使用してアクセストークンを調べます。 [要求] タブを選択すると、トークン内の各要求の詳細な説明が表示されます。

FHIR サーバーに接続する

Postman を開き、[ワークスペース]、[コレクション]、使用する [環境] を選択します。 [+] アイコンを選択して、新しい要求を作成します。

FHIR サービスで正常性チェックを実行するには、GET 要求に「{{fhirurl}}/health/check」と入力した後、[送信] を選択します。 Status of FHIR service - HTTP Status コード応答が 200 で、OverallStatus が正常であることが確認できるはずです。これは、正常性チェックが正常であることを意味します。

FHIR リソースを取得する

Microsoft Entra アクセストークンを取得したら、FHIR データにアクセスできます。新しい GET 要求に「{{fhirurl}}/Patient」と入力します。

認可種類として ベアラートークン を選択します。 [トークン] セクションに「{{bearerToken}}」と入力します。 [Send] を選択します。応答として、FHIR リソース内の患者の一覧が表示されます。

FHIR リソースを作成または更新する

Microsoft Entra アクセストークンを取得したら、FHIR データを作成または更新できます。たとえば、新しい患者を作成したり、既存の患者を更新したりすることができます。

新しい要求を作成し、メソッドを [ポスト] に変更し、要求セクションに値を入力します。

{{fhirurl}}/Patient

認可種類として ベアラートークン を選択します。 [トークン] セクションに「{{bearerToken}}」と入力します。 [本文] タブを選択します。raw オプションと、JSON を本文形式として選択します。次のテキストをコピーして本文セクションに貼り付けます。

{
    "resourceType": "Patient",
    "active": true,
    "name": [
        {
            "use": "official",
            "family": "Kirk",
            "given": [
                "James",
                "Tiberious"
            ]
        },
        {
            "use": "usual",
            "given": [
                "Jim"
            ]
        }
    ],
    "gender": "male",
    "birthDate": "1960-12-25"
}

[Send] を選択します。 JSON 応答に新しい患者が表示されます。

FHIR データをエクスポートする

Microsoft Entra アクセストークンを取得したら、FHIR データを Azure ストレージアカウントにエクスポートできます。

エクスポート設定を構成し、Data Lake Storage Gen2 アカウントを作成するには、「エクスポートの設定を構成する」を参照してください。

新しい GET 要求を作成します: {{fhirurl}}/$export?_container=export

認可種類として ベアラートークン を選択します。 [トークン] セクションに「{{bearerToken}}」と入力します。 [ヘッダー] を選択して、2 つの新しいヘッダーを追加します:

Accept: application/fhir+json
Prefer: respond-async

[Send] を選択します。 202 Accepted 応答が表示されるはずです。応答の [ヘッダー] タブを選択し、[コンテンツの場所] の値を書き留めます。この値を使用して、エクスポートジョブの状態のクエリを実行できます。

次のステップ

Postman サンプルクエリのスターターコレクション

Note

FHIR® は HL7 の登録商標であり、HL7 の許可を得て使用しています。

次の方法で共有

Postman を使用して FHIR サービスにアクセスする

前提条件

設定手順

Microsoft Entra ID でクライアントアプリケーションを登録する

アプリケーション ID (クライアント ID)

認証設定: 機密かパブリックか

証明書とシークレット

FHIR サービスで FHIR データ共同作成者ロールを割り当てる

Postman の設定 - ワークスペース、コレクション、環境を作成する。

環境変数を作成または更新する

機能ステートメントを取得する

Microsoft Entra アクセストークンを取得する

クライアント資格情報付与タイプでサービスプリンシパルを使用する

認可コード付与タイプでユーザーアカウントを使用する

FHIR サーバーに接続する

FHIR リソースを取得する

FHIR リソースを作成または更新する

FHIR データをエクスポートする

次のステップ

フィードバック

その他のリソース

次の方法で共有

Postman を使用して FHIR サービスにアクセスする

前提条件

設定手順

Microsoft Entra ID でクライアント アプリケーションを登録する

アプリケーション ID (クライアント ID)

認証設定: 機密かパブリックか

証明書とシークレット

FHIR サービスで FHIR データ共同作成者ロールを割り当てる

Postman の設定 - ワークスペース、コレクション、環境を作成する。

環境変数を作成または更新する

機能ステートメントを取得する

Microsoft Entra アクセス トークンを取得する

クライアント資格情報付与タイプでサービス プリンシパルを使用する

認可コード付与タイプでユーザー アカウントを使用する

FHIR サーバーに接続する

FHIR リソースを取得する

FHIR リソースを作成または更新する

FHIR データをエクスポートする

次のステップ

フィードバック

その他のリソース

Microsoft Entra ID でクライアントアプリケーションを登録する

Microsoft Entra アクセストークンを取得する

クライアント資格情報付与タイプでサービスプリンシパルを使用する

認可コード付与タイプでユーザーアカウントを使用する