FHIR 教育專區

FHIR 開發概述

本文引用自HL7官方資料 : https://build.fhir.org/overview-dev.html
FHIR 的預期使用範圍涵蓋人類和獸醫、臨床照護、公共衛生、臨床試驗、管理和財務方面。該標準在全球範圍內廣泛使用於各種架構和場景。
FHIR框架:
FHIR 的架構基於“資源(Resources)”。資源物件是對於醫療保健實體的實施例表示之方式。所有資源都具有以下5個共同特徵：identifier)

1.資源的識別碼(identifier) - 通常是定義資源查找位置的 URL。 2.通用元數據(Metadata)。 3.人類可讀的 XHTML 摘要。 4.一組已定義的資料元素 - 每種類型的資源都有不同的資料集(例如可以搭配TWCDI資料集)。 5.支援醫療保健變化的可擴充性框架。

此規範描述了一組資源，即一組資源類型(type)，這些資源類型描述了一組資源實例(instances)可用於資料交換。但有時「資源」這一詞，並不會具體說明是類型(type)還是實例(instances) ，透過使用的內文情境可清楚地辨明。
以下藉由JSON表示方式將患者資源(Patient Resource)做一範例說明:

資源的每個實例包括：
resourceType（第 2 行）- 必需：FHIR 定義許多不同類型的資源(如:Patient、Encouter、Medication等等)。
id（第 3 行）- 代表此資源的 ID。在交換資源時總是存在，但在創建作期間除外。
meta（第 4 - 7 行）- 通常存在：所有資源的通用/上下文資料，並由基礎設施管理。
文本（第 8 - 11 行）- 建議使用：為資源提供人類可讀表示形式的 XHTML。
擴展（第 12 - 17 行）- 選用：由擴展性框架定義的擴展。
資料（第 18 - 42 行） - 選用：資料元素，為每種類型的資源定義的不同的資料集。
請注意，雖然上述規範依照定義順序顯示JSON屬性，但仍有許多JSON庫是依據其他條件對屬性進行排序。
所有資源都可以有一個 URL，用於標識該資源並指定它曾經/可以從哪裡存取。該 URL 並不會在資源內部表示；而是在上下文使用中出現，並在製作資源副本時發生更改，或在其他部署/安全相關更改之後出現。如果透過 FHIR RESTful API 存取資源，則資源的 URL 為 [base]/[resourceType]/[id]，其中資源類型和 id 則如上述資源架構中所描述。
FHIR 提供了一個 REST API，包含豐富而簡單的操作集：

創建 = POST https://example.com/base/{resourceType} 讀取 = GET https://example.com/base/{resourceType}/{id} 更新 = PUT https://example.com/base/{resourceType}/{id} 修補 = PATCH https://example.com/base/{resourceType}/{id} 刪除 = DELETE https://example.com/base/{resourceType}/{id} 搜索 = GET https://example.com/base/{resourceType}？search 参数... 歷史記錄 = GET https://example.com/base/{resourceType}/{id}/_history 交易 = POST https://example.com/base/（將事務捆綁包 POST 到系統）操作 = GET https://example.com/base/{resourceType}/{id}/]${opname}

創建 Resource 及回應

要創建資源，需向資源類型的相應端發送 HTTP POST 請求端點。

POST https://example.com/base/{resourceType}

下面以patient創建作為說明:

1.   POST /base/Patient HTTP/1.1
2.   Authorization: Bearer 37CC0B0E-C15B-4578-9AC1-D83DCED2B2F9
3.   Accept: application/fhir+json
4.   Content-Type: application/fhir+json
5.   Content-Length: 1198
6.
7.   {
8.     "resourceType": "Patient",
9.     ...(properties)
10.  }

附註： ◆ /Patient （第 1 行） - 使用資源類型的名稱。 ◆ 授權（第 2 行）- 請參閱 FHIR 的安全性說明。 ◆ 接受，內容類型（第 3-4 行）- 以 JSON（或 application/fhir+xml 表示為 XML 版本）的所有 FHIR 資源內容類型，FHIR 資源皆以UTF-8表示。 ◆ id - 用戶端不需要為正在創建的資源提供 ID - 伺服器將分配一個 ID。如果用戶端分配了一個，伺服器仍將覆蓋它。 ◆ 資源內容，第 8+ 行 - 此時沒有 meta 屬性。資源的其餘部分與上述內容相同。

資源回應將包含 HTTP 代碼 201，用以指示已成功創建資源。

1.   HTTP/1.1 201 Created
2.   Content-Length: 161
3.   Content-Type: application/fhir+json
4.   Date: Mon, 18 Aug 2014 01:43:30 GMT
5.   ETag: W/"1"
6.   Location: http://example.com/base/Patient/f001
7.
8.   {
9.     "resourceType": "OperationOutcome",
10.   "text": {
11.      "status": "generated",
12.      "div": "<div xmlns="http://www.w3.org/1999/xhtml">The operation was successful</div>"
13.      }
14.   }

附註: ◆ HTTP/1.1 201（第 1 行），表示成功。請注意，官方強烈建議使用 HTTP v 1.1，但並非必需。 ◆ ETag（第 5 行），用於版本感知更新模式（如果伺服器支援版本控制）。 ◆ 位置（第 6 行），伺服器分配給資源的 ID。在隨後返回資源時，URL 中的 id 必須與資源中的 id 匹配。 ◆ OperationOutcome（第 9 行），此上下文中的 OperationOutcome 資源沒有 id 或 meta 元素。

讀取 Resource 請求及回應

讀取資源的內容可用 HTTP GET 指令執行:

GET https://example.com/base/{resourceType}/{id}

參考下列範例說明:

1.   GET /base/Patient/f001?_format=xml HTTP/1.1
2.   Host: example.com
3.   Accept: application/fhir+xml
4.   Cache-Control: no-cache

