FHIR 適用的 SMART

可替代的醫療應用程式和可重複使用的技術 (SMART on FHIR) 是醫療保健標準，應用程式可以透過資料存放區來存取臨床資訊。 其會根據包括 OAuth2 和 OpenID Connect 在內的開放標準，將安全性層新增至 FHIR® 介面，以啟用與 EHR 系統的整合。 使用 SMART on FHIR 提供至少三個重要優點：

• 應用程式有已知方法可取得 FHIR 存放庫的驗證/授權。
• 使用 SMART on FHIR 存取 FHIR 存放庫的使用者受限於與使用者相關聯的資源，而非可存取存放庫中所有資料。
• 使用者可以使用 SMART 臨床範圍，將有限資料集的存取權授與應用程式。

下列教學課程說明使用 FHIR 服務啟用 FHIR 適用的 SMART 應用程式的步驟。

必要條件

• FHIR 服務的執行個體
• .NET SDK 6.0
• 啟用跨原始來源資源分享 (CORS)
• 在 Microsoft Entra ID 中註冊公用用戶端應用程式
  • 註冊應用程式之後，請記下用戶端應用程式的 applicationId。
• 請確定您可以存取 FHIR 服務的 Azure 訂用帳戶，以建立資源並新增角色指派。

使用 Azure 健康資料服務範例的 SMART on FHIR (SMART on FHIR (增強版))

步驟 1：設定 FHIR SMART 使用者角色

請遵循管理使用者：將使用者指派給角色一節中所列的步驟。 新增至此角色的任何使用者都能夠存取 FHIR 服務，前提是其要求符合 FHIR 適用的 SMART 實作指南。 授與此角色中使用者的存取權會受到與其 fhirUser 區間相關聯的資源所限制，以及受到臨床範圍所限制。

注意

SMART on FHIR 實作指南定義 FHIR 資源類型的存取權 (有不同範圍)。 這些範圍會影響應用程式對 FHIR 資源的存取。 具有 SMART 使用者角色的使用者有權在 FHIR 服務上執行讀取 API 互動。 SMART 使用者角色不會授與 FHIR 服務的寫入許可權。

步驟 2：FHIR 伺服器與範例整合

按一下此連結以瀏覽至 Azure 健康資料和 AI 範例開放原始碼解決方案。 本文件中所列的步驟可讓 FHIR 伺服器與其他 Azure 服務 (例如 APIM、Azure 函式等) 整合。

注意

這些範例是開放原始程式碼，您在使用之前應先檢閱 GitHub 上的資訊和授權條款。 其並非屬於 Azure 健康資料服務，且 Microsoft 支援服務並不支援。 這些範例會用來示範如何使用 Microsoft Entra ID 做為識別提供者工作流程，將 Azure 健康資料服務 (AHDS) 和其他開放原始碼工具一起使用，以示範適用於病患與人口服務的 §170.315(g)(10) 標準化 API 準則 (英文)。

SMART on FHIR Proxy

按一下以展開！

注意

對於使用先前所述 AHDS 樣本的 FHIR 適用的 SMART (增強版)，還有另一個選擇。 我們建議您採用 SMART on FHIR (增強版)。 FHIR 適用的 SMART Proxy 選項是舊版選項。 FHIR 適用的 SMART (增強版) 相較於 FHIR 適用的 SMART Proxy，可提供更多功能。 FHIR 適用的 SMART (增強版) 符合 FHIR 適用的 SMART 實作指南 (v 1.0.0) (英文) 和適用於病患與人口服務的 §170.315(g)(10) 標準化 API 準則 (英文) 的需求。

步驟 1：設定用戶端應用程式的管理員同意

若要使用 SMART on FHIR，您必須先驗證並授權應用程式。 第一次使用 FHIR 適用的 SMART 時，您也必須取得系統管理同意，讓應用程式存取 FHIR 資源。

如果您沒有應用程式中的擁有權角色，請連絡應用程式擁有者，並要求他們在應用程式中為您授與管理員同意。

如果您有系統管理權限，請完成下列步驟，直接向自己授與管理員同意。 (您也可以稍後於在應用程式中收到提示時，向自己授與系統管理同意。)您可以使用這些相同的步驟，將其他使用者新增為擁有者，讓他們可以檢視和編輯應用程式註冊。

