使用 Postman 存取 FHIR 服務
本文說明使用 Postman 存取 Azure Health Data Services 中的 FHIR® 服務的步驟。
必要條件
- 部署在 Azure 中的 FHIR 服務。 如需詳細資訊,請參閱 部署 FHIR 服務。
- 註冊的用戶端應用程式,用來存取 FHIR 服務。 如需詳細資訊,請參閱 在 Microsoft Entra ID 中註冊服務用戶端應用程式。
- 授與用戶端應用程式和用戶帳戶的 FHIR 數據參與者許可權 。
- Postman 安裝在本機。 如需詳細資訊,請參閱 開始使用Postman。
建立工作區、集合和環境
如果您不熟悉 Postman,請遵循下列步驟來建立工作區、集合和環境。
Postman 引進工作區概念,可讓您和小組共用 API、集合、環境和其他元件。 您可以使用預設的 [我的工作區] 或 [小組] 工作區,或為您或您的小組建立新的工作區。
接下來,建立新的集合,您可以在其中分組所有相關的 REST API 要求。 在工作區中,選取 [ 建立集合]。 您可以保留預設名稱 New 集合 或將其重新命名。 變更會自動儲存。
您也可以匯入和匯出 Postman 集合。 如需詳細資訊,請參閱 Postman檔。
建立或更新環境變數
雖然您可以在要求中使用完整的 URL,但建議您將 URL 和其他資料儲存在變數中。
若要存取 FHIR 服務,您必須建立或更新這些變數:
變數 | 說明 | 注意事項 |
---|---|---|
tenantid | 部署 FHIR 服務的 Azure 租使用者 | 位於應用程式註冊概觀 |
subid | 部署 FHIR 服務的 Azure 訂用帳戶 | 位於 FHIR 服務概觀 |
clientid | 應用程式客戶端註冊標識碼 | - |
clientsecret | 應用程式用戶端註冊密碼 | - |
fhirurl | FHIR 服務完整 URL (例如, https://xxx.azurehealthcareapis.com ) |
位於 FHIR 服務概觀 |
bearerToken | 將 Microsoft Entra 存取令牌儲存在腳本中 | 保留空白 |
注意
請確定您已在用戶端應用程式註冊中設定重新導向 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 身分識別平台 存取令牌。
建立新的 POST
要求:
輸入要求標頭:
https://login.microsoftonline.com/{{tenantid}}/oauth2/token
選取 [ 本文] 索引卷標,然後選取 x-www-form-urlencoded。 在索引鍵與值區段中輸入下列值:
- grant_type:
Client_Credentials
- client_id:
{{clientid}}
- client_secret:
{{clientsecret}}
- resource:
{{fhirurl}}
- grant_type:
注意
在 FHIR 服務對象參數未對應至 FHIR 服務端點 URL 的案例中,資源參數值應該對應至 FHIR 服務 驗證 窗格上的物件值。
- 選取 [ 測試] 索引標籤,然後在文字區段中輸入:
pm.environment.set("bearerToken", pm.response.json().access_token);
若要讓值可供集合使用,請使用 pm.collectionVariables.set 方法。 如需 set 方法及其範圍層級的詳細資訊,請參閱 在腳本中使用變數。 - 選取 [儲存] 以儲存設定。
- 請選取傳送。 您應該會看到具有 Microsoft Entra 存取令牌的回應,此令牌會自動儲存至變數
bearerToken
。 然後,您可以在所有 FHIR 服務 API 要求中使用。
您可以使用線上工具來檢查存取權杖,例如 https://jwt.ms。 選取 [ 宣告] 索引 標籤,以查看令牌中每個宣告的詳細描述。
使用具有授權碼授與類型的用戶帳戶
您可以使用您的 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
用戶端識別碼:應用程式用戶端註冊標識碼
用戶端密碼:應用程式用戶端註冊密碼
範圍:
{{fhirurl}}/.default
客戶端驗證:在主體中傳送客戶端認證
選擇 頁面底部的 [取得新的存取令牌 ]。
系統會要求您提供使用者認證以進行登入。
您會收到令牌。 選擇 [使用令牌]。
請確定令牌位於 REST 呼叫的授權標頭 中。
使用線上工具檢查存取權杖,例如 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}}
。 請選取傳送。 作為回應,您應該會在 FHIR 資源中看到病患清單。
建立或更新 FHIR 資源
取得 Microsoft Entra 存取令牌之後,您可以建立或更新 FHIR 數據。 例如,您可以建立新的病患或更新現有的患者。
建立新的要求,將 方法變更為 Post,然後在要求區段中輸入值。
{{fhirurl}}/Patient
選取 [持有人令牌 ] 作為授權類型。 在 [令牌] 區段中輸入 {{bearerToken}}
。 選取 [ 本文] 索引標籤。選取 原始 選項和 JSON 做為內文文字格式。 將文字複製並貼到本文區段。
{
"resourceType": "Patient",
"active": true,
"name": [
{
"use": "official",
"family": "Kirk",
"given": [
"James",
"Tiberious"
]
},
{
"use": "usual",
"given": [
"Jim"
]
}
],
"gender": "male",
"birthDate": "1960-12-25"
}
請選取傳送。 您應該會在 JSON 回應中看到新的患者。
匯出 FHIR 資料
取得 Microsoft Entra 存取令牌之後,您可以將 FHIR 數據匯出至 Azure 記憶體帳戶。
建立新的 GET
要求: {{fhirurl}}/$export?_container=export
選取 [持有人令牌 ] 作為授權類型。 在 [令牌] 區段中輸入 {{bearerToken}}
。 選取 [標頭] 以新增兩個新的標頭:
接受:
application/fhir+json
偏好:
respond-async
請選取傳送。 您應該注意到 202 Accepted
回應。 選取回應的 [標頭] 索引標籤,並記下 Content-Location 中的值。 您可以使用 值來查詢匯出作業狀態。
下一步
注意
FHIR® 是 HL7 的註冊商標,並搭配 HL7 的許可權使用。