附註： ◆ 347（第 1 行），獲取資源的 ID。 ◆ _format=xml（第 1 行），用戶端除了使用 accept 標頭之外，標示所需回應格式的另一種方法，對於無法訪問 HTTP 標頭（例如 XSLT 轉換）的用戶端非常有用（請參閱 Mime 類型)。 ◆ 快取控制（第 4 行）。

讀取的回應: 回應包含資源內容，說明如下

1.   HTTP/1.1 200 OK
2.   Content-Length: 729
3.   Content-Type: application/fhir+xml
4.   Last-Modified: Sun, 17 Aug 2014 15:43:30 GMT
5.   ETag: W/"1"
6.
7.   <?xml version="1.0" encoding="UTF-8"?>
8.   <Patient xmlns="http://hl7.org/fhir">
9.     <id value="347"/>
10.      <meta>
11.         <versionId value="1"/>
12.         <lastUpdated value="2014-08-17T15:43:30Z"/>
14.      </meta>
15.      <!-- content as shown above for patient -->
16.   </Patient>

附註： ◆ id（第 9 行），資源的 ID，必須與讀取請求中的id匹配。 ◆ versionId（第 11 行）- 資源的當前版本 ID（如果伺服器支援版本控制）。最佳做法是此值與 ETag 匹配（請參閱版本感知更新），但客戶端絕不能假定此值。 ◆ 伺服器不需要支援版本控制，但官方強烈建議這樣做。 ◆ lastUpdated（第 12 行），如果存在，則必須與 HTTP 標頭中的值匹配。

搜尋 Resource 請求及回應

搜尋的指令除了可以獲取單個已知資源之外，還可以加入使用一組描述所欲檢索的資源集及其順序的條件。

GET https://example.com/base/{resourceType}?criteria

其中，criteria是一組 HTTP 參數，用於指定要返回的資源。

https://example.com/base/MedicationRequest?patient=347

表示傳回上述創建患者範例的所有處方資料。

搜索請求的回應是一個 Bundle：一個匹配資源的清單，其中包含一些元數據(Metadata)：

1.   HTTP/1.1 200 OK
2.   Content-Length: 14523
3.   Content-Type: application/fhir+xml
4.   Last-Modified: Sun, 17 Aug 2014 15:49:30 GMT
5.
6.   {
7.      "resourceType": "Bundle",
8.      "type": "searchset",
9.      "id" : "eceb4882-5c7e-4ca4-af62-995dfb8cef01"
10.     "timestamp": "2014-08-19T15:49:30Z",
11.     "total": "3",
12.     "link": [
13.        {
14.          "relation" : "next",
15.          "url" : "https://example.com/base/MedicationRequest?patient=347&searchId=ff15fd40-ff71-4b48-b366-09c706bed9d0&page=2"
16.         }, {
17.          "relation" : "self",
18.          "url" : "https://example.com/base/MedicationRequest?patient=347"
19.         }
20.      ],
21.      "entry": [
22.         {
23.           "resource" : {
24.              "resourceType": "MedicationRequest",
25.              "id" : "3123",
26.              "meta" : {
27.                 "versionId" : "1",
28.                 "lastUpdated" : "2014-08-16T05:31:17Z"
29.               },
30.               ... content of resource ...
31.            },
32.         },
33.         ... 2 additional resources ....
34.      ]
35.   }

附註： ◆ resourceType/type（第 7/8 行），搜尋結果始終是“searchset”類型的捆綁包。 ◆ id（第 9 行），分配給此特定捆綁包的識別碼。伺服器應為此捆綁包分配一個不會重複使用的唯一 ID。 ◆ timestamp（第 10 行），（如果伺服器支援版本控制）這應該與 HTTP 標頭匹配，並且應該是執行搜索的日期，或者更近的日期，具體取決於伺服器如何處理正在進行的更新。時間戳必須與結果中的最新資源相同或更新。 ◆ total（第 11 行），搜尋結果中的匹配項目總數。不是此特定捆綁包中的匹配項數，也可能是搜尋結果的分頁檢視。 ◆ link（第 12 行），一組命名連結，用於為此捆綁包提供相關上下文。此規範中定義的名稱：first、prev、next、last、self。 ◆ entry（第 21 行），此結果集中的實際資源。 ◆ entry.resource.id（第 25 行），請注意，在某些捆綁包中，資源類型和entry.resource.id的組合在捆綁包中必須是唯一。 ◆ 搜索操作還能夠返回其他相關資源。

更新 Resource 請求及回應

用戶端向伺服器發送新版本的資源以取代現有版本，它會將其 PUT 到現有資源的位置：

PUT https://example.com/base/{resourceType}/{id}

{id} 中不需要已經存在資源，伺服器可以選擇在指定地址自動創建資源。以下是更新患者的範例：

1.   PUT /base/Patient/f001 HTTP/1.1
2.   Host: example.com
3.   Content-Type: application/fhir+json
4.   Content-Length: 1435
5.   Accept: application/fhir+json
6.   If-Match: 1
7.
8.   {
9.      "resourceType": "Patient",
10.    "id" : "347",
11.    "meta" : {
12.       "versionId" : "1",
13.       "lastUpdated" : "2014-08-18T15:43:30Z"
14.     },
15.      ...
16.   }

附註： ◆ resourceType（第 1 行）， URL 中的“Patient”必須與資源中的資源類型匹配（第 9 行）。 ◆ 資源 ID（第 1 行，“347”），這必須與資源中的 ID（第 10 行）匹配。 ◆ If-Match（第 6 行），如果提供此項，則它必須與 meta.versionId（第 12 行）中的值匹配，並且伺服器必須檢查版本完整性，如果不支援版本，則返回 412。 ◆ meta.lastUpdated（第 13 行），此值將被忽略，並將由伺服器更新。 ◆ 資源內容（第 14 行），此處未顯示，與上述的 Patient 相同。

更新後的回應:

1.   HTTP/1.1 200 OK
2.   Content-Length: 161
3.   Content-Type: application/fhir+json
4.   Date: Mon, 18 Aug 2014 01:43:30 GMT
5.   ETag: W/"2"
6.   Location: https://example.com/base/Patient/f001/_history/2
7.
8.   {
9.      "resourceType": "OperationOutcome",
10.    "text": {
11.       "status": "generated",
12.       "div": "<div xmlns="http://www.w3.org/1999/xhtml">The operation was successful</div>"
13.      }
14.   }

附註： ◆ ETag（第 5 行），這是新版本的 versionId，也可以在位置標頭（第 6 行）中找到（如果伺服器支援版本控制）。

Resource 內容說明

範例說明:

1.   {
2.      "resourceType" : " XXX ",
3.      "id" : "12",
4.      "meta" : {
5.         "versionId" : "12",
6.         "lastUpdated" : "2014-08-18T15:43:30Z",
7.         "profile" : ["http://example-consortium.org/fhir/profile/patient"],
8.         "security" : [{
9.            "system" : "http://terminology.hl7.org/CodeSystem/v3-ActCode",
10.          "code" : "EMP"
11.       }],
12.      "tag" : [{
13.         "system" : "http://example.com/codes/workflow",
14.         "code" : "needs-review"
15.         }]
16.      },
17.      "implicitRules" : "http://example-consortium.org/fhir/ehr-plugins",
18.      "language" : "X"
19.   }

附註: ◆ resourceType（第 2 行），每個資源物件必填的欄位。在 XML 中，即是資源的根元素名稱。 ◆ id（第 3 行），在創建資源時定義，並且不再更改。 ◆ meta.versionId（第 5 行），每次更改任何資源內容時都會變更（meta - 中的最後 3 個元素除外:profile、security、tag)。 ◆ meta.lastUpdated（第 6 行），當 versionId 更改時同步變更；不支援版本的系統通常也不會追蹤 lastUpdated。 ◆ meta.profile（第 7 行），內容符合配置檔的宣告。有關進一步討論，請參閱擴展和限制資源。可隨著配置檔和值集的更改或系統重新檢查一致性而更改。 ◆ meta.security（第 8 - 11 行），應用於此資源的安全標籤。這些標籤以特定方式將資源連接到整體安全策略和基礎設施。當資源發生更改時，或者每當安全子系統選擇更新時，都可以更新安全標籤。 ◆ meta.tag（第 12 - 16 行），應用於此資源的標記。標記用於將資源與流程和工作流相關聯；應用程式在解釋資源的含義時不需要考慮標記。 ◆ implicitRules（第 17 行），指示存在有關如何使用資源的自定義協定，必須瞭解該協定才能安全地處理資源。官方不建議使用，因為它會限制共用。 ◆ language（第 18 行），資源的基本語言。允許資源包含來自其他語言的內容。

Resource 之 Profile 與繼承

以Patient Resource 為範例說明:

FHIR 原生資源物件對於 identifier 之定義為病患之識別碼，此欄位為選填，最多並無限制。 TW Core IG 的 Patient 中，約束此欄位設定為必填(最多無限制)，並可用身分證、護照、居留證號或病歷號作為識別碼。形成此資源之設定檔(Profile)。

TWPAS IG 的 Patient，繼承 TW Core IG Patient 的設定檔並因應實作需求，限縮病患識別碼的填入為最多兩個。

(圖片來源：工研院整理製作)

Resource 的結構說明 (以Patient Resource 為例)

如何閱讀資源物件的結構

資源物件的資料表由 Name、Flags、Cardinarity、Type 及 Description&Constraints 所組成。

Nmae 表示該欄位名稱，若使用 Slices，則表示該欄位具有多種表示方式。例如，病患的識別碼可以使用身分證號碼、病歷號碼或是護照號碼等等。

Flags 若標示 s，則表示此欄位 FHIR Server 必須支援且能夠儲存；若出現c，則為上傳時受限制的項目，例如:身分證字號須為10碼，且第1碼為英文，2~10碼為數字。

Cardinarity 說明此欄位為選填(0 )或必填( 1 … * )，以及必填時數量是否限制( 1 … * )。

(圖片來源：工研院整理製作)

專門術語與值集綁定

為什麼需要術語 :

術語(terminology)在醫療健康領域中的應用佔有重要的地位，因為它對於記錄、共享和分析健康資料提供一致、標準化的語言(描述方式)。如果沒有標準化的術語，醫療保健提供者之間的溝通、資料互通性和患者照護品質可能會因為資料解釋中的誤解和不一致而受到影響。

FHIR中的術語模組用於標準化和管理 FHIR 框架內與醫療健康相關的術語和詞彙。它包括CodeSystem、ValueSet和ConceptMap等資源，支援各種標準化程式碼和分類的表示，確保跨系統資料的一致解釋。

本範例以健保醫療服務給付項目-檢驗相關代碼進行說明，應用於Observation.code之欄位。此欄位cardinarity為1，表示為必填，綁定程度extensible為鼓勵使用值集中的代碼(LOINC)，但不強制。因此在擴充資料項目中可選擇綁定LOINC或是臺灣健保署醫療服務給付項目-檢驗值集。展開coding:TWlaboratoryCategory，即可針對所選用的值集填入對應的Code、System及Display如圖示中之範例。

(圖片來源：工研院整理製作)

安裝 HAPI FHIR Server

工具介紹 :