若要將自己或其他使用者新增為應用程式的擁有者：

1. 在 Azure 入口網站中，移至 [Microsoft Entra ID]。
2. 在左側功能表中，選取 [應用程式註冊]。
3. 搜尋您建立的應用程式註冊，然後加以選取。
4. 在左側功能表的 [管理] 底下，選取 [擁有者]。
5. 選取 [新增擁有者]，然後新增您自己或新增您想要擁有管理員同意的使用者。
6. 選取儲存

步驟 2：啟用 SMART on FHIR Proxy

SMART on FHIR 會要求 Audience 的識別碼 URI 必須等於 FHIR 服務的 URI。 FHIR 服務的標準組態會使用 Audience 的值 https://fhir.azurehealthcareapis.com。 不過，您也可以設定符合 FHIR 服務之特定 URL 的值 (例如 https://MYFHIRAPI.fhir.azurehealthcareapis.com)。 使用 SMART on FHIR Proxy 時這是必要的。

若要在 FHIR 執行個體的 [驗證] 設定中啟用 SMART on FHIR Proxy，請選取 [SMART on FHIR Proxy] 核取方塊。

SMART on FHIR Proxy 可做為 SMART on FHIR 應用程式和 Microsoft Entra ID 之間的中繼。 驗證回覆 (驗證碼) 必須前往 SMART on FHIR Proxy，而非應用程式本身。 然後 Proxy 會將回覆轉送至應用程式。

由於驗證碼的這個兩步驟轉送，您需要將 Microsoft Entra 用戶端應用程式的回覆 URL (回呼) 設定為 URL，此 URL 是 FHIR 適用的 SMART Proxy 回覆 URL 與 FHIR 適用的 SMART 應用程式回覆 URL 的組合。 合併的回覆 URL 採用下列格式。

https://MYFHIRAPI.azurehealthcareapis.com/AadSmartOnFhirProxy/callback/aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA

在回覆中，aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA 是 FHIR 適用的 SMART 應用程式「回覆 URL」的 URL 安全、以 base64 編碼的版本。 針對 SMART on FHIR 應用程式啟動器，當應用程式在本機執行時，回覆 URL 會是 https://localhost:5001/sampleapp/index.html。

您可以使用如下列的指令碼來產生組合的回覆 URL。

$replyUrl = "https://localhost:5001/sampleapp/index.html"
$fhirServerUrl = "https://MYFHIRAPI.fhir.azurewebsites.net"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($ReplyUrl)
$encodedText = [Convert]::ToBase64String($bytes)
$encodedText = $encodedText.TrimEnd('=');
$encodedText = $encodedText.Replace('/','_');
$encodedText = $encodedText.Replace('+','-');

$newReplyUrl = $FhirServerUrl.TrimEnd('/') + "/AadSmartOnFhirProxy/callback/" + $encodedText

將回覆 URL 新增至您先前為 Microsoft Entra ID 建立的公用用戶端應用程式。

步驟 3：取得測試病患

若要測試 FHIR 服務和 SMART on FHIR Proxy，您必須在資料庫中至少有一個病患。 如果您尚未使用 API，且資料庫中沒有資料，請參閱使用 Postman 存取 FHIR 服務 (部分機器翻譯) 以載入病患。 記下特定病患的識別碼。

步驟 4：下載 SMART on FHIR 應用程式啟動器

開放原始碼的適用於 Azure 的 FHIR Server 存放庫包含簡單的 SMART on FHIR 應用程式啟動器，以及 SMART on FHIR 應用程式範例。 在本教學課程中，請在此本機使用此 FHIR 適用的 SMART 應用程式啟動器來測試設定。

您可以使用下列命令來複製 GitHub 存放庫並前往應用程式。

git clone https://github.com/Microsoft/fhir-server
cd fhir-server/samples/apps/SmartLauncher

應用程式需要幾個組態設定，您可以在 appsettings.json 中進行設定：

{
    "FhirServerUrl": "https://MYFHIRAPI.fhir.azurehealthcareapis.com",
    "ClientId": "APP-ID",
    "DefaultSmartAppUrl": "/sampleapp/launch.html"
}

