Share via

使用 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 要求：

  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 服務 驗證 窗格上的物件值。

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

顯示 [傳送] 按鈕的螢幕快照。

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

顯示存取令牌宣告的螢幕快照。

使用具有授權碼授與類型的用戶帳戶

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

  1. 確認您是具有必要訪問許可權的 Microsoft Entra 租用戶成員。

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

    顯示回呼 URL 的螢幕快照。

  3. 在 [API 許可權] 底下的用戶端應用程式註冊中，從組織使用的 API 新增 azure Healthcare APIS 的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}} 。 選取 [ 本文] 索引標籤。選取 原始 選項和 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 中的值。 您可以使用 值來查詢匯出作業狀態。

顯示選取專案 202 已接受回應的螢幕快照。

下一步

Postman 範例查詢的入門集合

注意

FHIR® 是 HL7 的註冊商標，並搭配 HL7 的許可權使用。