HAPI FHIR 是由Smile Digital Health公司來進行維護的一個Open Source的 FHIR (Fast Healthcare Interoperability Resources) 伺服器，它支持HL7（Health Level 7）所定義之所有FHIR資源類型和RESTful API規範，並且提供支援FHIR版本切換、資源驗證、資料匯出、進階查詢與訂閱等功能，此外，也支援實作指引（Implementation Guide）之導入。 HAPI FHIR提供了許多線上參考資源，其中該組織也提供了測試伺服器供測試(https://hapi.fhir.org/)，並且支援多版本的測試，包含R5、R4、R4B...等。

(圖片來源：工研院整理製作)

以下介紹關於FHIR頁面上的一些基本元素與說明，由上到下、由左到右依序為，Options、Resource、Introduction與Server Actions：

(圖片來源：工研院整理製作)

1. Options：可設定搜尋參數調整，其中Encoding預設輸出為JSON，也可以透過該頁面改設定成XML；Pretty預設為On，這個參數可以調整JSON輸出內容是否要排版呈現，以方便使用者觀看其輸出資料；Summary主要是用來整理查詢輸出的結果，以設定「count」為例，只輸出這個查詢範圍內的總筆數，不額外輸出其細節，設定「data」其表示移除Text欄位後將其他內容輸出等。 2. Resource：該列表呈現資料庫內所記錄的所有Resource並按照資料筆數多寡進行排序。 3. Introduction：該欄位為本系統服務之說明，並提供HAPI版本號(7.0.2)、所使用之FHIR(R4)與FHIR Base之 Url位置。 4. Server Action：有三個選項：分別是Conformance、History與Transaction；Conformance其顯示本服務所描述之一致性說明、History則可以顯示近期更新到Server內的資料，最後Transaction則是可以上傳多個資源資料(Bubdle)的一個匯入接口。

當在Resource列表之中，任點一種Resource後，可以在該Resource內操作所有CRUD等基本操作以及進階搜尋功能，如下圖示：

(圖片來源：工研院整理製作)

(圖片來源：工研院整理製作)

安裝說明:

本安裝使用hapi-fhir 所提供之Github版本

1. Prerequisites (先決條件)

1) Ubuntu 20.04 以上 2) git (參考安裝手冊：https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) 3) docker & docker compose (參考安裝手冊：https://docs.docker.com/engine/install/ubuntu/)

2. Installation methods (安裝方法)

至HAPI github下載該服務，並修改與安裝

• Clone HAPI Project

git clone -b image/v7.0.3 https://github.com/hapifhir/hapi-fhir-jpaserver-starter.git

資料庫從H2改成Postgres DB (必要)

• 開啟Application.yaml檔案

cd hapi-fhir-jpaserver-starter
vim src/main/resource/Application.yaml

• 將H2換成Postgres之配置如下：

# src/main/resource/Application.yaml
# 修改前
datasource:
   #url: 'jdbc:h2:file:./target/database/h2'
   url: jdbc:h2:mem:test_mem
   username: sa
   password: null
   driverClassName: org.h2.Driver
   # max-active: 15

   # database connection pool size
   hikari:
      maximum-pool-size: 10
# 修改後
datasource:
   #url: 'jdbc:h2:file:./target/database/h2'
   # url: jdbc:h2:mem:test_mem
   # username: sa
   # password: null
   # driverClassName: org.h2.Driver
   url: 'jdbc:postgresql://hapi-fhir-postgres:5432/hapi'
   username: admin
   password: admin
   driverClassName: org.postgresql.Driver
   # max-active: 15

   # database connection pool size
   hikari:
      maximum-pool-size: 10

• 將H2 dialect 換成Postgres dialect之配置如下：

# src/main/resource/Application.yaml
# 修改前
jpa:
   properties:
      hibernate.format_sql: false
      hibernate.show_sql: false

      #Hibernate dialect is automatically detected except Postgres and H2.
      #If using H2, then supply the value of ca.uhn.fhir.jpa.model.dialect.HapiFhirH2Dialect
      #If using postgres, then supply the value of ca.uhn.fhir.jpa.model.dialect.HapiFhirPostgres94Dialect
      hibernate.dialect: ca.uhn.fhir.jpa.model.dialect.HapiFhirH2Dialect
# 修改後
jpa:
   properties:
      hibernate.format_sql: false
      hibernate.show_sql: false

      #Hibernate dialect is automatically detected except Postgres and H2.
      #If using H2, then supply the value of ca.uhn.fhir.jpa.model.dialect.HapiFhirH2Dialect
      #If using postgres, then supply the value of ca.uhn.fhir.jpa.model.dialect.HapiFhirPostgres94Dialect
      #hibernate.dialect: ca.uhn.fhir.jpa.model.dialect.HapiFhirH2Dialect
      hibernate.dialect: ca.uhn.fhir.jpa.model.dialect.HapiFhirPostgres94Dialect

• 參考修改後程式畫面如下：

開啟FHIR API對外 (可選)

• 開啟Application.yaml檔案

cd hapi-fhir-jpaserver-starter
vim src/main/resource/Application.yaml

• 修改hapi設定(添加 server address)

# src/main/resource/Application.yaml
# 修改前
hapi:
   fhir:
      ### This is the FHIR version. Choose between, DSTU2, DSTU3, R4 or R5
      fhir_version: R4
      ### Flag is false by default. This flag enables runtime installation of IG's.
      ig_runtime_upload_enabled: false
      ### enable to set the Server URL
      # server_address: http://hapi.fhir.org/baseR4
      # defer_indexing_for_codesystems_of_size: 101
      # install_transitive_ig_dependencies: true
# 修改後
hapi:
   fhir:
      ### This is the FHIR version. Choose between, DSTU2, DSTU3, R4 or R5
      fhir_version: R4
      ### Flag is false by default. This flag enables runtime installation of IG's.
      ig_runtime_upload_enabled: false
      ### enable to set the Server URL
      # server_address: http://hapi.fhir.org/baseR4
      # defer_indexing_for_codesystems_of_size: 101
      # install_transitive_ig_dependencies: true
      server_address: http://140.96.100.3:8080/fhir
      defer_indexing_for_codesystems_of_size: 101

• 修改hapi設定(修改 Local Tester server address)

# src/main/resource/Application.yaml
# 修改前
hapi:
   fhir:
      tester:
         home: Local Tester
         server_address: 'http://localhost:8080/fhir'
         refuse_to_fetch_third_party_urls: false
         fhir_version: R4
# 修改後
hapi:
   fhir:
      tester:
         home: Local Tester
         server_address: 'http://140.96.100.3:8080/fhir'
         refuse_to_fetch_third_party_urls: false
         fhir_version: R4

載入TW Core IG與開啟驗證 (可選):

• 開啟Application.yaml檔案

cd hapi-fhir-jpaserver-starter
vim src/main/resource/Application.yaml

• 修改hapi設定，添加TW Core IG package

# src/main/resource/Application.yaml
# 添加如下
hapi:
   fhir:
      install_transitive_ig_dependencies: true
      implementationguides:
      twcore:
         name: tw.gov.mohw.twcore
         version: 0.3.1
         packageUrl: 'https://twcore.mohw.gov.tw/ig/twcore/0.3.1/package.tgz'

• 修改hapi設定，開啟驗證，預設皆為false，可任一選擇開啟

# src/main/resource/Application.yaml
# 添加如下
hapi:
   fhir:
      validation:
         requests_enabled: true
         responses_enabled: false

設定DB可外部存取查看(可選):

• 修改docker-compose配置

# docker-compose.yaml
version: "3"
services:
   hapi-fhir-jpaserver-start:
   build: .
      container_name: hapi-fhir-jpaserver-start
      restart: on-failure
      ports:
         - "8080:8080"
   hapi-fhir-postgres:
      image: postgres:13-alpine
      container_name: hapi-fhir-postgres
      restart: always
      environment:
         POSTGRES_DB: "hapi"
         POSTGRES_USER: "admin"
         POSTGRES_PASSWORD: "admin"
      # 新增對外ports
      ports:
         - "5432:5432"
      volumes:
         - hapi-fhir-postgres:/var/lib/postgresql/data
      volumes:
         hapi-fhir-postgres:

3. 啟動服務、關閉服務與修改建置之指令

• 執行執行HAPI Server Docker Compose

cd hapi-fhir-jpaserver-starter
# 啟動服務
docker compose up
# 關閉並刪除服務
docker compose down
# 修改 application.yaml後，需重新建置
docker compose build hapi-fhir-jpaserver-start

如何建立一個實作指引(IG)

1.環境建置:

Clone your IG repository

$ git clone https://github.com/ITRI-BDL-D/MOHW-Sample-IG.git
$ cd MOHW-Sample-IG

安裝 JAVA

在建置 IG 之前，您需要安裝 Java Development Kit (JDK)。前往 https://adoptopenjdk.net/ 下載適用於您平台的最新（版本 8 或更高版本）JDK 並安裝它。

安裝 Ruby 及 Jekyll

Ruby Jekyll 需要 Ruby 2.7.0 或更高版本。如果您需要較新版本，請前往 https://www.ruby-lang.org/en/downloads/ 尋找說明。

Jekyll 前往 https://jekyllrb.com 並按照那裡的說明進行操作。

gem install jekyll bundler

測試是否安裝成功

jekyll -v

安裝 SUSHI

安裝 Node.js 安裝SUSHI

npm install -g fsh-sushi
sushi help

2.撰寫 FHIR Shorthand:

什麼是 FHIR Shorthand?

FHIR Shorthand（FSH）是一種為了簡化HL7 FHIR實作指南（Implementation Guide, IG）和FHIR資源定義而設計的域特定語言。它允許用戶以簡潔易懂的方式定義FHIR相關的工件，包括Profile、Extension、ValueSet等。

(圖片來源：https://build.fhir.org/ig/HL7/fhir-shorthand/index.html)

轉換工具: FSH ONLINE (https://fshonline.fshschool.org/) 、GoFSH (https://github.com/FHIR/GoFSH)。

Build

sushi

3.Local Build

更新 Publisher.jar

./_updatePublisher.sh

更新publication-request.json

Build

./_genonce.sh

開啟output/index.html

(圖片來源：工研院整理製作)

QA Report – 請檢查並修復錯誤

4.Publish

Fork FHIR IG registry Clone the HL7 history, web templates, and FHIR IG registry repositories.

$ git clone git@github.com:HL7/fhir-ig-history-template.git ig-history
$ git clone git@github.com:HL7/fhir-web-templates.git fhir-web-templates
$ git clone git@github.com:FHIR/ig-registry.git ig-registry

建立 “publication”資料夾建立 publication 資源

$ cd publication
$ mkdir templates webroot
$ cp ../fhir-web-templates/*template* templates

Run the IG Publisher in "publish" mode:

$ cd ~/src/publication
$ java -jar ../publisher.jar -go-publish     -source    /home/username/src/my-ig     -web       /home/username/src/publication/webroot     -history   /home/username/src/ig-history     -registry  /home/username/src/ig-registry/fhir-ig-list.json     -temp      /home/username/src/publication/temp     -templates /home/username/src/publication/templates

source - 要發布的實作指南 web - 生成檔案將儲存於此目錄 history - 歷史版本的來源目錄 registry - 要更新的實作指南登錄清單檔案，包含此次發布的資訊 temp - 暫存位置 templates - 用於生成歷史記錄等的自定義檔案

FHIR 課程

4. 臺灣核心互通資料群：TW CDI

衛生福利部資訊處技監兼處長

李建璋

2. FHIR 統一資料

衛生福利部資訊處技監兼處長

李建璋

1. 統一臺灣電子病歷的策略思考

衛生福利部資訊處技監兼處長

李建璋

3. 臺灣醫中電子病歷資料統一的架構

衛生福利部資訊處技監兼處長

李建璋

臺灣醫療資訊標準大平台

FHIR 教育專區

首頁

什麼是 FHIR

FHIR 教育專區

FHIR 開發概述

創建 Resource 及回應

要創建資源，需向資源類型的相應端發送 HTTP POST 請求端點。

POST https://example.com/base/{resourceType}

下面以patient創建作為說明:

1.   POST /base/Patient HTTP/1.1
2.   Authorization: Bearer 37CC0B0E-C15B-4578-9AC1-D83DCED2B2F9
3.   Accept: application/fhir+json
4.   Content-Type: application/fhir+json
5.   Content-Length: 1198
6.
7.   {
8.     "resourceType": "Patient",
9.     ...(properties)
10.  }

資源回應將包含 HTTP 代碼 201，用以指示已成功創建資源。

1.   HTTP/1.1 201 Created
2.   Content-Length: 161
3.   Content-Type: application/fhir+json
4.   Date: Mon, 18 Aug 2014 01:43:30 GMT
5.   ETag: W/"1"
6.   Location: http://example.com/base/Patient/f001
7.
8.   {
9.     "resourceType": "OperationOutcome",
10.   "text": {
11.      "status": "generated",
12.      "div": "<div xmlns="http://www.w3.org/1999/xhtml">The operation was successful</div>"
13.      }
14.   }

讀取 Resource 請求及回應

讀取資源的內容可用 HTTP GET 指令執行:

GET https://example.com/base/{resourceType}/{id}

參考下列範例說明:

1.   GET /base/Patient/f001?_format=xml HTTP/1.1
2.   Host: example.com
3.   Accept: application/fhir+xml
4.   Cache-Control: no-cache

讀取的回應: 回應包含資源內容，說明如下

1.   HTTP/1.1 200 OK
2.   Content-Length: 729
3.   Content-Type: application/fhir+xml
4.   Last-Modified: Sun, 17 Aug 2014 15:43:30 GMT
5.   ETag: W/"1"
6.
7.   <?xml version="1.0" encoding="UTF-8"?>
8.   <Patient xmlns="http://hl7.org/fhir">
9.     <id value="347"/>
10.      <meta>
11.         <versionId value="1"/>
12.         <lastUpdated value="2014-08-17T15:43:30Z"/>
14.      </meta>
15.      <!-- content as shown above for patient -->
16.   </Patient>

搜尋 Resource 請求及回應

搜尋的指令除了可以獲取單個已知資源之外，還可以加入使用一組描述所欲檢索的資源集及其順序的條件。

GET https://example.com/base/{resourceType}?criteria

其中，criteria是一組 HTTP 參數，用於指定要返回的資源。

https://example.com/base/MedicationRequest?patient=347

表示傳回上述創建患者範例的所有處方資料。

搜索請求的回應是一個 Bundle：一個匹配資源的清單，其中包含一些元數據(Metadata)：

1.   HTTP/1.1 200 OK
2.   Content-Length: 14523
3.   Content-Type: application/fhir+xml
4.   Last-Modified: Sun, 17 Aug 2014 15:49:30 GMT
5.
6.   {
7.      "resourceType": "Bundle",
8.      "type": "searchset",
9.      "id" : "eceb4882-5c7e-4ca4-af62-995dfb8cef01"
10.     "timestamp": "2014-08-19T15:49:30Z",
11.     "total": "3",
12.     "link": [
13.        {
14.          "relation" : "next",
15.          "url" : "https://example.com/base/MedicationRequest?patient=347&searchId=ff15fd40-ff71-4b48-b366-09c706bed9d0&page=2"
16.         }, {
17.          "relation" : "self",
18.          "url" : "https://example.com/base/MedicationRequest?patient=347"
19.         }
20.      ],
21.      "entry": [
22.         {
23.           "resource" : {
24.              "resourceType": "MedicationRequest",
25.              "id" : "3123",
26.              "meta" : {
27.                 "versionId" : "1",
28.                 "lastUpdated" : "2014-08-16T05:31:17Z"
29.               },
30.               ... content of resource ...
31.            },
32.         },
33.         ... 2 additional resources ....
34.      ]
35.   }

更新 Resource 請求及回應

用戶端向伺服器發送新版本的資源以取代現有版本，它會將其 PUT 到現有資源的位置：

PUT https://example.com/base/{resourceType}/{id}

{id} 中不需要已經存在資源，伺服器可以選擇在指定地址自動創建資源。以下是更新患者的範例：

1.   PUT /base/Patient/f001 HTTP/1.1
2.   Host: example.com
3.   Content-Type: application/fhir+json
4.   Content-Length: 1435
5.   Accept: application/fhir+json
6.   If-Match: 1
7.
8.   {
9.      "resourceType": "Patient",
10.    "id" : "347",
11.    "meta" : {
12.       "versionId" : "1",
13.       "lastUpdated" : "2014-08-18T15:43:30Z"
14.     },
15.      ...
16.   }

更新後的回應:

1.   HTTP/1.1 200 OK
2.   Content-Length: 161
3.   Content-Type: application/fhir+json
4.   Date: Mon, 18 Aug 2014 01:43:30 GMT
5.   ETag: W/"2"
6.   Location: https://example.com/base/Patient/f001/_history/2
7.
8.   {
9.      "resourceType": "OperationOutcome",
10.    "text": {
11.       "status": "generated",
12.       "div": "<div xmlns="http://www.w3.org/1999/xhtml">The operation was successful</div>"
13.      }
14.   }

附註： ◆ ETag（第 5 行），這是新版本的 versionId，也可以在位置標頭（第 6 行）中找到（如果伺服器支援版本控制）。

Resource 內容說明

範例說明:

1.   {
2.      "resourceType" : " XXX ",
3.      "id" : "12",
4.      "meta" : {
5.         "versionId" : "12",
6.         "lastUpdated" : "2014-08-18T15:43:30Z",
7.         "profile" : ["http://example-consortium.org/fhir/profile/patient"],
8.         "security" : [{
9.            "system" : "http://terminology.hl7.org/CodeSystem/v3-ActCode",
10.          "code" : "EMP"
11.       }],
12.      "tag" : [{
13.         "system" : "http://example.com/codes/workflow",
14.         "code" : "needs-review"
15.         }]
16.      },
17.      "implicitRules" : "http://example-consortium.org/fhir/ehr-plugins",
18.      "language" : "X"
19.   }

Resource 之 Profile 與繼承

以Patient Resource 為範例說明:

TWPAS IG 的 Patient，繼承 TW Core IG Patient 的設定檔並因應實作需求，限縮病患識別碼的填入為最多兩個。

(圖片來源：工研院整理製作)

Resource 的結構說明 (以Patient Resource 為例)

如何閱讀資源物件的結構

資源物件的資料表由 Name、Flags、Cardinarity、Type 及 Description&Constraints 所組成。

Nmae 表示該欄位名稱，若使用 Slices，則表示該欄位具有多種表示方式。例如，病患的識別碼可以使用身分證號碼、病歷號碼或是護照號碼等等。

Cardinarity 說明此欄位為選填(0 )或必填( 1 … * )，以及必填時數量是否限制( 1 … * )。

(圖片來源：工研院整理製作)

專門術語與值集綁定

為什麼需要術語 :

(圖片來源：工研院整理製作)

安裝 HAPI FHIR Server

工具介紹 :

(圖片來源：工研院整理製作)

以下介紹關於FHIR頁面上的一些基本元素與說明，由上到下、由左到右依序為，Options、Resource、Introduction與Server Actions：

(圖片來源：工研院整理製作)

當在Resource列表之中，任點一種Resource後，可以在該Resource內操作所有CRUD等基本操作以及進階搜尋功能，如下圖示：

(圖片來源：工研院整理製作)

安裝說明:

本安裝使用hapi-fhir 所提供之Github版本

1. Prerequisites (先決條件)

2. Installation methods (安裝方法)

至HAPI github下載該服務，並修改與安裝

• Clone HAPI Project

git clone -b image/v7.0.3 https://github.com/hapifhir/hapi-fhir-jpaserver-starter.git

資料庫從H2改成Postgres DB (必要)

• 開啟Application.yaml檔案

cd hapi-fhir-jpaserver-starter
vim src/main/resource/Application.yaml

• 將H2換成Postgres之配置如下：

# src/main/resource/Application.yaml
# 修改前
datasource:
   #url: 'jdbc:h2:file:./target/database/h2'
   url: jdbc:h2:mem:test_mem
   username: sa
   password: null
   driverClassName: org.h2.Driver
   # max-active: 15

   # database connection pool size
   hikari:
      maximum-pool-size: 10
# 修改後
datasource:
   #url: 'jdbc:h2:file:./target/database/h2'
   # url: jdbc:h2:mem:test_mem
   # username: sa
   # password: null
   # driverClassName: org.h2.Driver
   url: 'jdbc:postgresql://hapi-fhir-postgres:5432/hapi'
   username: admin
   password: admin
   driverClassName: org.postgresql.Driver
   # max-active: 15

   # database connection pool size
   hikari:
      maximum-pool-size: 10

• 將H2 dialect 換成Postgres dialect之配置如下：

# src/main/resource/Application.yaml
# 修改前
jpa:
   properties:
      hibernate.format_sql: false
      hibernate.show_sql: false

      #Hibernate dialect is automatically detected except Postgres and H2.
      #If using H2, then supply the value of ca.uhn.fhir.jpa.model.dialect.HapiFhirH2Dialect
      #If using postgres, then supply the value of ca.uhn.fhir.jpa.model.dialect.HapiFhirPostgres94Dialect
      hibernate.dialect: ca.uhn.fhir.jpa.model.dialect.HapiFhirH2Dialect
# 修改後
jpa:
   properties:
      hibernate.format_sql: false
      hibernate.show_sql: false

      #Hibernate dialect is automatically detected except Postgres and H2.
      #If using H2, then supply the value of ca.uhn.fhir.jpa.model.dialect.HapiFhirH2Dialect
      #If using postgres, then supply the value of ca.uhn.fhir.jpa.model.dialect.HapiFhirPostgres94Dialect
      #hibernate.dialect: ca.uhn.fhir.jpa.model.dialect.HapiFhirH2Dialect
      hibernate.dialect: ca.uhn.fhir.jpa.model.dialect.HapiFhirPostgres94Dialect

• 參考修改後程式畫面如下：

開啟FHIR API對外 (可選)

• 開啟Application.yaml檔案

cd hapi-fhir-jpaserver-starter
vim src/main/resource/Application.yaml

• 修改hapi設定(添加 server address)

# src/main/resource/Application.yaml
# 修改前
hapi:
   fhir:
      ### This is the FHIR version. Choose between, DSTU2, DSTU3, R4 or R5
      fhir_version: R4
      ### Flag is false by default. This flag enables runtime installation of IG's.
      ig_runtime_upload_enabled: false
      ### enable to set the Server URL
      # server_address: http://hapi.fhir.org/baseR4
      # defer_indexing_for_codesystems_of_size: 101
      # install_transitive_ig_dependencies: true
# 修改後
hapi:
   fhir:
      ### This is the FHIR version. Choose between, DSTU2, DSTU3, R4 or R5
      fhir_version: R4
      ### Flag is false by default. This flag enables runtime installation of IG's.
      ig_runtime_upload_enabled: false
      ### enable to set the Server URL
      # server_address: http://hapi.fhir.org/baseR4
      # defer_indexing_for_codesystems_of_size: 101
      # install_transitive_ig_dependencies: true
      server_address: http://140.96.100.3:8080/fhir
      defer_indexing_for_codesystems_of_size: 101

• 修改hapi設定(修改 Local Tester server address)

# src/main/resource/Application.yaml
# 修改前
hapi:
   fhir:
      tester:
         home: Local Tester
         server_address: 'http://localhost:8080/fhir'
         refuse_to_fetch_third_party_urls: false
         fhir_version: R4
# 修改後
hapi:
   fhir:
      tester:
         home: Local Tester
         server_address: 'http://140.96.100.3:8080/fhir'
         refuse_to_fetch_third_party_urls: false
         fhir_version: R4

載入TW Core IG與開啟驗證 (可選):

• 開啟Application.yaml檔案

cd hapi-fhir-jpaserver-starter
vim src/main/resource/Application.yaml

• 修改hapi設定，添加TW Core IG package

# src/main/resource/Application.yaml
# 添加如下
hapi:
   fhir:
      install_transitive_ig_dependencies: true
      implementationguides:
      twcore:
         name: tw.gov.mohw.twcore
         version: 0.3.1
         packageUrl: 'https://twcore.mohw.gov.tw/ig/twcore/0.3.1/package.tgz'

• 修改hapi設定，開啟驗證，預設皆為false，可任一選擇開啟

# src/main/resource/Application.yaml
# 添加如下
hapi:
   fhir:
      validation:
         requests_enabled: true
         responses_enabled: false

設定DB可外部存取查看(可選):

• 修改docker-compose配置

# docker-compose.yaml
version: "3"
services:
   hapi-fhir-jpaserver-start:
   build: .
      container_name: hapi-fhir-jpaserver-start
      restart: on-failure
      ports:
         - "8080:8080"
   hapi-fhir-postgres:
      image: postgres:13-alpine
      container_name: hapi-fhir-postgres
      restart: always
      environment:
         POSTGRES_DB: "hapi"
         POSTGRES_USER: "admin"
         POSTGRES_PASSWORD: "admin"
      # 新增對外ports
      ports:
         - "5432:5432"
      volumes:
         - hapi-fhir-postgres:/var/lib/postgresql/data
      volumes:
         hapi-fhir-postgres:

3. 啟動服務、關閉服務與修改建置之指令

• 執行執行HAPI Server Docker Compose

cd hapi-fhir-jpaserver-starter
# 啟動服務
docker compose up
# 關閉並刪除服務
docker compose down
# 修改 application.yaml後，需重新建置
docker compose build hapi-fhir-jpaserver-start

如何建立一個實作指引(IG)

1.環境建置:

Clone your IG repository

$ git clone https://github.com/ITRI-BDL-D/MOHW-Sample-IG.git
$ cd MOHW-Sample-IG

安裝 JAVA

在建置 IG 之前，您需要安裝 Java Development Kit (JDK)。前往 https://adoptopenjdk.net/ 下載適用於您平台的最新（版本 8 或更高版本）JDK 並安裝它。

安裝 Ruby 及 Jekyll

Ruby Jekyll 需要 Ruby 2.7.0 或更高版本。如果您需要較新版本，請前往 https://www.ruby-lang.org/en/downloads/ 尋找說明。

Jekyll 前往 https://jekyllrb.com 並按照那裡的說明進行操作。

gem install jekyll bundler

測試是否安裝成功

jekyll -v

安裝 SUSHI

安裝 Node.js 安裝SUSHI

npm install -g fsh-sushi
sushi help

2.撰寫 FHIR Shorthand:

什麼是 FHIR Shorthand?

(圖片來源：https://build.fhir.org/ig/HL7/fhir-shorthand/index.html)

轉換工具: FSH ONLINE (https://fshonline.fshschool.org/) 、GoFSH (https://github.com/FHIR/GoFSH)。

Build

sushi

3.Local Build

更新 Publisher.jar

./_updatePublisher.sh

更新publication-request.json

Build

./_genonce.sh

開啟output/index.html

(圖片來源：工研院整理製作)

QA Report – 請檢查並修復錯誤

4.Publish

Fork FHIR IG registry Clone the HL7 history, web templates, and FHIR IG registry repositories.

$ git clone git@github.com:HL7/fhir-ig-history-template.git ig-history
$ git clone git@github.com:HL7/fhir-web-templates.git fhir-web-templates
$ git clone git@github.com:FHIR/ig-registry.git ig-registry

建立 “publication”資料夾建立 publication 資源

$ cd publication
$ mkdir templates webroot
$ cp ../fhir-web-templates/*template* templates

Run the IG Publisher in "publish" mode:

$ cd ~/src/publication
$ java -jar ../publisher.jar -go-publish     -source    /home/username/src/my-ig     -web       /home/username/src/publication/webroot     -history   /home/username/src/ig-history     -registry  /home/username/src/ig-registry/fhir-ig-list.json     -temp      /home/username/src/publication/temp     -templates /home/username/src/publication/templates

FHIR 課程

4. 臺灣核心互通資料群：TW CDI

衛生福利部資訊處技監兼處長

李建璋

2. FHIR 統一資料

衛生福利部資訊處技監兼處長

李建璋

1. 統一臺灣電子病歷的策略思考

衛生福利部資訊處技監兼處長

李建璋

3. 臺灣醫中電子病歷資料統一的架構

衛生福利部資訊處技監兼處長

李建璋

FHIR

Rule Library

SMART on FHIR

SNOMED CT

LOINC

RxNorm

FHIR 教育專區

FHIR 開發概述

創建 Resource 及回應

讀取 Resource 請求及回應

搜尋 Resource 請求及回應

更新 Resource 請求及回應

Resource 內容說明

Resource 之 Profile 與繼承

Resource 的結構說明 (以Patient Resource 為例)

專門術語與值集綁定

安裝 HAPI FHIR Server

如何建立一個實作指引(IG)

FHIR 課程

4. 臺灣核心互通資料群：TW CDI

2. FHIR 統一資料

1. 統一臺灣電子病歷的策略思考

3. 臺灣醫中電子病歷資料統一的架構

FHIR

Rule Library

SMART on FHIR

SNOMED CT

LOINC

RxNorm

FHIR 教育專區

FHIR 開發概述

創建 Resource 及回應

讀取 Resource 請求及回應

搜尋 Resource 請求及回應

更新 Resource 請求及回應

Resource 內容說明

Resource 之 Profile 與繼承

Resource 的結構說明 (以Patient Resource 為例)

專門術語與值集綁定

安裝 HAPI FHIR Server

如何建立一個實作指引(IG)

FHIR 課程

4. 臺灣核心互通資料群：TW CDI

2. FHIR 統一資料

1. 統一臺灣電子病歷的策略思考

3. 臺灣醫中電子病歷資料統一的架構