建議您使用 dotnet user-secrets 功能：

dotnet user-secrets set FhirServerUrl https://MYFHIRAPI.fhir.azurehealthcareapis.com
dotnet user-secrets set ClientId <APP-ID>

使用下列命令執行應用程式：

dotnet run

步驟 5：測試 SMART on FHIR Proxy

啟動 FHIR 適用的 SMART 應用程式啟動器之後，您可以將瀏覽器指向 https://localhost:5001，您應該會在其中看到下列內容：

當您輸入 [病患]、[就診] 或 [從業人員] 資訊時，您會發現 [啟動內容] 已更新。 當您使用 FHIR 服務時，啟動內容只是一份 JSON 文件，其中包含病患、從業人員等等的相關資訊。 此啟動內容是以 base64 編碼，並傳遞至 SMART on FHIR 應用程式做為 launch 查詢參數。 根據 SMART on FHIR 規格，此變數對 SMART on FHIR 應用程式而言是不透明的，並會傳遞給識別提供者。

SMART on FHIR Proxy 會使用此資訊來填入權杖回應中的欄位。 FHIR 適用的 SMART 應用程式可以使用這些欄位來控制其要求資料的病患，以及如何在螢幕上呈現應用程式。 FHIR 適用的 SMART Proxy 支援下列欄位。

• patient
• encounter
• practitioner
• need_patient_banner
• smart_style_url

這些欄位旨在提供應用程式的指引，但不會傳達任何安全性資訊。 SMART on FHIR 應用程式可以忽略它們。

請注意，SMART on FHIR 應用程式啟動器會更新頁面底部的 [啟動 URL] 資訊。 選取 [啟動] 以啟動範例應用程式，您應該會看到類似以下的內容。

檢查權杖回應，以查看啟動內容欄位如何傳遞至應用程式。

從 SMART on FHIR Proxy 遷移至 SMART on FHIR (增強版)

重要

SMART on FHIR Proxy 將於 2026 年 9 月淘汰，屆時將轉換至 SMART on FHIR (增強版)。 從 2026 年 9 月開始，依賴 SMART on FHIR Proxy 的應用程式將會報告存取 FHIR 服務時發生錯誤。

SMART on FHIR (增強版) 相較於 SMART on FHIR Proxy，可提供更多功能。 您可以將 SMART on FHIR(Enhanced) 視為符合 SMART on FHIR 實作指南 (v 1.0.0) (英文) 和適用於病患與人口服務的 §170.315(g)(10) 標準化 API 準則 (英文) 的需求。下表列出 SMART on FHIR Proxy 與 SMART on FHIR (增強版) 之間的差異。

功能	SMART on FHIR (增強版)	Smart On FHIR Proxy
支援獨立啟動	是	No
支援 EHR 啟動	Yes	Yes
支援範圍限制	是	No
依賴第一方 Azure 產品	是，Azure API 管理 (APIM) 等 Azure 產品必須整合	No
Microsoft 支援服務	支援 FHIR 服務。需要透過 GitHub 報告和監視開放原始碼樣本支援	支援 FHIR 服務

移轉步驟

• 步驟 1：設定 FHIR SMART 使用者角色 請遵循管理使用者：將使用者指派給角色一節下所列的步驟。 新增至 SMART 角色的任何用戶都能夠存取 FHIR 服務，前提是其要求符合 SMART on FHIR 實作指南。
• 步驟 2：在 Azure 健康情況資料和 AI OSS 樣本下部署 SMART on FHIR 樣本
• 步驟 3：將 FHIR 服務 URL 的端點更新為「{{BASEURL_FROM_APIM}}/smart」。
• 步驟 4：在 FHIR 服務的 [驗證] 刀鋒視窗底下，取消核取 [SMART on FHIR Proxy] 設定。

如有任何疑問，您可以參考 Microsoft Q&A 中社群專家的解答。 如需技術支援，您也可以建立支援要求。

下一步

既然您已瞭解如何啟用 SMART on FHIR 功能，請參閱搜尋範例頁面，以瞭解如何使用搜尋參數、修飾詞和其他 FHIR 搜尋方法進行搜尋的詳細資料。

FHIR 搜尋範例

注意

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