使用 Postman 存取 FHIR 服務

文章
10/16/2024

本文將逐步說明如何使用 Postman 存取 Azure 健康資料服務中的 FHIR® 服務。

必要條件

部署在 Azure 中的 FHIR 服務。如需詳細資訊，請參閱部署 FHIR 服務。
註冊的用戶端應用程式，用來存取 FHIR 服務。如需詳細資訊，請參閱在 Microsoft Entra ID 中註冊服務用戶端應用程式。
向用戶端應用程式和您的使用者帳戶授與的 FHIR 資料參與者權限。
安裝在本機的 Postman。如需詳細資訊，請參閱開始使用 Postman。

建立工作區、集合和環境

如果您不熟悉 Postman，請遵循下列步驟來建立工作區、集合和環境。

Postman 引進工作區概念，可讓您和小組共用 API、集合、環境和其他元件。您可以使用預設的我的工作區或小組工作區，也可以為您或小組建立新的工作區。

接下來，建立新的集合，您可以在其中分組所有相關的 REST API 要求。在工作區中，選取 [建立集合]。可以保留預設名稱 [新集合]，也可以將其重新命名。變更會自動儲存。

也可以匯入和匯出 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}}

注意

在 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。選取 [宣告] 索引標籤，以查看權杖中每個宣告的詳細描述。

使用搭配授權碼授與類型的使用者帳戶

您可以使用您的 Microsoft Entra 帳戶認證並遵循列出的步驟，來取得 Microsoft Entra 存取權杖。

確認您是具有必要存取權限的 Microsoft Entra 租用戶成員。
請確定您已在用戶端應用程式註冊中，為 Web 平台設定重新導向 URL https://oauth.pstmn.io/v1/callback。
在用戶端應用程式註冊的 [API 權限] 底下，從 [組織使用的 API] 中新增 Azure 健康資料服務的 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}}。選取 [Body] $本文$ 索引標籤。選取 [raw] 選項，並選取 [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 儲存體帳戶。

若要設定匯出設定並建立 Data Lake Storage Gen2 帳戶，請參閱執行匯出設定。

建立新的 GET 要求：{{fhirurl}}/$export?_container=export

選取 [持有人權杖] 作為授權類型。在 [權杖] 區段中輸入 {{bearerToken}}。選取 [標頭] 以新增兩個新的標頭：

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

請選取傳送。您應該注意到 202 Accepted 回應。選取回應的 [標頭] 索引標籤，並記下 [Content-Location] 中的值。您可以使用此值來查詢匯出作業狀態。

下一步

Postman 範例查詢的入門集合

注意

FHIR® 是 HL7 的註冊商標，在 HL7 的許可下使用。

分享方式：