使用 Postman 存取 FHIR 服務

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

必要條件

• 部署在 Azure 中的 FHIR 服務。 如需詳細資訊，請參閱部署 FHIR 服務。
• 安裝在本機的 Postman。 如需詳細資訊，請參閱開始使用 Postman。
• FHIR 服務上角色指派的使用者存取系統管理員 角色。

安裝步驟

若要從 Postman 應用程式存取 FHIR 服務，請檢閱下列步驟：

1. 在 Microsoft Entra ID 中註冊用戶端應用程式（應用程式註冊）。

2. 在 FHIR 服務下指派 FHIR 數據參與者角色。

3. 設定 Postman - 建立工作區、集合和環境

在 Microsoft Entra ID 中註冊用戶端應用程式

1. 在 Azure 入口網站 中，選取 [Microsoft [項目標識符] 圖格。

2. 選取 [管理] 區段下的 [應用程式註冊]。

3. 選取 [+ 新增註冊]。

4. 輸入應用程式註冊的名稱。 在 [支持的帳戶類型] 下，選取 [僅此組織目錄中的帳戶]。 選取 [ 註冊]。

應用程式識別碼 (用戶端識別碼)

註冊新的應用程式之後，您可以在 [概觀] 區段中找到應用程式 （用戶端） 識別碼和目錄 （租使用者） 識別碼。 請記下這些值以供日後使用，因為您在設定 Postman 環境時需要這些值。

驗證設定：機密與公用

• 選取 [驗證] 以檢閱設定。 [允許公用用戶端流程] 的預設值為 [否]。

• 如果您保留此預設值，則應用程式註冊為機密用戶端應用程式，而且需要憑證或密碼。

• 如果您在 [進階] 設定中，將 [允許公用用戶端流程] 選項的預設值變更為 [是]，則應用程式註冊是公用用戶端應用程式，而且不需要憑證或密碼。
  

• 當您想要在行動應用程式或 JavaScript 應用程式中使用用戶端應用程式且不想儲存任何密碼時，[是] 值非常有用。

• 針對需要重新導向 URL 的工具，選取 [新增平台] 以設定平台。

• 針對 Postman，選取 [行動應用程式與傳統型應用程式]。 輸入 “https://www.getpostman.com/oauth2/callback"在 [自定義重新導向 URI] 區段中。 選取 [設定] 按鈕以儲存設定。

憑證和祕密

1. 按兩下 [ 憑證和秘密]。 按兩下 [ +新增客戶端密碼]。

2. 在 [ 新增客戶端密碼] 底下 ，在 [描述 ] 欄位中輸入密碼的名稱。 指引是設定 6 個月的秘密到期時間。 按一下新增。

3. 請務必儲存 秘密值，而不是秘密標識符。

注意

嘗試使用 Postman 或 REST 用戶端等工具來取得 FHIR 服務的存取權杖時，請使用 client_credentials 的 grant_type。

在 FHIR 服務中 指派 FHIR 數據參與者角色

本節說明將 FHIR 數據參與者角色指派給 Azure Health Data Services 中 FHIR® 服務的已註冊應用程式的步驟。

1. 在 Azure 入口網站 中，流覽至您的 FHIR 服務。

2. 在左側功能表中，選取 [存取控制 （IAM） 刀鋒視窗。按兩下 [+ 新增]，然後選取 [新增角色指派]。 如果新增角色指派的選項無法使用，請要求 Azure 系統管理員指派您執行此步驟的許可權。

3. 在 [角色] 索引標籤的 [新增角色指派] 中，向下卷動清單中的 ，然後選取 [FHIR 數據參與者]。 然後按一下 [下一步]。

4. 在 [ 成員] 索引標籤下，按兩下 [ +選取成員]。 在右側的 [選取] 字段中輸入 Postman 服務用戶端應用程式的名稱。 選取 app。

5. 同樣地，在 [選取] 中輸入用戶名稱。 選取您的使用者，使其新增至清單以及應用程式註冊，然後按兩下 [ 選取]。 然後按一下 [下一步]。

6. 在 [ 檢閱 + 指派] 索引標籤下，按兩下 ， 檢閱 + 指派]。

設定 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 要求：

1. 輸入要求標頭：https://login.microsoftonline.com/{{tenantid}}/oauth2/token

2. 選取 [本文] 索引卷標，然後選取 x-www-form-urlencoded。 在索引鍵與值區段中輸入下列值：

   • grant_type：Client_Credentials
   • client_id：{{clientid}}
   • client_secret：{{clientsecret}}
   • resource：{{fhirurl}}

注意

在 FHIR 服務對象參數未對應至 FHIR 服務端點 URL 的案例中，資源參數值應該對應至 FHIR 服務 [驗證] 窗格上的對象值。

3. 選取 [測試] 索引標籤，然後在文字區段中輸入 pm.environment.set("bearerToken", pm.response.json().access_token);。 若要讓該值可供集合使用，請使用 pm.collectionVariables.set 方法。 如需 set 方法及其範圍層級的詳細資訊，請參閱在指令碼中使用變數。
4. 選取 [儲存] 以儲存設定。
5. 請選取傳送。 您應該會看到具有 Microsoft Entra 存取權杖的回應，此權杖會自動儲存到變數 bearerToken 中。 然後，您可以在所有 FHIR 服務 API 要求中使用此權杖。

您可以使用線上工具來檢查存取權杖，例如 https://jwt.ms。 選取 [宣告] 索引標籤，以查看權杖中每個宣告的詳細描述。

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

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

1. 確認您是具有必要存取權限的 Microsoft Entra 租用戶成員。

2. 請確定您已在用戶端應用程式註冊中，為 Web 平台設定重新導向 URL https://oauth.pstmn.io/v1/callback。

3. 在用戶端應用程式註冊的 [API 權限] 底下，從 [組織使用的 API] 中新增 Azure 健康資料服務的 User_Impersonation 委派權限。

4. 在 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

   • 用戶端驗證：在本文中傳送用戶端認證

5. 選擇頁面底部的 [取得新存取權杖]。

6. 提供用於登入的使用者認證。

7. 收到權杖之後，請選擇 [使用權杖]。

8. 請確定權杖位於 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 的許可下使用。