本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS HealthLake 參考
下列支援參考資料適用於 FHIR、FHIR 和 上的 SMART AWS HealthLake。
**注意**
所有原生 HealthLake 動作和資料類型會在單獨的參考中描述。如需詳細資訊，請參閱 [https://docs.aws.amazon.com/healthlake/latest/APIReference/](https://docs.aws.amazon.com/healthlake/latest/APIReference/)。
**Topics**
+ [FHIR 上的 SMART](reference-smart-on-fhir.md)
+ [FHIR R4](reference-fhir.md)
+ [合規](reference-compliance.md)
+ [HealthLake](reference-healthlake.md)
# 的 FHIR 上的 SMART 支援 AWS HealthLake
啟用 FHIR 的 HealthLake 資料存放區上的可替代醫療應用程式和可重複使用技術 (SMART) 允許在符合 FHIR 的應用程式上存取 SMART。HealthLake 資料是透過使用第三方授權伺服器來驗證和授權請求來存取。因此，您不是透過 管理使用者登入資料 AWS Identity and Access Management，而是使用符合 FHIR 規範的授權伺服器上的 SMART。
**注意**
HealthLake 在 FHIR 版本 1.0 和 2.0 上支援 SMART。若要進一步了解這些架構，請參閱 *FHIR R4 文件*中的 [SMART 應用程式啟動](https://www.hl7.org/fhir/smart-app-launch/)。
HealthLake 資料存放區支援下列 FHIR 請求上的 SMART 身分驗證和授權架構：
**OpenID (AuthN)**：驗證人員或用戶端應用程式是他們聲稱是誰 （或什麼）。
**OAuth 2.0 (AuthZ)**：用於授權 HealthLake 資料存放區中的哪些 FHIR 資源，已驗證的請求可以讀取或寫入。這是由授權伺服器中設定的範圍所定義。
您可以使用 AWS CLI AWS SDKs 在啟用 FHIR 的資料存放區上建立 SMART。如需詳細資訊，請參閱[建立 HealthLake 資料存放區](managing-data-stores-create.md)。
**Topics**
+ [FHIR 上的 SMART 入門](reference-smart-on-fhir-getting-started.md)
+ [FHIR 上 SMART 的 HealthLake 身分驗證要求](reference-smart-on-fhir-authentication.md)
+ [HealthLake 支援的 FHIR OAuth 2.0 範圍上的 SMART](reference-smart-on-fhir-oauth-scopes.md)
+ [使用 驗證字符 AWS Lambda](reference-smart-on-fhir-token-validation.md)
+ [在啟用 FHIR 的 HealthLake 資料存放區上搭配 SMART 使用精細授權](reference-smart-on-fhir-fine-grained-authorization.md)
+ [在 FHIR 探索文件上擷取 SMART](reference-smart-on-fhir-discovery-document.md)
+ [在已啟用 SMART 功能的 HealthLake 資料存放區上提出 FHIR REST API 請求](reference-smart-on-fhir-request-example.md)
# FHIR 上的 SMART 入門
下列主題說明如何開始使用 AWS HealthLake 的 FHIR 授權上的 SMART。其中包括您必須在 AWS 帳戶中佈建的資源、在啟用 FHIR 的 HealthLake 資料存放區上建立 SMART，以及 FHIR 用戶端應用程式如何與授權伺服器和 HealthLake 資料存放區互動的範例。
**Topics**
+ [在 FHIR 上為 SMART 設定資源](#smart-on-fhir-resources)
+ [FHIR 上適用於 SMART 的用戶端應用程式工作流程](#smart-on-fhir-client-app-workflow)
## 在 FHIR 上為 SMART 設定資源
下列步驟定義 HealthLake 如何處理 FHIR 請求上的 SMART，以及成功所需的資源。下列元素在工作流程中一起運作，以在 FHIR 上建立 SMART 請求：
+ **最終使用者**：通常，病患或臨床醫生在 FHIR 上使用第三方 SMART 來存取 HealthLake 資料存放區中的資料。
+ **FHIR 上的 SMART 應用程式 （稱為用戶端應用程式）**：想要存取 HealthLake 資料存放區中找到之資料的應用程式。
+ **授權伺服器**：符合 OpenID Connect 標準的伺服器，能夠驗證使用者並發出存取權杖。
+ **HealthLake 資料存放**區：啟用 FHIR 的 SMART HealthLake存放區，使用 Lambda 函數回應提供承載字符的 FHIR REST 請求。
若要讓這些元素一起運作，您必須建立下列資源。
**注意**
我們建議您在設定授權伺服器、定義必要的[範圍](reference-smart-on-fhir-oauth-scopes.md)，並建立 AWS Lambda 函數來處理[權杖](reference-smart-on-fhir-token-validation.md)自我檢查之後，在啟用 FHIR 的 HealthLake 資料存放區上建立您的 SMART。
**1. 設定授權伺服器端點**
若要在 FHIR 架構上使用 SMART，您需要設定第三方授權伺服器，以驗證對資料存放區提出的 FHIR REST 請求。如需詳細資訊，請參閱[FHIR 上 SMART 的 HealthLake 身分驗證要求](reference-smart-on-fhir-authentication.md)。
**2. 在授權伺服器上定義範圍，以控制 HealthLake 資料存放區存取層級**
FHIR 上的 SMART 架構使用 OAuth 範圍來判斷已驗證請求可存取的 FHIR 資源，以及存取程度。定義範圍是針對最低權限進行設計的一種方式。如需詳細資訊，請參閱[HealthLake 支援的 FHIR OAuth 2.0 範圍上的 SMART](reference-smart-on-fhir-oauth-scopes.md)。
**3. 設定能夠執行權杖自我檢查的 AWS Lambda 函數**
用戶端應用程式在啟用 FHIR 的 SMART 資料存放區上傳送的 FHIR REST 請求包含 JSON Web Token (JWT)。如需詳細資訊，請參閱[解碼 JWT](reference-smart-on-fhir-token-validation.md)。
**4. 在啟用 FHIR 的 HealthLake 資料存放區上建立 SMART**
若要在 FHIR HealthLake 資料存放區上建立 SMART，您需要提供 `IdentityProviderConfiguration`。如需詳細資訊，請參閱[建立 HealthLake 資料存放區](managing-data-stores-create.md)。
## FHIR 上適用於 SMART 的用戶端應用程式工作流程
下一節說明如何在 FHIR 上的 SMART 內容中啟動用戶端應用程式，並在 HealthLake 資料存放區上提出成功的 FHIR REST 請求。
**1. 使用用戶端應用程式向 Well-Known Uniform Resource Identifier 提出`GET`請求**
已啟用 SMART 的用戶端應用程式必須提出`GET`請求，以尋找 HealthLake 資料存放區的授權端點。這是透過 Well-Known Uniform Resource Identifier (URI) 請求來完成的。如需詳細資訊，請參閱[在 FHIR 探索文件上擷取 SMART](reference-smart-on-fhir-discovery-document.md)。
**2. 請求存取和範圍**
用戶端應用程式使用授權伺服器的授權端點，讓使用者可以登入。此程序會驗證使用者。範圍用於定義用戶端應用程式可在 HealthLake 資料存放區中存取的 FHIR 資源。如需詳細資訊，請參閱[HealthLake 支援的 FHIR OAuth 2.0 範圍上的 SMART](reference-smart-on-fhir-oauth-scopes.md)。
**3. 存取權杖**
現在使用者已通過身分驗證，用戶端應用程式會從授權伺服器收到 JWT 存取字符。當用戶端應用程式傳送 FHIR REST 請求給 HealthLake 時，會提供此字符。如需詳細資訊，請參閱[字符驗證](reference-smart-on-fhir-token-validation.md)。
**4. 在啟用 FHIR 的 HealthLake 資料存放區上對 SMART 提出 FHIR REST API 請求**
用戶端應用程式現在可以使用授權伺服器提供的存取權杖，將 FHIR REST API 請求傳送至 HealthLake 資料存放區端點。如需詳細資訊，請參閱[在已啟用 SMART 功能的 HealthLake 資料存放區上提出 FHIR REST API 請求](reference-smart-on-fhir-request-example.md)。
**5. 驗證 JWT 存取權杖**
若要驗證 FHIR REST 請求中傳送的存取權杖，請使用 Lambda 函數。如需詳細資訊，請參閱[使用 驗證字符 AWS Lambda](reference-smart-on-fhir-token-validation.md)。
# FHIR 上 SMART 的 HealthLake 身分驗證要求
若要存取啟用 FHIR 之 HealthLake 資料存放區上的 SMART 中的 FHIR 資源，用戶端應用程式必須由 OAuth 2.0 相容授權伺服器授權，並在 FHIR REST API 請求中呈現 OAuth Bearer 權杖。若要尋找授權伺服器的端點，請透過`Well-Known`統一資源識別符在 FHIR 探索文件上使用 HealthLake SMART。若要進一步了解此程序，請參閱[在 FHIR 探索文件上擷取 SMART](reference-smart-on-fhir-discovery-document.md)。
在 FHIR HealthLake 資料存放區上建立 SMART 時，您必須在`CreateFHIRDatastore`請求的 `metadata`元素中定義授權伺服器的端點和字符端點。若要進一步了解如何定義 `metadata`元素，請參閱 [建立 HealthLake 資料存放區](managing-data-stores-create.md)。
使用授權伺服器端點，用戶端應用程式將使用授權服務驗證使用者。一旦授權和驗證，授權服務會產生 JSON Web Token (JWT)，並傳遞給用戶端應用程式。此字符包含允許用戶端應用程式使用的 FHIR 資源範圍，進而限制使用者可存取的資料。或者，如果提供了啟動範圍，則回應將包含這些詳細資訊。若要進一步了解 HealthLake 支援的 FHIR 範圍上的 SMART，請參閱 [HealthLake 支援的 FHIR OAuth 2.0 範圍上的 SMART](reference-smart-on-fhir-oauth-scopes.md)。
使用授權伺服器授予的 JWT，用戶端應用程式會對啟用 FHIR 的 HealthLake 資料存放區上的 SMART 進行 FHIR REST API 呼叫。若要驗證和解碼 JWT，您需要建立 Lambda 函數。HealthLake 會在收到 FHIR REST API 請求時代表您叫用此 Lambda 函數。若要查看入門 Lambda 函數範例，請參閱 [使用 驗證字符 AWS Lambda](reference-smart-on-fhir-token-validation.md)。
## 在啟用 FHIR 的 HealthLake 資料存放區上建立 SMART 所需的授權伺服器元素
在`CreateFHIRDatastore`請求中，您需要提供授權端點和字符端點，做為 `IdentityProviderConfiguration` 物件中 `metadata`元素的一部分。授權端點和字符端點都是必要的。若要查看如何在`CreateFHIRDatastore`請求中指定範例，請參閱 [建立 HealthLake 資料存放區](managing-data-stores-create.md)。
## 在啟用 FHIR 的 HealthLake 資料存放區上完成 SMART 上的 FHIR REST API 請求所需的宣告
您的 AWS Lambda 函數必須包含下列宣告，才能在啟用 FHIR 的 HealthLake 資料存放區上成為 SMART 上的有效 FHIR REST API 請求。
+ `nbf`：[（非之前） 宣告](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) — "nbf" （非之前） 宣告會識別不得接受 JWT 處理的時間。處理 "nbf" 宣告時，目前日期/時間必須晚於或等於 "nbf" 宣告中列出的不早於日期/時間。我們提供的 Lambda 函數範例`iat`會從伺服器回應轉換為 `nbf`。
+ `exp`：[（過期時間） 宣告](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) —「過期」（過期時間） 宣告會識別 JWT 當天或之後不得接受處理的過期時間。
+ `isAuthorized`：布林值設定為 `True`。指出請求已在授權伺服器上獲得授權。
+ `aud`：[（對象） 宣告](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3) — "aud" （對象） 宣告可識別 JWT 的收件人。這必須是啟用 FHIR 的 HealthLake 資料存放區端點上的 SMART。
+ `scope`：這必須至少是一個 FHIR 資源相關範圍。此範圍在您的授權伺服器上定義。若要進一步了解 HealthLake 接受的 FHIR 資源相關範圍，請參閱 [HealthLake 的 FHIR 資源範圍上的 SMART](reference-smart-on-fhir-oauth-scopes.md#smart-on-fhir-scopes-rest)。
# HealthLake 支援的 FHIR OAuth 2.0 範圍上的 SMART
HealthLake 使用 OAuth 2.0 做為授權通訊協定。在授權伺服器上使用此通訊協定可讓您為用戶端應用程式可存取的 FHIR 資源定義 HealthLake 資料存放區許可 （建立、讀取、更新、刪除和搜尋）。
FHIR 上的 SMART 架構定義一組可以從授權伺服器請求的範圍。例如，僅設計為允許患者檢視其實驗室結果或檢視其聯絡詳細資訊的用戶端應用程式，應僅*獲授權*請求`read`範圍。
**注意**
HealthLake 支援 FHIR V1 和 V2 上的 SMART，如下所述。建立資料存放區時，SMART on FHIR [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy)設定為下列三個值之一：
`SMART_ON_FHIR_V1` – 僅支援 FHIR V1 上的 SMART，其中包含 `read`（讀取/搜尋） 和 `write`(create/update/delete許可。
`SMART_ON_FHIR` – 支援 FHIR V1 和 V2 上的 SMART，其中包括 `create`、`read`、`delete`、 `update`和 `search`許可。
`AWS_AUTH` – 預設的 AWS HealthLake 授權策略；與 FHIR 上的 SMART 無關。
## 獨立啟動範圍
HealthLake 支援獨立啟動模式範圍 `launch/patient`。
在獨立啟動模式中，用戶端應用程式會請求存取病患的臨床資料，因為用戶端應用程式不知道使用者和病患。因此，用戶端應用程式的授權請求會明確請求傳回病患範圍。身分驗證成功後，授權伺服器會發出存取字符，其中包含請求的啟動病患範圍。所需的患者內容會在授權伺服器的回應中與存取字符一起提供。
**支援的啟動模式範圍**
| Scope (範圍) | Description |
| --- | --- |
| `launch/patient` | OAuth 2.0 授權請求中的參數，請求在授權回應中傳回該病患資料。 |
## HealthLake 的 FHIR 資源範圍上的 SMART
HealthLake 在 FHIR 資源範圍上定義三個層級的 SMART。
+ `patient` 範圍會授予單一病患特定資料的存取權。
+ `user` 範圍會授予使用者可存取的特定資料的存取權。
+ `system` 範圍會授予 HealthLake 資料存放區中所有 FHIR 資源的存取權。
下列各節列出使用 FHIR V1 上的 SMART 或 FHIR V2 上的 SMART 建構 FHIR 資源範圍的語法。
**注意**
建立資料存放區時，會設定 FHIR 上的 SMART 授權策略。如需詳細資訊，請參閱 *AWS HealthLake API 參考*[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy)中的 。
### HealthLake 支援的 FHIR V1 範圍上的 SMART
在 FHIR V1 上使用 SMART 時，用於建構 HealthLake 的 FHIR 資源範圍的一般語法如下。若要在下列範例中檢視整個 URL 路徑，請捲動至**複製**按鈕。
```
('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('read' | 'write' | '*')
```
**FHIR v1 支援的授權範圍上的 SMART**
| 範圍語法 | 範例範圍 | 結果 |
| --- | --- | --- |
| `patient/(fhir-resource \| '*').('read' \| 'write' \| '*')` | patient/AllergyIntolerance.\$1 | 病患用戶端應用程式具有所有記錄的區分的執行個體層級讀取/寫入存取權。 |
| `user/(fhir-resource \| '*').('read' \| 'write' \| '*')` | user/Observation.read | 使用者用戶端應用程式具有所有記錄觀察的執行個體層級讀取/寫入存取權。 |
| system/('read' \$1 'write' \$1 \$1) | system/\$1.\$1 | 系統用戶端應用程式具有所有 FHIR 資源資料的讀取/寫入存取權。 |
### HealthLake 支援的 FHIR V2 範圍上的 SMART
在 FHIR V2 上使用 SMART 時，用於建構 HealthLake 的 FHIR 資源範圍的一般語法如下。若要在下列範例中檢視整個 URL 路徑，請捲動至**複製**按鈕。
```
('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('c' | 'r' | 'u' | 'd' | 's')
```
**注意**
若要在 FHIR V2 上使用 SMART，您必須將值傳入[https://hl7.org/fhir/smart-app-launch/STU2/conformance.html#permissions](https://hl7.org/fhir/smart-app-launch/STU2/conformance.html#permissions)中繼資料`capabilities`字串，這是 [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html) 資料類型的成員。
HealthLake 支援精細範圍。如需詳細資訊，請參閱 *FHIR US Core 實作指南*中[支援的精細範圍](https://hl7.org/fhir/us/core/scopes.html#the-following-granular-scopes-shall-be-supported)。
**FHIR V2 支援的授權範圍上的 SMART**
| 範圍語法 | 範例 V1 範圍 | 結果 |
| --- | --- | --- |
| `patient/Observation.rs` | user/Observation.read | 讀取和搜尋目前病患Observation資源的許可。 |
| `system/*.cruds` | system/\$1.\$1 | 系統用戶端應用程式具有所有 FHIR 資源資料的完整create/read/update/刪除/搜尋存取權。 |
# 使用 驗證字符 AWS Lambda
當您在啟用 FHIR 的資料存放區上建立 HealthLake SMART 時，您必須在`CreateFHIRDatastore`請求中提供 AWS Lambda 函數的 ARN。Lambda 函數的 ARN 是使用 `IdpLambdaArn` 參數在 `IdentityProviderConfiguration` 物件中指定。
您必須先建立 Lambda 函數，才能建立啟用 FHIR 的 SMART 資料存放區。建立資料存放區後，就無法變更 Lambda ARN。若要查看您在建立資料存放區時指定的 Lambda ARN，請使用 `DescribeFHIRDatastore` API 動作。
**若要讓 FHIR REST 請求在啟用 FHIR 的資料存放區上在 SMART 上成功，您的 Lambda 函數必須執行下列動作：**
+ 在 1 秒內將回應傳回 HealthLake 資料存放區端點。
+ 解碼用戶端應用程式傳送之 REST API 請求的授權標頭中提供的存取字符。
+ 指派具有足夠許可可執行 FHIR REST API 請求的 IAM 服務角色。
+ 需要下列宣告才能完成 FHIR REST API 請求。如需詳細資訊，請參閱 [必要宣告](reference-smart-on-fhir-authentication.md#server-response)。
+ `nbf`
+ `exp`
+ `isAuthorized`
+ `aud`
+ `scope`
使用 Lambda 時，除了 Lambda 函數之外，您還需要建立執行角色和資源型政策。Lambda 函數的執行角色是 IAM 角色，授予函數存取執行時間所需 AWS 服務和資源的許可。您提供的資源型政策必須允許 HealthLake 代表您叫用您的函數。
本主題中的各節說明來自用戶端應用程式和解碼回應的範例請求、建立 AWS Lambda 函數所需的步驟，以及如何建立 HealthLake 可採用的資源型政策。
+ [第 1 部分：建立 Lambda 函數](#smart-on-fhir-lambda-create)
+ [第 2 部分：建立 AWS Lambda 函數使用的 HealthLake 服務角色](#smart-on-fhir-lambda-service-role)
+ [第 3 部分：更新 Lambda 函數的執行角色](#smart-on-fhir-lambda-service-role-execution-role)
+ [第 4 部分：將資源政策新增至 Lambda 函數](#smart-on-fhir-lambda-invoke-healthlake)
+ [第 5 部分：為您的 Lambda 函數佈建並行](#smart-on-fhir-lambda-function-scaling)
## 建立 AWS Lambda 函數
此主題中建立的 Lambda 函數會在 HealthLake 收到對啟用 FHIR 的 SMART 資料存放區的請求時觸發。來自用戶端應用程式的請求包含 REST API 呼叫，以及包含存取字符的授權標頭。
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/
Authorization: Bearer i8hweunweunweofiwweoijewiwe
```
本主題中的範例 Lambda 函數會使用 AWS Secrets Manager 來隱藏與授權伺服器相關的登入資料。我們強烈建議不要直接在 Lambda 函數中提供授權伺服器登入詳細資訊。
**Example 驗證包含授權承載字符的 FHIR REST 請求**
Lambda 函數範例示範如何驗證傳送到啟用 FHIR 之 SMART 資料存放區的 FHIR REST 請求。若要查看如何實作此 Lambda 函數step-by-steps說明，請參閱 [使用 建立 Lambda 函數 AWS 管理主控台](#create-lambda-console)。
如果 FHIR REST API 請求不包含有效的資料存放區端點、存取字符和 REST 操作，Lambda 函數將會失敗。若要進一步了解必要的授權伺服器元素，請參閱 [必要宣告](reference-smart-on-fhir-authentication.md#server-response)。
```
import base64
import boto3
import logging
import json
import os
from urllib import request, parse
logger = logging.getLogger()
logger.setLevel(logging.INFO)
## Uses Secrets manager to gain access to the access key ID and secret access key for the authorization server
client = boto3.client('secretsmanager', region_name="region-of-datastore")
response = client.get_secret_value(SecretId='name-specified-by-customer-in-secretsmanager')
secret = json.loads(response['SecretString'])
client_id = secret['client_id']
client_secret = secret['client_secret']
unencoded_auth = f'{client_id}:{client_secret}'
headers = {
'Authorization': f'Basic {base64.b64encode(unencoded_auth.encode()).decode()}',
'Content-Type': 'application/x-www-form-urlencoded'
}
auth_endpoint = os.environ['auth-server-base-url'] # Base URL of the Authorization server
user_role_arn = os.environ['iam-role-arn'] # The IAM role client application will use to complete the HTTP request on the datastore
def lambda_handler(event, context):
if 'datastoreEndpoint' not in event or 'operationName' not in event or 'bearerToken' not in event:
return {}
datastore_endpoint = event['datastoreEndpoint']
operation_name = event['operationName']
bearer_token = event['bearerToken']
logger.info('Datastore Endpoint [{}], Operation Name: [{}]'.format(datastore_endpoint, operation_name))
## To validate the token
auth_response = auth_with_provider(bearer_token)
logger.info('Auth response: [{}]'.format(auth_response))
auth_payload = json.loads(auth_response)
## Required parameters needed to be sent to the datastore endpoint for the HTTP request to go through
auth_payload["isAuthorized"] = bool(auth_payload["active"])
auth_payload["nbf"] = auth_payload["iat"]
return {"authPayload": auth_payload, "iamRoleARN": user_role_arn}
## access the server
def auth_with_provider(token):
data = {'token': token, 'token_type_hint': 'access_token'}
req = request.Request(url=auth_endpoint + '/v1/introspect', data=parse.urlencode(data).encode(), headers=headers)
with request.urlopen(req) as resp:
return resp.read().decode()
```
### 使用 建立 Lambda 函數 AWS 管理主控台
下列程序假設您已在啟用 FHIR 的 SMART 資料存放區上處理 FHIR REST API 請求時，建立希望 HealthLake 擔任的服務角色。如果您尚未建立服務角色，您仍然可以建立 Lambda 函數。您必須先新增服務角色的 ARN，Lambda 函數才能運作。若要進一步了解如何建立服務角色並在 Lambda 函數中指定該角色，請參閱 [建立 HealthLake 服務角色以用於用來解碼 JWT 的 AWS Lambda 函數](#smart-on-fhir-lambda-service-role)
**建立 Lambda 函數 (AWS 管理主控台)**
1. 開啟 Lambda 主控台中的 [函數頁面](https://console.aws.amazon.com/lambda/home/functions)。
1. 選擇**建立函數**。
1. 選取**從頭開始撰寫**。
1. 在**基本資訊**下，輸入**函數名稱**。在**執行時間**下，選擇以 Python 為基礎的執行時間。
1. **執行角色** 請選擇 **建立具備基本 Lambda 許可的新角色** 。
Lambda 會建立函數和[執行角色](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html)，此角色會授予函數將日誌上傳至 Amazon CloudWatch 的許可。Lambda 函數會在您叫用函數時擔任執行角色，並使用執行角色來建立 AWS SDK 的登入資料。
1. 選擇**程式碼**索引標籤，然後新增範例 Lambda 函數。
如果您尚未為 Lambda 函數建立要使用的服務角色，則必須先建立該角色，範例 Lambda 函數才能運作。若要進一步了解如何為 Lambda 函數建立服務角色，請參閱 [建立 HealthLake 服務角色以用於用來解碼 JWT 的 AWS Lambda 函數](#smart-on-fhir-lambda-service-role)。
```
import base64
import boto3
import logging
import json
import os
from urllib import request, parse
logger = logging.getLogger()
logger.setLevel(logging.INFO)
## Uses Secrets manager to gain access to the access key ID and secret access key for the authorization server
client = boto3.client('secretsmanager', region_name="region-of-datastore")
response = client.get_secret_value(SecretId='name-specified-by-customer-in-secretsmanager')
secret = json.loads(response['SecretString'])
client_id = secret['client_id']
client_secret = secret['client_secret']
unencoded_auth = f'{client_id}:{client_secret}'
headers = {
'Authorization': f'Basic {base64.b64encode(unencoded_auth.encode()).decode()}',
'Content-Type': 'application/x-www-form-urlencoded'
}
auth_endpoint = os.environ['auth-server-base-url'] # Base URL of the Authorization server
user_role_arn = os.environ['iam-role-arn'] # The IAM role client application will use to complete the HTTP request on the datastore
def lambda_handler(event, context):
if 'datastoreEndpoint' not in event or 'operationName' not in event or 'bearerToken' not in event:
return {}
datastore_endpoint = event['datastoreEndpoint']
operation_name = event['operationName']
bearer_token = event['bearerToken']
logger.info('Datastore Endpoint [{}], Operation Name: [{}]'.format(datastore_endpoint, operation_name))
## To validate the token
auth_response = auth_with_provider(bearer_token)
logger.info('Auth response: [{}]'.format(auth_response))
auth_payload = json.loads(auth_response)
## Required parameters needed to be sent to the datastore endpoint for the HTTP request to go through
auth_payload["isAuthorized"] = bool(auth_payload["active"])
auth_payload["nbf"] = auth_payload["iat"]
return {"authPayload": auth_payload, "iamRoleARN": user_role_arn}
## Access the server
def auth_with_provider(token):
data = {'token': token, 'token_type_hint': 'access_token'}
req = request.Request(url=auth_endpoint + '/v1/introspect', data=parse.urlencode(data).encode(), headers=headers)
with request.urlopen(req) as resp:
return resp.read().decode()
```
### 修改 Lambda 函數的執行角色
建立 Lambda 函數之後，您需要更新執行角色，以包含呼叫 Secrets Manager 的必要許可。在 Secrets Manager 中，您建立的每個秘密都有 ARN。若要套用最低權限，執行角色應只能存取 Lambda 函數執行所需的資源。
您可以在 IAM 主控台中搜尋 Lambda 函數，或在 Lambda 主控台中選擇**組態**，以修改 Lambda 函數的執行角色。若要進一步了解如何管理 Lambda 函數執行角色，請參閱 [Lambda 執行角色](#smart-on-fhir-lambda-service-role-execution-role)。
**Example 授予 存取權的 Lambda 函數執行角色 `GetSecretValue`**
將 IAM 動作新增至`GetSecretValue`執行角色會授予範例 Lambda 函數運作所需的許可。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "secretsmanager:GetSecretValue",
"Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:secret-name-DKodTA"
}
]
}
```
此時，您已建立 Lambda 函數，可用於驗證作為 FHIR REST 請求的一部分提供的存取字符，該請求會傳送到啟用 FHIR 的 SMART 資料存放區。
## 建立 HealthLake 服務角色以用於用來解碼 JWT 的 AWS Lambda 函數
**人物：IAM 管理員**
可新增或移除 IAM 政策，並建立新的 IAM 身分的使用者。
**服務 角色**
服務角色是服務擔任的 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)，可代您執行動作。IAM 管理員可以從 IAM 內建立、修改和刪除服務角色。如需詳細資訊，請參閱《*IAM 使用者指南*》中的[建立角色以委派許可給 AWS 服務](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)。
JSON Web Token (JWT) 解碼後，Lambda 需要授權，才能傳回 IAM 角色 ARN。此角色必須具有執行 REST API 請求的必要許可，否則會因為許可不足而失敗。
使用 IAM 設定自訂政策時，最好授予所需的最低許可。若要進一步了解，請參閱《*IAM 使用者指南*》中的[套用最低權限許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege)。
建立 HealthLake 服務角色以在授權 Lambda 函數中指定 需要兩個步驟。
+ 首先，您需要建立 IAM 政策。此政策必須指定您在授權伺服器中提供 範圍的 FHIR 資源存取權。
+ 其次，您需要建立 服務角色。當您建立角色時，您可以指定信任關係，並連接您在步驟 1 中建立的政策。信任關係會將 HealthLake 指定為服務委託人。在此步驟中，您需要指定 HealthLake 資料存放區 ARN 和 AWS 帳戶 ID。
### 建立新的 IAM 政策
您在授權伺服器中定義的範圍會決定已驗證使用者在 HealthLake 資料存放區中可存取的 FHIR 資源。
您可以量身打造您建立的 IAM 政策，以符合您定義的範圍。
您可以在 IAM 政策陳述式的 `Action`元素中定義下列動作。對於資料表`Action`中的每個 ，您可以定義 `Resource types`。在 HealthLake 中，資料存放區是唯一支援的資源類型，可在 IAM 許可政策陳述式的 `Resource`元素中定義。
個別 FHIR 資源不是您可以定義為 IAM 許可政策中 元素的資源。
**HealthLake 定義的動作**
| 動作 | 描述 | 存取層級 | 資源類型 （必要） |
| --- | --- | --- | --- |
| CreateResource | 准許建立資源 | 寫入 | 資料存放區 ARN：arn：aws：healthlakeyour-region：111122223333：datastore/fhir/your-datastore-id |
| DeleteResource | 准許刪除資源 | 寫入 | 資料存放區 ARN：arn：aws：healthlakeyour-region：111122223333：datastore/fhir/your-datastore-id |
| ReadResource | 准許讀取資源 | 讀取 | 資料存放區 ARN：arn：aws：healthlakeyour-region：111122223333：datastore/fhir/your-datastore-id |
| SearchWithGet | 准許使用 GET 方法搜尋資源 | 讀取 | 資料存放區 ARN：arn：aws：healthlakeyour-region：111122223333：datastore/fhir/your-datastore-id |
| SearchWithPost | 准許使用 POST 方法搜尋資源 | 讀取 | 資料存放區 ARN：arn：aws：healthlakeyour-region：111122223333：datastore/fhir/your-datastore-id |
| StartFHIRExportJobWithPost | 准許使用 GET 開始 FHIR 匯出任務 | 寫入 | 資料存放區 ARN：arn：aws：healthlakeyour-region：111122223333：datastore/fhir/your-datastore-id |
| UpdateResource | 准許更新資源 | 寫入 | 資料存放區 ARN：arn：aws：healthlakeyour-region：111122223333：datastore/fhir/your-datastore-id |
若要開始使用，您可以使用 `AmazonHealthLakeFullAccess`。此政策會授予資料存放區中所有 FHIR 資源的讀取、寫入、搜尋和匯出。若要授予資料存放區的唯讀許可，請使用 `AmazonHealthLakeReadOnlyAccess`。
若要進一步了解如何使用 AWS 管理主控台 AWS CLI或 IAM SDKs建立自訂政策，請參閱《[IAM 使用者指南》中的建立](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) *IAM* 政策。
### 建立 HealthLake 的服務角色 (IAM 主控台）
使用此程序來建立服務角色。建立服務時，您也需要指定 IAM 政策。
**建立 HealthLake 的服務角色 (IAM 主控台）**
1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 的 IAM 主控台。
1. 在 IAM 主控台的導覽窗格中，選擇**角色**。
1. 然後，選擇 **Create role** (建立角色)。
1. 在**選取信任實體**頁面上，選擇**自訂信任政策**。
1. 接著，在**自訂信任政策**下，更新範例政策，如下所示。**your-account-id** 將 取代為您的帳戶號碼，並新增要在匯入或匯出任務中使用的資料存放區的 ARN。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Principal": {
"Service": "healthlake.amazonaws.com"
},
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnEquals": {
"aws:SourceArn": "arn:aws:healthlake:us-east-1:123456789012:datastore/fhir/your-datastore-id"
}
}
}
]
}
```
------
1. 然後選擇**下一步**。
1. 在**新增許可**頁面上，選擇您希望 HealthLake 服務擔任的政策。若要尋找您的政策，請在**許可政策**下進行搜尋。
1. 然後，選擇**連接政策**。
1. 然後在**角色名稱**下**的名稱、檢閱和建立**頁面上輸入名稱。
1. （選用）接著在**描述**下，為您的角色新增簡短描述。
1. 如果可能，請輸入角色名稱或角色名稱後綴，以協助您識別此角色的用途。角色名稱在您的 AWS 帳戶內必須是獨一無二的。它們無法透過大小寫進行區分。例如，您無法建立名為 **PRODROLE** 和 **prodrole** 的角色。因為有各種實體可能會參照角色，所以您無法在建立角色之後編輯角色名稱。
1. 檢閱角色詳細資訊，然後選擇**建立角色**。
若要了解如何在範例 Lambda 函數中指定角色 ARN，請參閱 [建立 AWS Lambda 函數](#smart-on-fhir-lambda-create)。
## Lambda 執行角色
Lambda 函數的執行角色是授予函數存取 AWS 服務和資源的許可的 IAM 角色。本頁提供有關如何建立、檢視和管理 Lambda 函數執行角色的資訊。
根據預設，當您使用 建立新的 Lambda 函數時，Lambda 會建立具有最少許可的執行角色 AWS 管理主控台。若要管理執行角色中授予的許可，請參閱 *Lambda 開發人員指南*中的[在 IAM 主控台中建立執行角色](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html#permissions-executionrole-console)。
本主題中提供的 Lambda 函數範例使用 Secrets Manager 來隱藏授權伺服器的憑證。
如同您建立的任何 IAM 角色，請務必遵循最低權限最佳實務。在開發片語期間，有時您可能會授予超出必要範圍的許可。在生產環境中發佈您的函數之前，最佳實務是調整政策以僅包含必要的許可。如需詳細資訊，請參閱《*IAM 使用者指南*》中的[套用最低權限](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege)。
## 允許 HealthLake 觸發您的 Lambda 函數
因此 HealthLake 可以代表您叫用 Lambda 函數，您必須執行下列動作：
+ 您需要將 設定為`IdpLambdaArn`等於您希望 HealthLake 在`CreateFHIRDatastore`請求中調用之 Lambda 函數的 ARN。
+ 您需要以資源為基礎的政策，允許 HealthLake 代表您叫用 Lambda 函數。
當 HealthLake 在啟用 FHIR 的 SMART 資料存放區上收到 FHIR REST API 請求時，它需要許可來代表您調用資料存放區建立時指定的 Lambda 函數。若要授予 HealthLake 存取權，您將使用以資源為基礎的政策。若要進一步了解如何為 Lambda 函數建立資源型政策，請參閱《 *AWS Lambda 開發人員指南*》中的[允許 AWS 服務呼叫 Lambda 函數](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html#permissions-resource-serviceinvoke)。
## 為您的 Lambda 函數佈建並行
**重要**
HealthLake 需要 Lambda 函數的最大執行時間少於一秒 (1000 毫秒）。
如果您 Lambda 函數超過執行時間限制，您會收到 TimeOut 例外狀況。
為了避免發生此例外狀況，建議您設定佈建並行。您可以在增加呼叫前配置佈建並行，來確保所有請求均由具有低延遲的初始化執行個體所提供。若要進一步了解如何設定佈建並行，請參閱 *Lambda 開發人員指南*中的[設定佈建並行](https://docs.aws.amazon.com/ambda/latest/dg/provisioned-concurrency.html)
若要查看 Lambda 函數的平均執行時間，目前請使用 Lambda 主控台上 Lambda 函數的**監控**頁面。根據預設，Lambda 主控台會提供**持續時間**圖表，顯示函數程式碼處理事件的平均、最短和最長時間。若要進一步了解監控 Lambda 函數，請參閱 [Lambda 開發人員指南中的 Lambda 主控台中的監控函數](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-functions-access-metrics.html#monitoring-console-graph-types)。 **
如果您已為 Lambda 函數佈建並行，並想要監控它，請參閱《*Lambda 開發人員指南*》中的[監控並行](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-concurrency.html)。
# 在啟用 FHIR 的 HealthLake 資料存放區上搭配 SMART 使用精細授權
僅[範圍](reference-smart-on-fhir-oauth-scopes.md#smart-on-fhir-scopes-rest)不會為您提供請求者有權在資料存放區中存取哪些資料的必要具體性。在啟用 FHIR 的 HealthLake 資料存放區上授予 SMART 存取權時，使用精細授權可實現更高層級的特異性。若要使用精細授權，請在`CreateFHIRDatastore`請求的 `IdentityProviderConfiguration` 參數`True`中將 設定為`FineGrainedAuthorizationEnabled`等於 。
如果您啟用精細授權，您的授權伺服器會傳回 中的`fhirUser`範圍`id_token`以及存取權杖。這允許用戶端應用程式擷取有關使用者的資訊。用戶端應用程式應將`fhirUser`宣告視為代表目前使用者的 FHIR 資源 URI。此值可以為 `Patient`、`Practitioner` 或 `RelatedPerson`。授權伺服器的回應也包含定義使用者可存取哪些資料`user/`的範圍。這會使用針對 FHIR 資源特定範圍相關範圍定義的語法：
```
user/(fhir-resource | '*').('read' | 'write' | '*')
```
以下是如何使用精細授權進一步指定資料存取相關 FHIR 資源類型的範例。
+ 當 `fhirUser`為 時`Practitioner`，精細授權會決定使用者可存取的患者集合。`fhirUser` 僅允許病患參考 `fhirUser` 做為一般從業人員的那些病患存取 。
```
Patient.generalPractitioner : [{Reference(Practitioner)}]
```
+ 當 `fhirUser`是 `Patient`或 `RelatedPerson`且請求中參考的患者與 不同時`fhirUser`，精細授權會決定請求患者對 `fhirUser`的存取。在請求`Patient`的資源中指定關係時，允許存取。
```
Patient.link.other : {Reference(Patient|RelatedPerson)}
```
# 在 FHIR 探索文件上擷取 SMART
SMART 定義探索文件，可讓用戶端了解 HealthLake 資料存放區支援的授權端點 URLs和功能。此資訊可協助用戶端將授權請求導向正確的端點，並建構 HealthLake 資料存放區支援的授權請求。
若要讓用戶端應用程式成功向 HealthLake 提出 FHIR REST 請求，必須收集 HealthLake 資料存放區定義的授權要求。*不需要*承載字符 （授權），此請求才能成功。
**請求 HealthLake 資料存放區的探索文件**
1. 收集 HealthLake `region`和 `datastoreId` 值。如需詳細資訊，請參閱[取得資料存放區屬性](managing-data-stores-describe.md)。
1. 使用 HealthLake `region`和 的收集值來建構請求的 URL`datastoreId`。附加`/.well-known/smart-configuration`至 URL 的端點。若要在下列範例中檢視整個 URL 路徑，請捲動至**複製**按鈕。
```
https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/.well-known/smart-configuration
```
1. 使用 `GET` 搭配 [AWS Signature 第 4 版](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)簽署通訊協定來傳送請求。若要檢視整個範例，請捲動至**複製**按鈕。
------
#### [ curl ]
```
curl --request GET \
'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/.well-known/smart-configuration \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
--header "x-amz-security-token:$AWS_SESSION_TOKEN" \
--header 'Accept: application/json'
```
------
HealthLake 資料存放區的探索文件會傳回為 JSON blob，您可以在其中找到 `authorization_endpoint`和 `token_endpoint`，以及資料存放區的規格和定義功能。
```
{
"authorization_endpoint": "https://oidc.example.com/authorize",
"token_endpoint": "https://oidc.example.com/oauth/token",
"capabilities": [
"launch-ehr",
"client-public"
]
}
```
`token_endpoint` 需要 `authorization_endpoint`和 才能啟動用戶端應用程式。
+ **授權端點** — 授權用戶端應用程式或使用者所需的 URL。
+ **權杖端點** — 用戶端應用程式用來與之通訊的授權伺服器端點。
# 在已啟用 SMART 功能的 HealthLake 資料存放區上提出 FHIR REST API 請求
您可以在啟用 FHIR 的 HealthLake 資料存放區上的 SMART 上提出 FHIR REST API 請求。下列範例顯示來自用戶端應用程式的請求，其中包含授權標頭中的 JWT，以及 Lambda 應如何解碼回應。用戶端應用程式請求經過授權和驗證後，必須從授權伺服器收到承載字符。在啟用 FHIR 的 HealthLake 資料存放區上傳送 SMART 上的 FHIR REST API 請求時，請使用授權標頭中的承載字符。
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/[ID]
Authorization: Bearer auth-server-provided-bearer-token
```
因為在授權標頭中找到承載字符，且未偵測到 IAM AWS 身分，所以 HealthLake 會叫用在建立啟用 SMART on FHIR 的 HealthLake 資料存放區時指定的 Lambda 函數。當您的 Lambda 函數成功解碼字符時，以下範例回應會傳送至 HealthLake。
```
{
"authPayload": {
"iss": "https://authorization-server-endpoint/oauth2/token", # The issuer identifier of the authorization server
"aud": "https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/", # Required, data store endpoint
"iat": 1677115637, # Identifies the time at which the token was issued
"nbf": 1677115637, # Required, the earliest time the JWT would be valid
"exp": 1997877061, # Required, the time at which the JWT is no longer valid
"isAuthorized": "true", # Required, boolean indicating the request has been authorized
"uid": "100101", # Unique identifier returned by the auth server
"scope": "system/*.*" # Required, the scope of the request
},
"iamRoleARN": "iam-role-arn" #Required, IAM role to complete the request
}
```
# 的 FHIR R4 支援 AWS HealthLake
AWS HealthLake 支援 FHIR R4 規格進行運作狀態資料交換。下列各節提供 HealthLake 如何使用 FHIR R4 規格來協助您使用 FHIR R4 RESTful APIs [管理和](managing-fhir-resources.md)[搜尋](searching-fhir-resources.md) HealthLake 資料存放區中的 FHIR 資源的支援資訊。
**Topics**
+ [功能陳述式](reference-fhir-capability-statement.md)
+ [設定檔驗證](reference-fhir-profile-validations.md)
+ [資源類型](reference-fhir-resource-types.md)
+ [搜尋參數](reference-fhir-search-parameters.md)
+ [\$1操作](reference-fhir-operations.md)
# 的 FHIR R4 功能陳述式 AWS HealthLake
若要尋找作用中 HealthLake 資料存放區的 FHIR 相關功能 （行為），您必須擷取其功能陳述式。功能陳述式用作實際伺服器功能的陳述式，或所需或所需伺服器實作的陳述式。FHIR [https://hl7.org/fhir/R4/http.html#capabilities](https://hl7.org/fhir/R4/http.html#capabilities)互動會擷取 HealthLake 資料存放區功能及其支援的 FHIR 規格部分的相關資訊。HealthLake 會根據 FHIR R4 資源驗證 FHIR [https://hl7.org/fhir/R4/structuredefinition.html](https://hl7.org/fhir/R4/structuredefinition.html) 資源類型。
**取得 HealthLake 資料存放區的功能陳述式**
1. 收集 HealthLake `region`和 `datastoreId` 值。如需詳細資訊，請參閱[取得資料存放區屬性](managing-data-stores-describe.md)。
1. 使用 HealthLake `region`和 的收集值來建構請求的 URL`datastoreId`。同時在 URL 中包含 FHIR `metadata`元素。若要在下列範例中檢視整個 URL 路徑，請捲動至**複製**按鈕。
```
https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/metadata
```
1. 傳送 請求。FHIR `capabilities`互動使用具有 [AWS Signature 第 4 版](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)簽署通訊協定的`GET`請求。下列`curl`範例取得 所指定 HealthLake 資料存放區的功能陳述式`datastoreId`。若要檢視整個範例，請捲動至**複製**按鈕。
------
#### [ curl ]
```
curl --request GET \
'https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/metadata \
--aws-sigv4 'aws:amz:region:healthlake' \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
--header "x-amz-security-token:$AWS_SESSION_TOKEN" \
--header 'Accept: application/json'
```
------
您將會收到 HealthLake 資料存放區的 `200` HTTP 回應代碼和功能陳述式。如需詳細資訊，請參閱 **FHIR R4 文件**[https://hl7.org/fhir/R4/capabilitystatement.html](https://hl7.org/fhir/R4/capabilitystatement.html)中的 。
# HealthLake 的 FHIR 設定檔驗證
AWS HealthLake 支援基本 [FHIR R4 規格](https://hl7.org/fhir/R4)。基本 FHIR R4 規格中包含 FHIR 設定檔。設定檔用於 FHIR 資源類型，以使用基本資源類型的限制條件和/或延伸來定義更具體的資源類型定義。例如，FHIR 設定檔可以識別必要欄位，例如延伸項目和值集。資源可以支援多個設定檔。所有 HealthLake 資料存放區都支援使用 FHIR Profiles。
**注意**
將資料新增至 HealthLake 資料存放區時，*不需要*新增 FHIR 設定檔。如果在新增或更新資源時未指定 FHIR 描述檔，則資源只會根據基本 FHIR R4 結構描述進行驗證。
FHIR 資源符合的 FHIR 描述檔會在匯入 HealthLake 之前包含在資源中。因此，FHIR 設定檔會在匯入期間由 HealthLake 驗證。
FHIR 設定檔在實作指南中指定。FHIR 實作指南 (IG) 是一組說明，說明如何將 FHIR 標準用於特定用途。HealthLake 會驗證下列實作指南中定義的 FHIR 設定檔。
**支援的 FHIR 設定檔 AWS HealthLake**
| 名稱 | 版本 | 實作指南 | 功能 | 美國東部 (俄亥俄) | 美國東部 (維吉尼亞北部) | 美國西部 (奧勒岡) | 亞太地區 (孟買) | 亞太地區 (悉尼) | 加拿大 (中部) | 歐洲 (愛爾蘭) | 歐洲 (倫敦) |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 美國核心 | 3.1.1 | [http://hl7.org/fhir/us/core/STU3.1.1/](http://hl7.org/fhir/us/core/STU3.1.1/) | 預設 | X | X | X | X | X | X | X | X |
| 美國核心 | 4.0.0 | [https://hl7.org/fhir/us/core/STU4/index.html](https://hl7.org/fhir/us/core/STU4/index.html) | 支援 | X | X | X | X | X | X | X | X |
| 美國核心 | 5.0.1 | [https://hl7.org/fhir/us/core/STU5.0.1/index.html](https://hl7.org/fhir/us/core/STU5.0.1/index.html) | 支援 | X | X | X | X | X | X | X | X |
| 美國核心 | 6.1.0 | [https://hl7.org/fhir/us/core/STU6.1/index.html](https://hl7.org/fhir/us/core/STU6.1/index.html) | 支援 | X | X | X | X | X | X | X | X |
| 美國核心 | 7.0.0 | [https://hl7.org/fhir/us/core/STU7/](https://hl7.org/fhir/us/core/STU7/) | 支援 | X | X | X | X | X | X | X | X |
| 英國核心 | 2.0.1 | [https://simplifier.net/guide/uk-core-implementation-guide-stu2/Home/ProfilesandExtensions/ProfilesIndex?version=2.0.1](https://simplifier.net/guide/uk-core-implementation-guide-stu2/Home/ProfilesandExtensions/ProfilesIndex?version=2.0.1) | 支援 | X | X | X | X | | | X | X |
| CARIN 藍色按鈕 | 1.1.0 | [http://hl7.org/fhir/us/carin-bb/STU1.1/](http://hl7.org/fhir/us/carin-bb/STU1.1/) | 預設 | X | X | X | X | X | X | X | X |
| CARIN 藍色按鈕 | 1.0.0、2.0.0、2.1.0 | [https://hl7.org/fhir/us/carin-bb/history.html](https://hl7.org/fhir/us/carin-bb/history.html) | 支援 | X | X | X | X | X | X | X | X |
| Da Vinci 付款人資料交換 | 1.0.0 | [https://hl7.org/fhir/us/davinci-pdex/](https://hl7.org/fhir/us/davinci-pdex/) | 預設 | X | X | X | X | X | X | X | X |
| Da Vinci 付款人資料交換 | 2.0.0、2.1.0 | [https://hl7.org/fhir/us/davinci-pdex/history.html](https://hl7.org/fhir/us/davinci-pdex/history.html) | 支援 | X | X | X | X | X | X | X | X |
| Da Vinci 運作狀態記錄交換 (HRex) | 0.2.0 | [https://hl7.org/fhir/us/davinci-hrex/2020Sep/](https://hl7.org/fhir/us/davinci-hrex/2020Sep/) | 預設 | X | X | X | X | X | X | X | X |
| DaVinci PDEX 計畫淨額 | 1.1.0 | [https://hl7.org/fhir/us/davinci-pdex-plan-net/STU1.1/](https://hl7.org/fhir/us/davinci-pdex-plan-net/STU1.1/) | 預設 | X | X | X | X | X | X | X | X |
| DaVinci PDEX 計畫淨額 | 1.0.0 | [https://hl7.org/fhir/us/davinci-pdex-plan-net/STU1/](https://hl7.org/fhir/us/davinci-pdex-plan-net/STU1/) | 支援 | X | X | X | X | X | X | X | X |
| DaVinci Payer Data Exchange (PDex) 美國藥物配方 | 1.1.0 | [https://hl7.org/fhir/us/davinci-drug-formulary/STU1.1/](https://hl7.org/fhir/us/davinci-drug-formulary/STU1.1/) | 預設 | X | X | X | X | X | X | X | X |
| DaVinci Payer Data Exchange (PDex) 美國藥物配方 | 1.0.1、2.0.1、2.1.0 | [https://hl7.org/fhir/us/davinci-drug-formulary/history.html](https://hl7.org/fhir/us/davinci-drug-formulary/history.html) | 支援 | X | X | X | X | X | X | X | X |
| Da Vinci 臨床資料交換 (CDex) | 2.1.0 | [https://build.fhir.org/ig/HL7/davinci-ecdx/index.html](https://build.fhir.org/ig/HL7/davinci-ecdx/index.html) | 預設 | X | X | X | X | X | X | X | X |
| Da Vinci 預先授權支援 (PAS) FHIR IG | 2.1.0 | [https://hl7.org/fhir/us/davinci-pas/](https://hl7.org/fhir/us/davinci-pas/) | 預設 | X | X | X | X | X | X | X | X |
| NCQA HEDIS® 實作指南 | 0.3.1 | [https://www.ncqa.org/resources/hedis-ig-resource-page/](https://www.ncqa.org/resources/hedis-ig-resource-page/) | 預設 | X | X | X | X | | | X | X |
| 國際患者摘要 (IPS) | 2.0.0 選票 | [https://hl7.org/fhir/uv/ips/2024Sep/](https://hl7.org/fhir/uv/ips/2024Sep/) | 預設 | X | X | X | X | X | X | X | X |
| 品質指標 | 5.0.0 | [https://registry.fhir.org/package/hl7.fhir.us.cqfmeasures%7C5.0.0](https://registry.fhir.org/package/hl7.fhir.us.cqfmeasures%7C5.0.0) | 預設 | X | X | X | X | | | X | X |
| 基因體報告 | 3.0.0 | [https://build.fhir.org/ig/HL7/genomics-reporting/index.html](https://build.fhir.org/ig/HL7/genomics-reporting/index.html) | 預設 | X | X | X | X | | | X | X |
| 國家衛生局的 Ayushman Bharat Digital Mission (ABDM) | 2.0 | [https://www.nrces.in/ndhm/fhir/r4/index.html](https://www.nrces.in/ndhm/fhir/r4/index.html) | 預設 | X | X | X | X | | | X | X |
| CA Core\$1 | 1.1.0 | [https://simplifier.net/ca-core](https://simplifier.net/ca-core) | 支援 | | | | | | X | | |
| CA：eReC Pan-Canadian eReferral-eConsult | 1.1.0 | [https://simplifier.net/CA-eReC/~introduction](https://simplifier.net/CA-eReC/~introduction) | 支援 | | | | | | X | | |
| 病患摘要 加拿大版本 - (PS-CA) | 2.11 | [https://simplifier.net/PS-CA-R1/~introduction](https://simplifier.net/PS-CA-R1/~introduction) | 支援 | | | | | | X | | |
| Ontario Digital Health 藥物儲存庫 | 4.0.3 | [https://simplifier.net/ca-on-dhdr-r4/~introduction](https://simplifier.net/ca-on-dhdr-r4/~introduction) | 支援 | | | | | | X | | |
| AU 核心 | 1.0.0 | [https://hl7.org.au/fhir/core/](https://hl7.org.au/fhir/core/) | 支援 | | | | | X | | | |
| Magentus Practice Management | 1.2.16 | [https://fhir-versions.dev.geniesolutions.io/1.2.16/downloads.html](https://fhir-versions.dev.geniesolutions.io/1.2.16/downloads.html) | 支援 | | | | | X | | | |
## 驗證資源中指定的 FHIR 設定檔
若要驗證 FHIR 設定檔，請使用實作指南中指定的設定檔 URL，將其新增至個別資源的 `profile`元素。
當您將新資源新增至資料存放區時，會驗證 FHIR 設定檔。若要新增資源，您可以使用 `StartFHIRImportJob` API 操作、提出新增資源的`POST`請求，或讓 ` PUT `更新現有資源。
**Example – 查看在資源中參考哪些 FHIR 設定檔**
設定檔 URL 會新增至`"meta" : "profile"`鍵/值對中的 `profile`元素。為了清楚起見，已截斷此資源。
```
{
"resourceType": "Patient",
"id": "abcd1234efgh5678hijk9012",
"meta": {
"lastUpdated": "2023-05-30T00:48:07.8443764-07:00",
"profile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
]
}
}
```
**Example – 如何參考非預設支援的 FHIR 設定檔**
若要驗證受支援的非預設設定檔 （例如 CarinBB 1.0.0) - 在 `meta.profile`元素中新增具有版本 （以 '\$1' 分隔） 和基本設定檔 URL 的設定檔 URL。為了清楚起見，已截斷此範例資源。
```
{
"resourceType": "ExplanationOfBenefit",
"id": "sample-EOB",
"meta": {
"lastUpdated": "2024-02-02T05:56:09.4+00:00",
"profile": [
"http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-ExplanationOfBenefit-Pharmacy|1.0.0",
"http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-ExplanationOfBenefit-Pharmacy“
]
}
}
```
# HealthLake 的 FHIR R4 支援的資源類型
下表列出 支援的 FHIR R4 資源類型 AWS HealthLake。如需詳細資訊，請參閱 **FHIR R4 文件**中的[資源索引](https://hl7.org/fhir/R4/resourcelist.html)。
**HealthLake 支援的 FHIR R4 資源類型**
| | | | |
| --- |--- |--- |--- |
| 帳戶 | DetectedIssue | 發票 | 從業人員 |
| ActivityDefinition | 裝置 | 程式庫 | PractitionerRole |
| AdverseEvent | DeviceDefinition | 連結 | 程序 |
| AllergyIntolerance | DeviceMetric | 清單 | 證明 |
| 約定 | DeviceUseStatement | Location | 問卷 |
| AppointmentResponse | DeviceRequest | 量值 | QuestionnaireResponse |
| AuditEvent - 請參閱備註 | DiagnosticReport | MeasureReport | RelatedPerson |
| 二進位 | DocumentManifest | 媒體 | RequestGroup |
| BodyStructure | DocumentReference | 藥物 | ResearchStudy |
| 套件 - 請參閱備註 | EffectEvidenceSynthesis | MedicationAdministration | ResearchSubject |
| CapabilityStatement | 遇到 | MedicationDispense | RiskAssessment |
| CarePlan | Endpoint | MedicationKnowledge | RiskEvidenceSynthesis |
| CareTeam | EpisodeOfCare | MedicationRequest | Schedule |
| ChargeItem | EnrollmentRequest | MedicationStatement | ServiceRequest |
| ChargeItemDefinition | EnrollmentResponse | MessageHeader | 插槽 |
| 取得 | ExplanationOfBenefit | MolecularSequence | 樣本 |
| ClaimResponse | FamilyMemberHistory | NutritionOrder | StructureDefinition |
| Communication | 旗標 | 觀察 | StructureMap |
| CommunicationRequest | 目標 | OperationOutcome - 請參閱備註 | 物質 |
| 合成 | Group | 組織 | SupplyDelivery |
| ConceptMap | GuidanceResponse | OrganizationAffiliation | SupplyRequest |
| 條件 | HealthcareService | 參數 - 請參閱備註 | 任務 |
| 同意 | ImagingStudy | 病患 | ValueSet |
| 合約 | 預防 | PaymentNotice | VisionPrescription |
| 涵蓋範圍 | ImmunizationEvaluation | PaymentReconciliation | VerificationResult - 請參閱備註 |
| CoverageEligibilityRequest | ImmunizationRecommendation | 個人 | |
| CoverageEligibilityResponse | InsurancePlan | PlanDefinition | |
**FHIR 規格和 HealthLake**
您不能使用 FHIR `OperationOutcome``Parameters`和資源類型提出 `GET`或 `POST`請求。
**AuditEvent** — 可以建立或讀取 AuditEvent 資源，但無法更新或刪除。
**套件** — HealthLake 管理套件請求的方式有多種。如需詳細資訊，請參閱[綁定 FHIR 資源](managing-fhir-resources-bundle.md)。
**VerificationResult** — 只有 2023 年 12 月 9 日之後建立的資料存放區才支援此資源類型。
# HealthLake 的 FHIR R4 搜尋參數
使用 FHIR [https://hl7.org/fhir/R4/http.html#search](https://hl7.org/fhir/R4/http.html#search)互動，根據一些篩選條件在 HealthLake 資料存放區中搜尋一組 FHIR 資源。您可以使用 `GET`或 `POST`請求來執行`search`互動。對於涉及個人身分識別資訊 (PII) 或受保護醫療資訊 (PHI) 的搜尋，建議使用`POST`請求，因為 PII 和 PHI 會新增為請求內文的一部分，並在傳輸中加密。
**注意**
本章所述的 FHIR `search`互動是根據 HL7 FHIR R4 標準的醫療保健資料交換而建置。由於它是 HL7 FHIR 服務的表示，因此不會透過 AWS CLI 和 AWS SDKs提供。如需詳細資訊，請參閱 **FHIR R4 RESTful API 文件**[https://hl7.org/fhir/R4/http.html#search](https://hl7.org/fhir/R4/http.html#search)中的 。
您也可以使用 Amazon Athena 查詢具有 SQL 的 HealthLake 資料存放區。如需詳細資訊，請參閱整合。
HealthLake 支援下列 FHIR R4 搜尋參數子集。如需詳細資訊，請參閱[HealthLake 的 FHIR R4 搜尋參數](#reference-fhir-search-parameters)。
## 支援的搜尋參數類型
下表顯示 HealthLake 中支援的搜尋參數類型。
**支援的搜尋參數類型**
| 搜尋參數 | Description |
| --- | --- |
| \$1id | 資源 ID （非完整 URL) |
| \$1lastUpdated | 上次更新日期。伺服器可自行決定邊界精確度。 |
| \$1tag | 依資源標籤搜尋。 |
| \$1profile | 搜尋標記設定檔的所有資源。 |
| \$1安全性 | 搜尋套用至此資源的安全標籤。 |
| \$1source | 搜尋資源的來源。 |
| \$1text | 搜尋資源的敘述。 |
| createdAt | 搜尋自訂擴充功能 createdAt。 |
**注意**
下列搜尋參數僅支援 2023 年 12 月 9 日之後建立的資料存放區：\$1security， \$1source， \$1text， createdAt。
下表顯示如何根據指定資源類型的指定資料類型修改查詢字串的範例。為了清楚起見，範例欄中的特殊字元尚未編碼。若要成功進行查詢，請確定查詢字串已正確編碼。
**搜尋參數範例**
| 搜尋參數類型 | 詳細資訊 | 範例 |
| --- | --- | --- |
| Number | 搜尋指定資源中的數值。觀察到重要的數字。有效數字的數量依搜尋參數值在 中是特定的，前導零除外。允許比較字首。 | `[parameter]=100` `[parameter]=1e2` `[parameter]=lt100` |
| 日期/DateTime | 搜尋特定日期或時間。預期的格式是 `yyyy-mm-ddThh:mm:ss[Z\|(+\|-)hh:mm]`，但可能會有所不同。 接受下列資料類型：`date`、`dateTime`、`Period`、 `instant`和 `Timing`。如需在搜尋中使用這些資料類型的詳細資訊，請參閱 **FHIR R4 RESTful API 文件**中的[日期](https://www.hl7.org/fhir/search.html#date)。 允許比較字首。 | `[parameter]=eq2013-01-14` `[parameter]=gt2013-01-14T10:00` `[parameter]=ne2013-01-14` |
| String | 以區分大小寫的方式搜尋一系列字元。 同時支援 `HumanName`和 `Address`類型。如需詳細資訊，請參閱 **FHIR R4 文件**中的 [HumanName 資料類型](https://www.hl7.org/fhir/datatypes.html#HumanName)項目和[`Address`資料類型](https://www.hl7.org/fhir/datatypes.html#Address)項目。 使用`:text`修飾詞支援進階搜尋。 | `[base]/Patient?given=eve` `[base]/Patient?given:contains=eve` |
| 權杖 | 搜尋與字元字串close-to-exact相符項目，通常與一對醫療代碼值相比。 區分大小寫會連結到建立查詢時使用的程式碼系統。以訂閱為基礎的查詢有助於減少與區分大小寫相關的問題。為了清楚起見， `\|` 尚未編碼。 | `[parameter]=[system]\|[code]`：這裡`[system]`參考編碼系統，並`[code]`參考該特定系統中找到的程式碼值。 `[parameter]=[code]`：在這裡，您的輸入將符合程式碼或系統。 `[parameter]=\|[code]`：在此，您的輸入將符合程式碼，且系統屬性沒有識別符。 |
| 複合 | 使用 修飾詞`$`和 `,`操作，在單一資源類型中搜尋多個參數。 允許比較字首。 | `/Patient?language=FR,NL&language=EN` `Observation?component-code-value-quantity=http://loinc.org\|8480-6$lt60` `[base]/Group?characteristic-value=gender$mixed` |
| 數量 | 搜尋數字、系統和程式碼做為值。號碼是必要項目，但系統和程式碼是選用項目。根據數量資料類型。如需詳細資訊，請參閱 **FHIR R4 文件**中的[數量](https://www.hl7.org/fhir/datatypes.html#Quantity)。 使用以下假設語法 `[parameter]=[prefix][number]\|[system]\|[code]` | `[base]/Observation?value-quantity=5.4\|http://unitsofmeasure.org\|mg` `[base]/Observation?value-quantity=5.4\|http://unitsofmeasure.org\|mg` `[base]/Observation?value-quantity=5.4\|http://unitsofmeasure.org\|mg` `[base]/Observation?value-quantity=le5.4\|http://unitsofmeasure.org\|mg` |
| 參考資料 | 搜尋其他資源的參考。 | `[base]/Observation?subject=Patient/23` `test` |
| URI | 搜尋明確識別特定資源的字元字串。 | `[base]/ValueSet?url=http://acme.org/fhir/ValueSet/123` |
| 特別 | 根據整合式醫療 NLP 延伸模組進行搜尋。 |
## HealthLake 支援的進階搜尋參數
HealthLake 支援下列進階搜尋參數。
| 名稱 | 描述 | 範例 | 功能 |
| --- | --- | --- | --- |
| \$1include | 用來請求在搜尋請求中傳回其他資源。它會傳回由目標資源執行個體參考的資源。 | Encounter?\$1include=Encounter:subject | |
| \$1revinclude | 用來請求在搜尋請求中傳回其他資源。它會傳回參考主要資源執行個體的資源。 | Patient?\$1id=patient-identifier&\$1revinclude=Encounter:patient | |
| \$1summary | 摘要可用來請求資源的子集。 | Patient?\$1summary=text | 支援下列摘要參數：\$1summary=true、\$1summary=false、\$1summary=text、\$1summary=data。 |
| \$1elements | 請求傳回一組特定的元素，做為搜尋結果中資源的一部分。 | Patient?\$1elements=identifier,active,link | |
| \$1total | 傳回符合搜尋參數的資源數目。 | Patient?\$1total=accurate | 支援 \$1total=accurate、\$1total=none。 |
| \$1sort | 使用逗號分隔清單，指出傳回搜尋結果的排序順序。- 字首可用於逗號分隔清單中的任何排序規則，以表示遞減順序。 | Observation?\$1sort=status,-date | 支援依類型為 的欄位排序Number, String, Quantity, Token, URI, Reference。只有 2023 年 12 月 9 日之後建立的資料存放區Date才支援依 排序。最多支援 5 個排序規則。 |
| \$1count | 控制搜尋套件每頁傳回多少資源。 | Patient?\$1count=100 | 頁面大小上限為 100。 |
| chaining | 搜尋參考資源的元素。會將鏈結搜尋.導向至參考資源內的 元素。 | DiagnosticReport?subject:Patient.name=peter | |
| reverse chaining (\$1has) | 根據參考資源的資源元素來搜尋資源。 | Patient?\$1has:Observation:patient:code=1234-5 | |
`_include`
在搜尋查詢`_include`中使用 也允許傳回其他指定的 FHIR 資源。使用 `_include` 來包含向前連結的資源。
**Example – 使用 `_include` 來尋找被診斷出有口鼻的患者或患者群組**
您會搜尋指定診斷碼用於止吐`Condition`的資源類型，然後使用 `_include` 指定也要傳回該診斷`subject`的 。在 `Condition` 資源類型中， `subject`是指病患資源類型或群組資源類型。
為了清楚起見，範例中的特殊字元尚未編碼。若要讓查詢成功，請確定查詢字串已正確編碼。
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/
Condition?code=49727002&_include=Condition:subject
```
`_include:iterate` 修改器
`_include:iterate` 修飾詞允許跨兩個層級遞迴地包含參考的資源。例如
```
GET /ServiceRequest?identifier=025C0931195&_include=ServiceRequest:requester&_include:iterate=PractitionerRole:practitioner
```
將傳回 ServiceRequest、其相關聯的 PractitionerRole （透過請求者參考），然後遞迴地包含該 PractitionerRole 參考的 Practitioner。此修飾詞適用於 HealthLake 中的所有資源類型。
`_include=*` 修改器
`_include=*` 修飾詞是一種萬用字元，會自動包含搜尋結果直接參考的所有資源。例如
```
GET /ServiceRequest?specimen.accession=12345&_include=*
```
將傳回相符的 ServiceRequest 及其參考的所有資源 （例如病患、從業人員、樣本等），而不需要個別指定每個參考路徑。此修飾詞適用於 HealthLake 中的所有資源類型。
`_revinclude`
在搜尋查詢`_revinclude`中使用 也允許傳回其他指定的 FHIR 資源。使用 `_revinclude` 來包含向後連結的資源。
**Example – 使用 `_revinclude` 包含連結至特定病患的相關事件和觀察資源類型**
若要進行此搜尋，您必須先在`_id`搜尋參數中指定其識別符`Patient`來定義個人。然後，您可以使用 結構`Encounter:patient`和 指定其他 FHIR 資源`Observation:patient`。
為了清楚起見，範例中的特殊字元尚未編碼。若要讓查詢成功，請確定查詢字串已正確編碼。
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/
Patient?_id=patient-identifier&_revinclude=Encounter:patient&_revinclude=Observation:patient
```
`_summary`
在搜尋查詢`_summary`中使用 可讓使用者請求 FHIR 資源的子集。它可以包含下列其中一個值：`true, text, data, false`。任何其他值都會被視為無效。傳回的資源會在 meta.tag `'SUBSETTED'`中標示為 ，表示資源不完整。
+ `true`：傳回資源 （基本定義） 中標示為「摘要」的所有支援元素。
+ `text`：僅傳回 'text'、'id'、'meta' 元素，以及僅傳回頂層強制性元素。
+ `data`：傳回除了「文字」元素以外的所有部分。
+ `false`：傳回資源的所有部分 （多個）
在單一搜尋請求中， `_summary=text`無法與 `_include`或 `_revinclude` 搜尋參數結合。
**Example – 取得資料存放區中病患資源的「文字」元素。**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_summary=text
```
`_elements`
在搜尋查詢`_elements`中使用 允許請求特定的 FHIR 資源元素。傳回的資源會在 meta.tag `'SUBSETTED'`中標示為 ，表示資源不完整。
`_elements` 參數包含以逗號分隔的基本元素名稱清單，例如在資源的根層級定義的元素。只有列出的元素才會傳回。如果`_elements`參數值包含無效的元素，伺服器會忽略它們並傳回強制性元素和有效的元素。
`_elements` 不適用於包含的資源 （搜尋模式為 的傳回資源`include`)。
在單一搜尋請求中， `_elements`無法與`_summary`搜尋參數結合。
**Example – 取得 HealthLake 資料存放區中病患資源的「識別符」、「作用中」、「連結」元素。**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_elements=identifier,active,link
```
`_total`
在搜尋查詢`_total`中使用 會傳回符合所請求搜尋參數的資源數量。HealthLake 會在搜尋`Bundle.total`回應的 中傳回相符資源的總數 （傳回的搜尋模式為 的資源`match`)。
`_total` 支援 `accurate`、 `none` 參數值。 `_total=estimate` 不支援 。任何其他值都會被視為無效。 `_total` 不適用於包含的資源 （傳回的 資源，其搜尋模式為 `include`)。
**Example – 取得資料存放區中病患資源的總數：**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_total=accurate
```
`_sort`
在搜尋查詢`_sort`中使用 會依特定順序排列結果。結果會根據排序規則的逗號分隔清單，依優先順序排序。排序規則應該是有效的搜尋參數。任何其他值都會被視為無效。
在單一搜尋請求中，您最多可以使用 5 個排序搜尋參數。您可以選擇使用`-`字首來表示遞減順序。伺服器預設會依遞增順序排序。
支援的排序搜尋參數類型為：`Number, String, Date, Quantity, Token, URI, Reference`。如果搜尋參數是指巢狀元素，則不支援此搜尋參數進行排序。例如，搜尋資源類型的 'name' 病患參考具有 HumanName 資料類型的 Patient.name 元素會被視為巢狀。因此，不支援依「名稱」排序病患資源。
**Example – 在資料存放區中取得病患資源，並依出生日期遞增排序：**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_sort=birthdate
```
`_count`
參數`_count`定義為伺服器關於在單一頁面中應傳回多少資源的指示。
頁面大小上限為 100。大於 100 的任何值都是無效的。`_count=0`不支援 。
**Example – 搜尋病患資源，並將搜尋頁面大小設定為 25：**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_count=25
```
`Chaining and Reverse Chaining(_has)`
在 FHIR 中鏈結和反向鏈結可提供更有效率且更精簡的方式來取得互連的資料，減少對多個個別查詢的需求，並讓開發人員和使用者更方便地擷取資料。
如果任何層級的遞迴傳回超過 100 個結果，HealthLake 將傳回 4xx，以保護資料存放區免於超載並導致多個分頁。
**Example – 鏈結 - 取得所有 DiagnosticReport，其是指病患名稱為 Peter 的 病患。**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/DiagnosticReport?subject:Patient.name=peter
```
**Example – 反向鏈結 - 取得病患資源，其中病患資源由至少一個觀察參考，其中觀察的程式碼為 1234，而觀察是指病患搜尋參數中的病患資源。**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_has:Observation:patient:code=1234
```
## 支援的搜尋修飾詞
搜尋修飾詞會與字串型欄位搭配使用。HealthLake 中的所有搜尋修飾詞都使用布林式邏輯。例如，您可以`:contains`指定 指定較大的字串欄位應包含一個小字串，以便將其包含在搜尋結果中。
**支援的搜尋修飾詞**
| 搜尋修飾詞 | Type |
| --- | --- |
| ：missing | 除了 之外的所有參數 Composite |
| ：exact | String |
| ：包含 | String |
| ：not | 權杖 |
| ：text | 權杖 |
| ：識別符 | 參考資料 |
| ：以下 | URI |
## 支援的搜尋比較器
您可以使用搜尋比較器來控制搜尋中相符項目的性質。您可以在搜尋數字、日期和數量欄位時使用比較器。下表列出 HealthLake 支援的搜尋比較器及其定義。
**支援的搜尋比較器**
| 搜尋比較程式 | Description |
| --- | --- |
| eq | 資源中 參數的值等於提供的值。 |
| ne | 資源中 參數的值不等於提供的值。 |
| gt | 資源中 參數的值大於提供的值。 |
| lt | 資源中 參數的值小於提供的值。 |
| ge | 資源中 參數的值大於或等於提供的值。 |
| le | 資源中 參數的值小於或等於提供的值。 |
| sa | 資源中 參數的值會在提供的值之後啟動。 |
| eb | 資源中 參數的值會在提供的值之前結束。 |
## HealthLake 不支援 FHIR 搜尋參數
HealthLake 支援所有 FHIR 搜尋參數，但下表所列的參數除外。如需 FHIR 搜尋參數的完整清單，請參閱 [FHIR 搜尋參數登錄檔。](https://hl7.org/fhir/R4/searchparameter-registry.html)
**不支援的搜尋參數**
| | |
| --- |--- |
| Bundle-composition | Location-near |
| 套件識別符 | Consent-source-reference |
| Bundle-message | 合約患者 |
| Bundle-type | 資源內容 |
| Bundle-timestamp | 資源查詢 |
# `$operations` 適用於 HealthLake 的 FHIR R4
FHIR \$1 操作 （也稱為「美元操作」) 是特殊的伺服器端函數，超出 FHIR `Read`規格中的標準 CRUD (`Create`、`Update`、、`Delete`) 操作。這些操作會以「\$1」字首識別，並啟用複雜處理、資料轉換和大量操作，這些操作在使用標準 REST API 呼叫時難以或效率不佳。\$1 操作可以在系統層級、資源類型層級或特定資源執行個體上叫用，提供與 FHIR 資料互動的彈性方式。 AWS HealthLake 支援多個 FHIR`$operations`。如需其他詳細資訊，請參閱以下每個個別頁面。
**Topics**
+ [HealthLake 的 FHIR R4 `$attribution-status`操作](reference-fhir-operations-attribution-status.md)
+ [使用 刪除資源類型 `$bulk-delete`](reference-fhir-operations-bulk-delete.md)
+ [`$bulk-member-match` HealthLake 的 操作](reference-fhir-operations-bulk-member-match.md)
+ [HealthLake 的 FHIR R4 `$confirm-attribution-list`操作](reference-fhir-operations-confirm-attribution-list.md)
+ [HealthLake 的 FHIR R4 `$davinci-data-export`操作](reference-fhir-operations-davinci-data-export.md)
+ [使用 產生臨床文件 `$document`](reference-fhir-operations-document.md)
+ [使用 永久移除資源 `$erase`](reference-fhir-operations-erase.md)
+ [使用 取得患者資料 `Patient/$everything`](reference-fhir-operations-everything.md)
+ [使用 擷取 ValueSet 程式碼 `$expand`](reference-fhir-operations-expand.md)
+ [使用 FHIR 匯出 HealthLake 資料 `$export`](reference-fhir-operations-export.md)
+ [HealthLake 的 FHIR `$inquire`操作](reference-fhir-operations-inquire.md)
+ [使用 擷取概念詳細資訊 `$lookup`](reference-fhir-operations-lookup.md)
+ [`$member-add` HealthLake 的 操作](reference-fhir-operations-member-add.md)
+ [`$member-match` HealthLake 的 操作](reference-fhir-operations-member-match.md)
+ [`$member-remove` HealthLake 的 操作](reference-fhir-operations-member-remove.md)
+ [使用 移除病患室資源 `$purge`](reference-fhir-operations-purge.md)
+ [HealthLake 的 FHIR `$questionnaire-package`操作](reference-fhir-operations-questionnaire-package.md)
+ [HealthLake 的 FHIR `$submit`操作](reference-fhir-operations-submit.md)
+ [使用 驗證 FHIR 資源 `$validate`](reference-fhir-operations-validate.md)
# HealthLake 的 FHIR R4 `$attribution-status`操作
擷取特定成員的屬性狀態，傳回包含與病患相關所有屬性資源的套件。此操作是 [FHIR 成員屬性 (ATR) 清單 IG 2.1.0 實作的一部分。](https://build.fhir.org/ig/HL7/davinci-atr/spec.html)
## Endpoint
```
POST [base]/Group/[id]/$attribution-status
```
## 請求參數
操作接受下列選用參數：
| 參數 | 類型 | 說明 |
| --- | --- | --- |
| memberId | 識別符 | 請求其屬性狀態之成員的 MemberId |
| patientReference | 參考資料 | 生產者系統中病患資源的參考 |
**注意**
`patientReference` 可以提供 `memberId`或 ，或兩者都用於驗證目的。
## 請求範例
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "memberId",
"valueIdentifier": {
"system": "http://example.org",
"value": "MBR123456789"
}
},
{
"name": "patientReference",
"valueReference": {
"reference": "Patient/patient-123",
"display": "John Doe"
}
}
]
}
```
## 回應
傳回包含與病患相關屬性資源的套件：
| 資源 | 基數 | Location |
| --- | --- | --- |
| 病患 | 1..1 | Group.member.entity |
| 涵蓋範圍 | 0..1 | Group.member.extension：coverageReference |
| Organization/Practitioner/PractitionerRole | 0..1 | Group.member.extension：attributedProvider |
| 任何資源 | 0..1 | Group.member.extension：associatedData |
### 回應範例
```
{
"resourceType": "Bundle",
"id": "bundle-response",
"meta": {
"lastUpdated": "2014-08-18T01:43:33Z"
},
"type": "collection",
"entry": [
{
"fullUrl": "http://example.org/fhir/Patient/12423",
"resource": {
"resourceType": "Patient",
"id": "12423",
"meta": {
"versionId": "1",
"lastUpdated": "2014-08-18T01:43:31Z"
},
"active": true,
"name": [
{
"use": "official",
"family": "Chalmers",
"given": ["Peter", "James"]
}
],
"gender": "male",
"birthDate": "1974-12-25"
}
},
{
"fullUrl": "http://example.org/fhir/Coverage/123456",
"resource": {
"resourceType": "Coverage",
"id": "1"
// ... additional Coverage resource details
}
},
{
"fullUrl": "http://example.org/fhir/Organization/666666",
"resource": {
"resourceType": "Organization",
"id": "2"
// ... additional Organization resource details
}
}
]
}
```
## 錯誤處理
操作會處理下列錯誤條件：
| 錯誤 | HTTP 狀態 | Description |
| --- | --- | --- |
| 無效的操作請求 | 400 | 不符合的請求參數或結構 |
| 找不到群組資源 | 404 | 指定的群組 ID 不存在 |
| 找不到病患資源 | 404 | 指定的病患參考不存在 |
## 授權和安全性
SMART 範圍需求
用戶端必須具有適當的權限，才能讀取群組資源和相關歸因資源
標準 FHIR 授權機制適用於所有操作
# 使用 刪除資源類型 `$bulk-delete`
AWS HealthLake 支援 `$bulk-delete`操作，可刪除資料存放區中特定類型的所有資源。當您需要：
+ 執行季節性稽核和清除
+ 大規模管理資料生命週期
+ 移除特定資源類型
+ 遵循資料保留政策
## Usage
您可以使用 POST 方法叫用 `$bulk-delete`操作：
```
POST [base]/[ResourceType]/$bulk-delete?isHardDelete=false&deleteAuditEvent=true
```
## Parameters
| 參數 | Type | 必要 | 預設 | Description |
| --- | --- | --- | --- | --- |
| isHardDelete | 布林值 | 否 | false | 當為 true 時， 會從儲存體永久移除資源 |
| deleteAuditEvent | 布林值 | 否 | true | 為 true 時， 會刪除相關聯的稽核事件 |
| \$1since | string | 否 | 資料存放區建立時間 | 輸入時， 會根據資源的lastModified時間選取開始截止時間來尋找資源。無法與開始或結束搭配使用 |
| start | string | 否 | 資料存放區建立時間 | 輸入時， 會根據資源的lastModified時間選取截止時間來尋找資源。可與 end 搭配使用 |
| end | string | 否 | 任務提交時間 | 輸入時， 會根據資源的lastModified時間選取結束截止時間以尋找資源 |
## 範例
**範例請求**
```
POST [base]/Observation/$bulk-delete?isHardDelete=false
```
**回應範例**
```
{
"jobId": "jobId",
"jobStatus": "SUBMITTED"
}
```
## 任務狀態
若要檢查大量刪除任務的狀態：
```
GET [base]/$bulk-delete/[jobId]
```
操作會傳回任務狀態資訊：
```
{
"datastoreId": "datastoreId",
"jobId": "jobId",
"status": "COMPLETED",
"submittedTime": "2025-10-09T15:09:51.336Z"
}
```
## Behavior (行為)
`$bulk-delete` 操作：
1. 以非同步方式處理大量資源
1. 維護 ACID 交易的資料完整性
1. 提供具有資源刪除計數的任務狀態追蹤
1. 支援軟式和硬式刪除模式
1. 包括刪除活動的完整稽核記錄
1. 允許選擇性刪除歷史版本和稽核事件
## 稽核記錄
`$bulk-delete` 操作會記錄為 StartFHIRBulkDeleteJob 和 DescribeFHIRBulkDeleteJob，其中包含詳細的操作資訊。
## 限制
+ 當 `isHardDelete` 設為 true 時，硬刪除的資源不會出現在搜尋結果或`_history`查詢中。
+ 透過此操作刪除的資源在處理期間可能暫時無法存取
+ 僅根據歷史版本調整儲存計量 - deleteVersionHistory=false 不會調整資料存放區儲存
# `$bulk-member-match` HealthLake 的 操作
AWS HealthLake 支援非同步處理多個成員比對請求`$bulk-member-match`的操作。此操作可讓醫療保健組織在單一大量請求中使用人口統計和涵蓋範圍資訊，在不同的醫療保健系統中有效率地比對數百個成員的唯一識別符。此功能對於大規模payer-to-payer資料交換、成員轉換和 CMS 合規要求至關重要，並遵循 FHIR [規格](https://build.fhir.org/ig/HL7/davinci-epdx/OperationDefinition-BulkMemberMatch.html)。
**注意**
`$bulk-member-match` 操作是以目前實驗性且可能會有所變更的基礎 FHIR 規格為基礎。隨著規格的演進，此 API 的行為和界面也會隨之更新。建議開發人員監控 AWS HealthLake 版本備註和相關的 FHIR 規格更新，以隨時掌握可能影響其整合的任何變更。
當您需要執行下列動作時，此操作特別有用：
+ 在開放註冊期間大規模處理成員比對
+ 促進付款人之間的大量成員轉換
+ 支援大規模 CMS 合規資料交換需求
+ 有效率地比對跨醫療保健網路的成員群組
+ 將 API 呼叫降至最低，並提高大量比對案例的操作效率
## Usage
`$bulk-member-match` 操作是使用 POST 方法在群組資源上調用的非同步操作：
```
POST [base]/Group/$bulk-member-match
```
提交大量比對請求後，您可以使用下列方式輪詢任務狀態：
```
GET [base]/$bulk-member-match-status/{jobId}
```
## 支援的參數
HealthLake 支援下列 FHIR `$bulk-member-match` 參數：
| 參數 | Type | 必要 | Description |
| --- | --- | --- | --- |
| `MemberPatient` | 病患 | 是 | 包含要比對之成員人口統計資訊的患者資源。 |
| `CoverageToMatch` | 涵蓋範圍 | 是 | 用於比對現有記錄的涵蓋資源。 |
| `CoverageToLink` | 涵蓋範圍 | 否 | 比對程序期間要連結的覆蓋資源。 |
| `Consent` | 同意 | 是 | 授權用途的同意資源也會儲存。這與*不需要*同意的個別`$member-match`操作不同。 |
## 提交大量成員比對任務的 POST 請求
下列範例顯示提交大量成員比對任務的 POST 請求。每個成員都會包裝在`MemberBundle`參數中`MemberPatient`，其中包含必要的 `CoverageToMatch`、 和 `Consent` 資源，以及選用的 `CoverageToLink`。
```
POST [base]/Group/$bulk-member-match
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "MemberBundle",
"part": [
{
"name": "MemberPatient",
"resource": {
"resourceType": "Patient",
"identifier": [
{
"system": "http://example.org/patient-id",
"value": "patient-0"
}
],
"name": [
{
"family": "Smith",
"given": ["James"]
}
],
"gender": "male",
"birthDate": "1950-01-01"
}
},
{
"name": "CoverageToMatch",
"resource": {
"resourceType": "Coverage",
"status": "active",
"identifier": [
{
"system": "http://example.org/coverage-id",
"value": "cov-0"
}
],
"subscriberId": "sub-0",
"beneficiary": {
"reference": "Patient/patient123"
},
"relationship": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
"code": "self"
}
]
},
"payor": [
{
"reference": "Organization/org123"
}
]
}
},
{
"name": "Consent",
"resource": {
"resourceType": "Consent",
"status": "active",
"scope": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentscope",
"code": "patient-privacy"
}
]
},
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "IDSCL"
}
]
}
],
"patient": {
"reference": "Patient/patient123"
},
"performer": [
{
"reference": "Patient/patient123"
}
],
"sourceReference": {
"reference": "http://example.org/DocumentReference/consent-source"
},
"policy": [
{
"uri": "http://hl7.org/fhir/us/davinci-hrex/StructureDefinition-hrex-consent.html#regular"
}
],
"provision": {
"type": "permit",
"period": {
"start": "2024-01-01",
"end": "2025-12-31"
},
"actor": [
{
"role": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
"code": "performer"
}
]
},
"reference": {
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "9876543210"
},
"display": "Old Health Plan"
}
},
{
"role": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "IRCP"
}
]
},
"reference": {
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "0123456789"
},
"display": "New Health Plan"
}
}
],
"action": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentaction",
"code": "disclose"
}
]
}
]
}
}
},
{
"name": "CoverageToLink",
"resource": {
"resourceType": "Coverage",
"status": "active",
"identifier": [
{
"system": "http://example.org/coverage-link-id",
"value": "cov-link-0"
}
],
"subscriberId": "new-sub-0",
"beneficiary": {
"reference": "Patient/patient123"
},
"relationship": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
"code": "self"
}
]
},
"payor": [
{
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "0123456789"
},
"display": "New Health Plan"
}
]
}
}
]
}
]
}
```
## 使用輸出完成任務回應
當任務完成時，回應會包含任務中繼資料和 FHIR 參數資源，其中包含分類相符結果的三個群組資源。
```
{
"datastoreId": "datastoreId",
"jobId": "jobId",
"status": "COMPLETED",
"submittedTime": "2026-03-20T18:45:26.321Z",
"numberOfMembers": 3,
"numberOfMembersProcessedSuccessfully": 3,
"numberOfMembersWithCustomerError": 0,
"numberOfMembersWithServerError": 0,
"output": {
"resourceType": "Parameters",
"meta": {
"profile": [
"http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/pdex-parameters-multi-member-match-bundle-out"
]
},
"parameter": [
{
"name": "MatchedMembers",
"resource": {
"resourceType": "Group",
"id": "group1",
"text": {
"status": "generated",
"div": "Matched members group
"
},
"contained": [
{
"resourceType": "Patient",
"id": "1",
"identifier": [
{
"system": "http://example.org/patient-id",
"value": "patient-0"
}
],
"name": [
{
"family": "Smith",
"given": ["James"]
}
],
"gender": "male",
"birthDate": "1950-01-01"
}
],
"type": "person",
"actual": true,
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/us/davinci-pdex/CodeSystem/PdexMultiMemberMatchResultCS",
"code": "match",
"display": "Matched"
}
]
},
"quantity": 1,
"member": [
{
"entity": {
"extension": [
{
"url": "http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/base-ext-match-parameters",
"valueReference": {
"reference": "#1"
}
}
],
"reference": "Patient/patient123"
}
}
]
}
},
{
"name": "NonMatchedMembers",
"resource": {
"resourceType": "Group",
"id": "Group2",
"text": {
"status": "generated",
"div": "Non-matched members group
"
},
"contained": [
{
"resourceType": "Patient",
"id": "1",
"identifier": [
{
"system": "http://example.org/patient-id",
"value": "patient-501"
}
],
"name": [
{
"family": "Carter",
"given": ["Emily"]
}
],
"gender": "female",
"birthDate": "1985-06-15"
}
],
"type": "person",
"actual": true,
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/us/davinci-pdex/CodeSystem/PdexMultiMemberMatchResultCS",
"code": "nomatch",
"display": "Not Matched"
}
]
},
"quantity": 1,
"member": [
{
"entity": {
"extension": [
{
"url": "http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/base-ext-match-parameters",
"valueReference": {
"reference": "#1"
}
}
],
"reference": "Patient/patient123"
}
}
]
}
},
{
"name": "ConsentConstrainedMembers",
"resource": {
"resourceType": "Group",
"id": "group3",
"text": {
"status": "generated",
"div": "Consent constrained members group
"
},
"contained": [
{
"resourceType": "Patient",
"id": "1",
"identifier": [
{
"system": "http://example.org/patient-id",
"value": "patient-502"
}
],
"name": [
{
"family": "Nguyen",
"given": ["David"]
}
],
"gender": "male",
"birthDate": "1972-11-22"
}
],
"type": "person",
"actual": true,
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/us/davinci-pdex/CodeSystem/PdexMultiMemberMatchResultCS",
"code": "consentconstraint",
"display": "Consent Constraint"
}
]
},
"quantity": 1,
"member": [
{
"entity": {
"extension": [
{
"url": "http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/base-ext-match-parameters",
"valueReference": {
"reference": "#1"
}
}
],
"reference": "Patient/123"
}
}
]
}
}
]
}
}
```
## 輸出群組資源
已完成的任務會傳回包含三個群組資源的參數資源：
**MatchedMembers 群組**
包含所有成功配對成員的患者參考，且未分類為同意限制條件。
`Group.quantity` 欄位包含其各自群組中的成員總數。
**NonMatchedMembers 群組**
包含對找不到相符項目或已識別多個相符項目之成員的參考。
**ConsentConstrainedMembers 群組**
包含所有成功配對成員的患者參考，其中同意限制會阻止資料共用。當下列兩種條件都存在時，同意資源會被視為受限：
+ **政策 URI 結尾`#sensitive`**為 - 這是最清晰、最直接的訊號。提交付款人明確表示：「此成員的資料很敏感 — 請謹慎處理。」
```
"policy": [{ "uri": "...hrex-consent.html#sensitive" }]
```
+ **最上層佈建類型為 `deny`** — 成員已廣泛拒絕資料共用。
```
"provision": { "type": "deny" }
```
## 與 \$1davinci-data-export 整合
傳回的 MatchedMembers 群組資源`$bulk-member-match`可以直接與 `$davinci-data-export`操作搭配使用，以擷取大量成員資料：
```
POST [base]/Group/{matched-group-id}/$davinci-data-export
GET [base]/Group/{matched-group-id}
```
此整合可讓您在初次大量識別相符成員的高效工作流程，然後使用產生的群組資源匯出其完整的運作狀態記錄。
## 效能特性
`$bulk-member-match` 操作專為大量處理而設計，並以非同步方式執行：
+ **並行**：每個資料存放區最多 5 個並行操作。
+ **可擴展性**：每個請求最多可處理 500 個成員 (5 MB 承載限制）。
+ **平行操作**：與並行匯入、匯出或大量刪除操作相容。
## Authorization
API 在 FHIR 授權通訊協定上使用 SMART 搭配下列必要範圍：
+ `system/Patient.read` — 搜尋和比對患者資源時必填。
+ `system/Coverage.read` — 驗證涵蓋範圍資訊時需要。
+ `system/Group.write` — 建立結果群組資源時需要。
+ `system/Organization.read` — 有條件，如果涵蓋範圍參考組織則為必要。
+ `system/Practitioner.read` — 有條件，如果涵蓋範圍參考從業人員則為必要。
+ `system/PractitionerRole.read` — 有條件，如果涵蓋範圍參考從業人員角色則為必要。
+ `system/Consent.write` — 有條件，如果提供同意資源則為必要。
此操作也支援程式設計存取的 AWS IAM Signature 第 4 版 (SigV4) 授權。
## 錯誤處理
操作會處理下列錯誤條件：
+ **400 錯誤的請求**：無效的請求格式、缺少必要的參數或承載超過大小限制 (500 個成員或 5 MB)。
+ **422 無法處理的實體**：在任務執行期間處理錯誤。
+ **個別成員錯誤**：當特定成員無法處理時，操作會繼續保留剩餘成員，並在 NonMatchedMembers 群組中包含錯誤詳細資訊，並具有適當的原因代碼。例如，`MemberBundle`缺少 `birthDate` 參數且具有患者 的 將傳回下列錯誤：
```
"errors": [
{
"memberIndex": 1,
"jsonBlob": {
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "invalid",
"diagnostics": "MemberPatient.birthDate is required"
}
],
"statusCode": 400
}
}
]
```
錯誤詳細資訊可透過狀態輪詢端點取得，包括：
+ `numberOfMembersWithCustomerError`：發生驗證或輸入錯誤的成員計數。
+ `numberOfMembersWithServerError`：發生伺服器端處理錯誤的成員計數。
## 相關的 操作
+ [`$member-match` HealthLake 的 操作](reference-fhir-operations-member-match.md) — 個別成員比對操作。
+ [HealthLake 的 FHIR R4 `$davinci-data-export`操作](reference-fhir-operations-davinci-data-export.md) — 使用群組資源大量匯出資料。
+ [`$operations` 適用於 HealthLake 的 FHIR R4](reference-fhir-operations.md) — 支援操作的完整清單。
# HealthLake 的 FHIR R4 `$confirm-attribution-list`操作
向生產者指出消費者不再需要對屬性清單進行變更。此操作會透過從清單中移除非作用中的成員、將狀態變更為「最終」，以及確認操作，來完成歸因清單。此操作是 [FHIR 成員屬性 (ATR) List IG 2.1.0 實作的一部分。](https://build.fhir.org/ig/HL7/davinci-atr/spec.html)
## Endpoint
```
POST [base]/Group/[id]/$confirm-attribution-list
```
## 請求
不需要參數。
```
POST [base]/Group/[id]/$confirm-attribution-list
```
## 回應
傳回 HTTP 201 與確認訊息。
### 回應範例
```
HTTP Status Code: 201
{
"resourceType": "Parameters",
"parameter": [
{
"name": "message",
"valueString": "Accepted."
}
]
}
```
## 確認後的群組狀態
確認成功後，群組資源的屬性清單狀態會設為「最終」：
```
{
"resourceType": "Group",
"id": "fullexample",
"extension": [
{
"url": "http://hl7.org/fhir/us/davinci-atr/StructureDefinition/ext-attributionListStatus",
"valueCode": "final"
}
]
// ... other Group properties
}
```
## 錯誤處理
操作會處理下列錯誤條件：
| 錯誤 | HTTP 狀態 | Description |
| --- | --- | --- |
| 無效的操作請求 | 400 | 不符合的請求參數或結構 |
| 找不到群組資源 | 404 | 指定的群組 ID 不存在 |
## 授權和安全性
SMART 範圍需求
用戶端必須具有適當的權限，才能讀取群組資源和相關歸因資源
對於 `$confirm-attribution-list`，用戶端也必須具有寫入權限才能修改群組資源
標準 FHIR 授權機制適用於所有操作
# HealthLake 的 FHIR R4 `$davinci-data-export`操作
`$davinci-data-export` 操作是一種非同步 FHIR 操作，可用來從中匯出醫療保健資料 AWS HealthLake。此操作支援多種匯出類型，包括成員屬性 (ATR)、PDex 提供者存取、Payer-to-Payer和成員存取 APIs。它是標準 FHIR `$export`操作的特殊版本，旨在符合 DaVinci 實作指南的要求。
## 主要功能
+ *非同步處理*：遵循標準 FHIR 非同步請求模式
+ *群組層級匯出*：匯出特定群組資源中成員的資料
+ *多種匯出類型*：支援 ATR （成員屬性）、PDex 提供者存取、Payer-to-Payer和成員存取 APIs
+ *全面的設定檔支援*：包括美國核心、CARIN 藍色按鈕和 PDex 設定檔
+ *彈性篩選*：支援依病患、資源類型和時間範圍進行篩選
+ *NDJSON 輸出*：以換行分隔 JSON 格式提供資料
## 操作端點
```
GET [base]/Group/[id]/$davinci-data-export
POST [base]/Group/[id]/$davinci-data-export
```
## 請求參數
| 參數 | 基數 | Description |
| --- | --- | --- |
| patient | 0..\$1 | 要匯出其資料的特定成員。省略時，會匯出群組中的所有成員。 |
| \$1type | 0..1 | 要匯出的以逗號分隔的 FHIR 資源類型清單。 |
| \$1since | 0..1 | 僅包含在此日期和時間之後更新的資源。 |
| \$1until | 0..1 | 僅包含在此日期和時間之前更新的資源。 |
| exportType | 0..1 | 要執行的匯出類型。有效值：hl7.fhir.us.davinci-atr、hl7.fhir.us.davinci-pdex、hl7.fhir.us.davinci-pdex.p2p、hl7.fhir.us.davinci-pdex.member。預設：hl7.fhir.us.davinci-atr。 |
| \$1includeEOB2xWoFinancial | 0..1 | 指定是否要在移除財務資料時包含 CARIN BB 2.x ExplanationOfBenefit 資源。預設：false。 |
### 支援的資源類型
支援的資源類型取決於您指定的匯出類型。對於 ATR 匯出，支援下列資源類型：
+ `Group`
+ `Patient`
+ `Coverage`
+ `RelatedPerson`
+ `Practitioner`
+ `PractitionerRole`
+ `Organization`
+ `Location`
對於 PDex 匯出 (Provider Access、Payer-to-Payer 和 Member Access)，除了上述類型之外，還支援所有臨床和宣告資源類型。如需支援資源類型的完整清單，請參閱[美國核心實作指南 (STU 6.1)](https://hl7.org/fhir/us/core/STU6.1/)、[CARIN 藍色按鈕實作指南](https://hl7.org/fhir/us/carin-bb/)，以及 [Da Vinci 預先授權支援實作指南](https://hl7.org/fhir/us/davinci-pas/)。
## 匯出類型
`$davinci-data-export` 操作支援下列匯出類型。您可以使用 `exportType` 參數指定匯出類型。
| 匯出類型 | 用途 | 資料範圍 | 時間限制 |
| --- | --- | --- | --- |
| hl7.fhir.us.davinci-atr | 成員屬性清單 | 屬性相關資源 | 無 |
| hl7.fhir.us.davinci-pdex | 提供者存取 API | 屬性患者的臨床和宣告資料 | 5 年 |
| hl7.fhir.us.davinci-pdex.p2p | Payer-to-Payer交換 | 保險轉換的歷史成員資料 | 5 年 |
| hl7.fhir.us.davinci-pdex.member | 成員存取 API | 成員自己的運作狀態資料 | 5 年 |
**注意**
對於 PDex 匯出，5 年時間限制不適用於 ATR 資源類型 (`Group`、`Patient`、`Coverage`、`RelatedPerson`、`Practitioner`、`PractitionerRole``Organization`、)`Location`。無論存留期為何，一律都會包含這些資源。
### ATR (hl7.fhir.us：//.davinci-atr)
使用 ATR 匯出類型，您可以匯出成員屬性清單資料。使用此匯出類型來擷取群組內成員的屬性相關資源。如需詳細資訊，請參閱 [Da Vinci ATR 匯出操作](https://build.fhir.org/ig/HL7/davinci-atr/OperationDefinition-davinci-data-export.html)。
支援的資源類型
`Group`, `Patient`, `Coverage`, `RelatedPerson`, `Practitioner`, `PractitionerRole`, `Organization`, `Location`
時間篩選
不會套用時間篩選。無論日期為何，都會匯出所有相符的資源。
### PDex 匯出類型
所有 PDex 匯出類型共用相同的支援設定檔和篩選邏輯。如需詳細資訊，請參閱 [Da Vinci PDex 提供者存取 API](https://build.fhir.org/ig/HL7/davinci-epdx/provider-access-api.html)。支援下列設定檔：
+ 美國核心 3.1.1、6.1.0 和 7.0.0
+ PDex 事前授權 （不支援成員存取）
+ CARIN BB 2.x 基礎描述檔：住院機構、門診機構、專業NonClinician、口頭、藥學
提供者存取 (`hl7.fhir.us.davinci-pdex`)
讓網路內提供者擷取歸因患者的患者資料。
Payer-to-Payer(`hl7.fhir.us.davinci-pdex.p2p`)
當患者變更保險時，啟用付款人之間的資料交換。
成員存取 (`hl7.fhir.us.davinci-pdex.member`)
可讓成員存取自己的運作狀態資料。此匯出類型可能包含宣告資源中的財務資料。
## 設定檔支援和包含邏輯
對於 PDex 匯出， `$davinci-data-export`操作會使用 `meta.profile`元素中的設定檔宣告來決定匯出中要包含哪些資源。
### ExplanationOfBenefit 資源處理
`ExplanationOfBenefit` (EOB) 資源會根據其`meta.profile`宣告從 PDex 匯出中包含或排除：
+ 匯出會排除具有 CARIN BB 1.x 設定檔的 ExplanationOfBenefit 資源。
+ 匯出會排除未設定 ExplanationOfBenefit 資源。 `meta.profile`
+ 一律包含具有 CARIN BB 2.x Basis 描述檔的 ExplanationOfBenefit 資源。
+ 根據預設，會排除具有包含財務資料的 CARIN BB 2.x 設定檔的 ExplanationOfBenefit 資源。設定 `_includeEOB2xWoFinancial=true` 時，它們會包含在財務資料分割中，並將資源轉換為對應的基礎設定檔。
+ 一律包含具有 PDex 預先授權設定檔的 ExplanationOfBenefit 資源。
### 財務資料轉換
當您設定 時`_includeEOB2xWoFinancial=true`，此操作會移除財務資料，將 [CARIN BB 2.x](https://hl7.org/fhir/us/carin-bb/) ExplanationOfBenefit 資源轉換為其對應的 Basis 設定檔。例如，`C4BB ExplanationOfBenefit Oral`資源會轉換為 `C4BB ExplanationOfBenefit Oral Basis`，這會根據 FHIR 規格從記錄分割財務資料。
下列財務資料元素會在轉換期間移除：
+ `total` 元素上的所有切片
+ 具有`amounttype`配量的所有`adjudication`元素
+ 包含金額資訊的所有`item.adjudication`元素
此操作也會在轉換期間更新設定檔中繼資料：
+ `meta.profile` 已更新為 Basis 設定檔正式 URL
+ 版本已更新為 CARIN BB 2.x Basis 版本
+ 不會修改資料存放區中的現有資源
+ 匯出的資源不會保留回資料存放區
### 設定檔偵測規則
操作使用下列規則來偵測和驗證設定檔：
+ 版本偵測是以`meta.profile`正式 URLs為基礎
+ 如果任何宣告的設定檔符合匯出條件，則會包含資源
+ 設定檔驗證會在匯出處理期間進行
## PDex 匯出的五年時間篩選
對於所有 PDex 匯出類型，HealthLake 會根據資源上次更新的時間套用 5 年的時間篩選條件。暫時篩選條件適用於下列核心屬性資源類型以外的所有資源，無論使用期限為何，一律會匯出這些資源：
+ `Patient`
+ `Coverage`
+ `Organization`
+ `Practitioner`
+ `PractitionerRole`
+ `RelatedPerson`
+ `Location`
+ `Group`
這些管理和人口統計資源是豁免的，因為它們提供匯出資料的基本內容。ATR 匯出不受任何時間篩選的限制。
## 請求範例
下列範例示範如何啟動不同匯出類型的匯出任務。
*ATR 匯出*
```
GET https://healthlake.{region}.amazonaws.com/datastore/{datastoreId}/r4/Group/example-group/$davinci-data-export?_type=Group,Patient,Coverage,Practitioner,Organization&exportType=hl7.fhir.us.davinci-atr
POST https://healthlake.{region}.amazonaws.com/datastore/{datastoreId}/r4/Group/example-group/$davinci-data-export?_type=Group,Patient,Coverage,Practitioner,Organization&exportType=hl7.fhir.us.davinci-atr
Content-Type: application/json
{
"DataAccessRoleArn": "arn:aws:iam::444455556666:role/your-healthlake-service-role",
"JobName": "attribution-export-job",
"OutputDataConfig": {
"S3Configuration": {
"S3Uri": "s3://your-export-bucket/EXPORT-JOB",
"KmsKeyId": "arn:aws:kms:region:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
}
}
```
*使用 ExplanationOfBenefit 財務資料移除來匯出供應商存取*
```
GET https://healthlake.{region}.amazonaws.com/datastore/{datastoreId}/r4/Group/example-group/$davinci-data-export?_type=Patient,Observation,Condition,MedicationRequest,ExplanationOfBenefit&exportType=hl7.fhir.us.davinci-pdex&_includeEOB2xWoFinancial=true
```
*Payer-to-Payer匯出*
```
GET https://healthlake.{region}.amazonaws.com/datastore/{datastoreId}/r4/Group/example-group/$davinci-data-export?_type=Patient,Coverage,ExplanationOfBenefit,Condition,Procedure&exportType=hl7.fhir.us.davinci-pdex.p2p&_includeEOB2xWoFinancial=true
```
*特定病患的成員存取匯出*
```
GET https://healthlake.{region}.amazonaws.com/datastore/{datastoreId}/r4/Group/example-group/$davinci-data-export?_type=Patient,Observation,Condition,ExplanationOfBenefit,MedicationRequest&exportType=hl7.fhir.us.davinci-pdex.member&patient=Patient/example-patient-id
```
## 回應範例
```
{
"datastoreId": "eaee622d8406b41eb86c0f4741201ff9",
"jobStatus": "SUBMITTED",
"jobId": "48d7b91dae4a64d00d54b70862f33f61"
}
```
## 資源關係
操作會根據其在成員屬性清單中的關係匯出資源：
```
Group (Attribution List)
├── Patient (Members)
├── Coverage → RelatedPerson (Subscribers)
├── Practitioner (Attributed Providers)
├── PractitionerRole → Location
└── Organization (Attributed Providers)
```
### 資源來源
| 資源 | 來源位置 | Description |
| --- | --- | --- |
| Patient | Group.member.entity | 屬於屬性清單成員的患者 |
| Coverage | Group.member.extension:coverageReference | 導致病患成員資格的涵蓋範圍 |
| Organization | Group.member.extension:attributedProvider | 患者所屬的組織 |
| Practitioner | Group.member.extension:attributedProvider | 患者所屬的個別從業人員 |
| PractitionerRole | Group.member.extension:attributedProvider | 患者所屬的從業人員角色 |
| RelatedPerson | Coverage.subscriber | 涵蓋範圍的訂閱者 |
| Location | PractitionerRole.location | 與從業人員角色相關聯的位置 |
| Group | 輸入端點 | 屬性清單本身 |
## 任務管理
檢查任務狀態
`GET [base]/export/[job-id]`
取消任務
`DELETE [base]/export/[job-id]`
### 任務生命週期
+ `SUBMITTED` - 已收到任務並排入佇列
+ `IN_PROGRESS` - 任務正在主動處理
+ `COMPLETED` - 任務成功完成，檔案可供下載
+ `FAILED` - 任務發生錯誤
## 輸出格式
+ *檔案格式*：NDJSON （換行分隔 JSON)
+ *檔案組織*：每個資源類型的個別檔案
+ *副檔名*：.ndjson
+ *位置*：指定的 S3 儲存貯體和路徑
## 錯誤處理
針對下列情況， 操作會傳回 HTTP 400 錯誤請求與 OperationOutcome：
授權錯誤
在 中指定的 IAM 角色`DataAccessRoleArn`沒有足夠的許可來執行匯出操作。如需所需 S3 和 KMS 許可的完整清單，請參閱[設定匯出任務的許可](getting-started-setting-up.md#setting-up-export-permissions)。
參數驗證錯誤
+ `patient` 參數的格式不是 `Patient/id,Patient/id,...`
+ 一或多個病患參考無效或不屬於指定的群組
+ `exportType` 參數值不是支援的匯出類型
+ `_type` 參數包含指定匯出類型不支援的資源類型
+ `_type` 參數缺少`hl7.fhir.us.davinci-atr`匯出類型所需的資源類型 (`Group`、`Patient`、`Coverage`)
+ `_includeEOB2xWoFinancial` 參數值不是有效的布林值
資源驗證錯誤
+ 指定的群組資源不存在於資料存放區中
+ 指定的群組資源沒有成員
+ 一或多個群組成員參考資料存放區中不存在的患者資源
## 安全性和授權
+ 適用標準 FHIR 授權機制
+ 資料存取角色必須具有 S3 和 KMS 操作所需的 IAM 許可。如需所需許可的完整清單，請參閱[設定匯出任務的許可](getting-started-setting-up.md#setting-up-export-permissions)。
## 最佳實務
+ *資源類型選擇*：僅請求所需的資源類型，以將匯出大小和處理時間降至最低
+ 以*時間為基礎的篩選*：使用 `_since` 參數進行增量匯出
+ *病患篩選*：當您只需要特定成員的資料時，請使用 `patient` 參數
+ *任務監控*：定期檢查大型匯出的任務狀態
+ *錯誤處理*：針對失敗的任務實作適當的重試邏輯
+ *暫時篩選條件感知*：對於 PDex 匯出，請在選取資源類型時考慮 5 年暫時篩選條件
+ *財務資料移除*：當您需要沒有財務資訊的宣告資料`_includeEOB2xWoFinancial=true`時使用
+ *設定檔管理*：確保資源具有適當的設定檔宣告、在擷取之前針對目標設定檔進行驗證，並使用設定檔版本控制來控制匯出行為
## 限制
+ 參數中最多可指定 500 名病患 `patient`
+ 匯出僅限於群組層級操作
+ 僅支援每個匯出類型的預先定義資源類型集
+ 輸出一律為 NDJSON 格式
+ PDex 匯出僅限於 5 年的臨床和宣告資料
+ 財務資料轉換僅適用於 CARIN BB 2.x ExplanationOfBenefit 設定檔
## 其他資源
+ [Da Vinci 成員屬性清單 IG](https://build.fhir.org/ig/HL7/davinci-atr/)
+ [Da Vinci 付款人資料交換 IG](https://hl7.org/fhir/us/davinci-pdex/)
+ [CARIN 消費者導向付款人資料交換 IG](https://build.fhir.org/ig/HL7/carin-bb/)
+ [美國核心實作指南](https://www.hl7.org/fhir/us/core/)
+ [FHIR 大量資料存取規格](https://hl7.org/fhir/uv/bulkdata/)
# 使用 產生臨床文件 `$document`
AWS HealthLake 現在支援合成資源的 `$document`操作，可讓您將合成與其所有參考的資源綁定到單一的整合套件中，以產生完整的臨床文件。此操作對於需要：
+ 建立標準化臨床文件
+ Exchange 完整患者記錄
+ 存放完整的臨床文件
+ 產生包含所有相關內容的報告
## Usage
您可以使用 GET 和 POST 方法在合成資源上叫用 `$document`操作：
**受支援的 操作**
```
GET/POST [base]/Composition/[id]/$document
```
## 支援的參數
HealthLake 支援下列 FHIR `$document` 參數：
| 參數 | Type | 必要 | 預設 | Description |
| --- | --- | --- | --- | --- |
| persist | 布林值 | 否 | false | 布林值，指出伺服器是否應存放產生的文件套件 |
## 範例
**GET 請求**
```
GET [base]/Composition/180f219f-97a8-486d-99d9-ed631fe4fc57/$document?persist=true
```
**具有參數的 POST 請求**
```
POST [base]/Composition/180f219f-97a8-486d-99d9-ed631fe4fc57/$document
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "persist",
"valueBoolean": true
}
]
}
```
**回應範例**
操作會傳回「文件」類型的套件資源，其中包含合成和所有參考的資源：
```
{
"resourceType": "Bundle",
"id": "180f219f-97a8-486d-99d9-ed631fe4fc57",
"type": "document",
"identifier": {
"system": "urn:ietf:rfc:3986",
"value": "urn:uuid:0c3151bd-1cbf-4d64-b04d-cd9187a4c6e0"
},
"timestamp": "2024-06-21T15:30:00Z",
"entry": [
{
"fullUrl": "http://example.org/fhir/Composition/180f219f-97a8-486d-99d9-ed631fe4fc57",
"resource": {
"resourceType": "Composition",
"id": "180f219f-97a8-486d-99d9-ed631fe4fc57",
"status": "final",
"type": {
"coding": [
{
"system": "http://loinc.org",
"code": "34133-9",
"display": "Summary of Episode Note"
}
]
},
"subject": {
"reference": "Patient/example"
},
"section": [
{
"title": "Allergies",
"entry": [
{
"reference": "AllergyIntolerance/123"
}
]
}
]
}
},
{
"fullUrl": "http://example.org/fhir/Patient/example",
"resource": {
"resourceType": "Patient",
"id": "example",
"name": [
{
"family": "Smith",
"given": ["John"]
}
]
}
},
{
"fullUrl": "http://example.org/fhir/AllergyIntolerance/123",
"resource": {
"resourceType": "AllergyIntolerance",
"id": "123",
"patient": {
"reference": "Patient/example"
},
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "418689008",
"display": "Allergy to penicillin"
}
]
}
}
}
]
}
```
## Behavior (行為)
`$document` 操作：
1. 將指定的合成資源做為文件的基礎
1. 識別和擷取合成直接參考的所有資源
1. 將合成和所有參考的資源封裝到類型為「文件」的套件中
1. 當持久性參數設定為 true 時，將產生的文件套件儲存在資料存放區中
1. 識別和擷取 合成間接參考的資源，以產生全面的文件
`$document` 操作目前支援以下列格式擷取資源參考：
1.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Resource/id
```
1. 資源/id
合成資源中不支援的資源參考將從產生的文件篩選出。
## 錯誤處理
操作會處理下列錯誤條件：
+ 400 錯誤的請求：無效的`$document`操作 （不符合的請求），或者如果產生的文件在持久性設定為 true 時因篩選掉的參考而失敗 FHIR 驗證
+ 找不到 404：找不到合成資源
如需 `$document`操作規格的詳細資訊，請參閱 [FHIR R4 合成`$document`](https://www.hl7.org/fhir/R4/composition-operation-document.html)文件。
# 使用 永久移除資源 `$erase`
AWS HealthLake 支援 `$erase`操作，可永久刪除特定資源及其歷史版本。當您需要執行下列動作時，此操作特別有用：
+ 永久移除個別資源
+ 刪除特定版本歷史記錄
+ 管理個別資源生命週期
+ 符合特定資料移除要求
## Usage
操作`$erase`可以在兩個層級叫用：
**資源執行個體層級**
```
POST [base]/[ResourceType]/[ID]/$erase?deleteAuditEvent=true
```
**版本特定層級**
```
POST [base]/[ResourceType]/[ID]/_history/[VersionID]/$erase
```
## Parameters
| 參數 | Type | 必要 | 預設 | Description |
| --- | --- | --- | --- | --- |
| deleteAuditEvent | 布林值 | 否 | false | 為 true 時， 會刪除相關聯的稽核事件 |
## 範例
**範例請求**
```
POST [base]/Patient/example-patient/$erase
```
**回應範例**
```
{
"jobId": "5df47e2f51ff3c731847678cb8cad48e",
"jobStatus": "SUBMITTED"
}
```
## 任務狀態
若要檢查清除任務的狀態：
```
GET [base]/$erase/[jobId]
```
操作會傳回任務狀態資訊：
```
{
"datastoreId": "36622996b1fcecb7e12ee2ee085308d3",
"jobId": "5df47e2f51ff3c731847678cb8cad48e",
"status": "COMPLETED",
"submittedTime": "2025-10-30T16:39:24.160Z"
}
```
## Behavior (行為)
`$erase` 操作：
1. 非同步處理以確保資料完整性
1. 維護 ACID 交易
1. 提供任務狀態追蹤
1. 永久移除指定的資源及其版本
1. 包括刪除活動的完整稽核記錄
1. 支援選擇性刪除稽核事件
## 稽核記錄
`$erase` 操作會以 DeleteResource 記錄使用者 ID、時間戳記和資源詳細資訊。
## 限制
+ `$erased` 資源不會出現在搜尋結果或`_history`查詢中。
+ 正在清除的資源在處理期間可能暫時無法存取
+ 當資源永久移除時，儲存體計量會立即調整
# 使用 取得患者資料 `Patient/$everything`
`Patient/$everything` 操作用於查詢 FHIR `Patient` 資源，以及與該 相關的任何其他資源`Patient`。此操作可用來讓病患存取其整個記錄，或讓提供者執行與病患相關的大量資料下載。HealthLake `Patient/$everything` 支援特定病患 `id`。
`Patient/$everything` 是一種 FHIR REST API 操作，可以叫用，如以下範例所示。
------
#### [ GET request ]
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything
```
------
**注意**
回應中的資源會依資源類型和資源 排序`id`。
回應一律會填入 `Bundle.total`。
## `Patient/$everything` 參數
HealthLake 支援下列查詢參數
| 參數 | 詳細資訊 |
| --- | --- |
| 入門 | 取得指定開始日期之後的所有`Patient`資料。 |
| end | 在指定的結束日期之前取得`Patient`所有資料。 |
| since | 在指定日期之後更新`Patient`所有資料。 |
| \$1type | 取得特定資源類型的`Patient`資料。 |
| \$1count | 取得`Patient`資料並指定頁面大小。 |
**Example - 取得指定開始日期之後的所有患者資料**
`Patient/$everything` 可以使用`start`篩選條件僅查詢特定日期之後的資料。
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything?start=2024-03-15T00:00:00.000Z
```
**Example - 在指定的結束日期之前取得`Patient`所有資料**
病患 \$1所有項目都可以使用`end`篩選條件，只在特定日期之前查詢資料。
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything?end=2024-03-15T00:00:00.000Z
```
**Example - 在指定日期之後更新`Patient`所有資料**
`Patient/$everything` 可以使用`since`篩選條件，僅查詢特定日期之後更新的資料。
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything?since=2024-03-15T00:00:00.000Z
```
**Example - 取得特定資源類型的`Patient`資料**
病患 \$1所有項目都可以使用`_type`篩選條件來指定要包含在回應中的特定資源類型。您可以在逗號分隔清單中指定多種資源類型。
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything?_type=Observation,Condition
```
**Example - 取得`Patient`資料並指定頁面大小**
病患 \$1所有項目都可以使用 `_count`來設定頁面大小。
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything?_count=15
```
## `Patient/$everything` `start` 和 `end` 屬性
HealthLake 支援 `Patient/ $everything``start`和 `end`查詢參數的下列資源屬性。
| 資源 | 資源元素 |
| --- | --- |
| 帳戶 | Account.servicePeriod.start |
| AdverseEvent | AdverseEvent.date |
| AllergyIntolerance | AllergyIntolerance.recordedDate |
| 約定 | Appointment.start |
| AppointmentResponse | AppointmentResponse.start |
| AuditEvent | AuditEvent.period.start |
| 基本 | Basic.created |
| BodyStructure | NO\$1DATE |
| CarePlan | CarePlan.period.start |
| CareTeam | CareTeam.period.start |
| ChargeItem | ChargeItem.occurrenceDateTime, ChargeItem.occurrencePeriod.start, ChargeItem.occurrenceTiming.event |
| 取得 | Claim.billablePeriod.start |
| ClaimResponse | ClaimResponse.created |
| ClinicalImpression | ClinicalImpression.date |
| Communication | Communication.sent |
| CommunicationRequest | CommunicationRequest.occurrenceDateTime,CommCommunicationRequest.occurrencePeriod.start |
| 合成 | Composition.date |
| 條件 | Condition.recordedDate |
| 同意 | consent.dateTime |
| 涵蓋範圍 | Coverage.period.start |
| CoverageEligibilityRequest | CoverageEligibilityRequest.created |
| CoverageEligibilityResponse | CoverageEligibilityResponse.created |
| DetectedIssue | DetectedIssue.identified |
| DeviceRequest | DeviceRequest.authoredOn |
| DeviceUseStatement | DeviceUseStatement.recordedOn |
| DiagnosticReport | DiagnosticReport.effective |
| DocumentManifest | DocumentManifest.created |
| DocumentReference | DocumentReference.context.period.start |
| 遇到 | Encounter.period.start |
| EnrollmentRequest | EnrollmentRequest.created |
| EpisodeOfCare | EpisodeOfCare.period.start |
| ExplanationOfBenefit | ExplanationOfBenefit.billablePeriod.start |
| FamilyMemberHistory | NO\$1DATE |
| 旗標 | Flag.period.start |
| 目標 | Goal.statusDate |
| Group | NO\$1DATE |
| ImagingStudy | ImagingStudy.started |
| 預防 | Immunization.recorded |
| ImmunizationEvaluation | ImmunizationEvaluation.date |
| ImmunizationRecommendation | ImmunizationRecommendation.date |
| 發票 | Invoice.date |
| 清單 | List.date |
| MeasureReport | MeasureReport.period.start |
| 媒體 | 媒體。發行 |
| MedicationAdministration | MedicationAdministration.effective |
| MedicationDispense | MedicationDispense.whenPrepared |
| MedicationRequest | MedicationRequest.authoredOn |
| MedicationStatement | MedicationStatement.dateAsserted |
| MolecularSequence | NO\$1DATE |
| NutritionOrder | NutritionOrder.dateTime |
| 觀察 | Observation.effective |
| 病患 | NO\$1DATE |
| 個人 | NO\$1DATE |
| 程序 | Procedure.performed |
| 證明 | Provenance.occurredPeriod.start,Provenance.occurredDateTime |
| QuestionnaireResponse | QuestionnaireResponse.authored |
| RelatedPerson | NO\$1DATE |
| RequestGroup | RequestGroup.authoredOn |
| ResearchSubject | ResearchSubject.period |
| RiskAssessment | RiskAssessment.occurrenceDateTime,RiskAssessment.occurrencePeriod.start |
| Schedule | Schedule.planningHorizon |
| ServiceRequest | ServiceRequest.authoredOn |
| 樣本 | 配置函式.receivedTime |
| SupplyDelivery | SupplyDelivery.occurrenceDateTime, SupplyDelivery.occurrencePeriod.start, SupplyDelivery.occurrenceTiming.event |
| SupplyRequest | SupplyRequest.authoredOn |
| VisionPrescription | VisionPrescription.dateWritten |
# 使用 擷取 ValueSet 程式碼 `$expand`
AWS HealthLake 現在支援您以客戶身分擷取的 ValueSets (ValueSet) `$expand`操作，可讓您擷取包含在這些 ValueSet 資源中的代碼完整清單。當您需要：
+ 擷取所有可能的程式碼以進行驗證
+ 在使用者介面中顯示可用的選項
+ 在特定術語內容中執行全面的程式碼查詢
## Usage
您可以使用 GET 和 POST 方法在 ValueSet 資源上叫用 `$expand`操作：
**受支援的 操作**
```
GET/POST [base]/ValueSet/[id]/$expand
GET [base]/ValueSet/$expand?url=http://example.com
POST [base]/ValueSet/$expand
```
## 支援的參數
HealthLake 支援 FHIR R4 `$expand` 參數的子集：
| 參數 | Type | 必要 | Description |
| --- | --- | --- | --- |
| url | uri | 否 | 要展開之 ValueSet 的正式 URL |
| id | id | 否 | 要展開的 ValueSet 資源 ID （適用於 GET 或 POST 操作） |
| filter | string | 否 | 篩選程式碼擴展結果 |
| count | integer | 否 | 要傳回的代碼數量 |
| offset | integer | 否 | 傳回前要略過的相符代碼數量。在篩選後套用，且僅適用於相符的代碼，不適用於原始 ValueSet 的完整、未篩選內容 |
## 範例
**依 ID 的 GET 請求**
```
GET [base]/ValueSet/example-valueset/$expand
```
**使用篩選條件依 URL 提出 GET 請求**
```
GET [base]/ValueSet/$expand?url=http://example.com/ValueSet/my-valueset&filter=male&count=5
```
**含參數的 POST 請求 （依 ID)**
```
POST [base]/ValueSet/example-valueset/$expand
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "count",
"valueInteger": 10
},
{
"name": "filter",
"valueString": "admin"
}
]
}
```
**含參數的 POST 請求 （依 URL)**
```
POST [base]/ValueSet/$expand
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "url",
"valueUri": "http://hl7.org/fhir/ValueSet/administrative-gender"
},
{
"name": "count",
"valueInteger": 10
}
]
}
```
**回應範例**
操作會傳回具有 `expansion`元素的 ValueSet 資源，其中包含展開的程式碼：
```
{
"resourceType": "ValueSet",
"id": "administrative-gender",
"status": "active",
"expansion": {
"identifier": "urn:uuid:12345678-1234-1234-1234-123456789abc",
"timestamp": "2024-01-15T10:30:00Z",
"total": 4,
"parameter": [
{
"name": "count",
"valueInteger": 10
}
],
"contains": [
{
"system": "http://hl7.org/fhir/administrative-gender",
"code": "male",
"display": "Male"
},
{
"system": "http://hl7.org/fhir/administrative-gender",
"code": "female",
"display": "Female"
},
{
"system": "http://hl7.org/fhir/administrative-gender",
"code": "other",
"display": "Other"
},
{
"system": "http://hl7.org/fhir/administrative-gender",
"code": "unknown",
"display": "Unknown"
}
]
}
}
```
回應包括：
+ expansion.total：展開 ValueSet 中的程式碼總數
+ expansion.contains：展開的程式碼陣列及其系統、程式碼和顯示值
+ expansion.parameter：擴展請求中使用的參數
如需 `$expand`操作規格的詳細資訊，請參閱 [FHIR R4 ValueSet `$expand`](https://build.fhir.org/valueset-operation-expand.html) 文件。
# 使用 FHIR 匯出 HealthLake 資料 `$export`
您可以使用 FHIR \$1export 操作，從 HealthLake 資料存放區大量匯出資料。HealthLake 支援`$export`使用 `POST`和 `GET`請求的 FHIR。若要使用 提出匯出請求`POST`，您必須擁有具有必要許可的 IAM 使用者、群組或角色、指定 `$export`做為請求的一部分，並在請求內文中包含所需的參數。
**注意**
使用 FHIR 提出的所有 HealthLake 匯出請求`$export`都會以 `ndjson` 格式傳回，並匯出至 Amazon S3 儲存貯體，其中每個 Amazon S3 物件僅包含單一 FHIR 資源類型。
您可以根據 AWS 帳戶服務配額將匯出請求排入佇列。如需詳細資訊，請參閱[Service Quotas](reference-healthlake-endpoints-quotas.md#reference-healthlake-quotas)。
HealthLake 支援下列三種類型的大量匯出端點請求。
**HealthLake 大量`$export`類型**
| 匯出類型 | Description | 語法 |
| --- | --- | --- |
| 系統 | 從 HealthLake FHIR 伺服器匯出所有資料。 | `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/$export` |
| 所有病患 | 匯出所有與病患相關的所有資料，包括與病患資源類型相關聯的資源類型。 | `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/$export` `GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/$export` |
| 病患群組 | 匯出與群組 ID 指定的一組患者相關的所有資料。 | `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Group/id/$export` `GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Group/id/$export` |
## 開始之前
符合下列要求，以使用 FHIR REST API for HealthLake 提出匯出請求。
+ 您必須設定具有提出匯出請求必要許可的使用者、群組或角色。如需詳細資訊，請參閱 [授權 `$export`請求](#export-rest-auth)。
+ 您必須已建立服務角色，授予 HealthLake 存取您要將資料匯出至其中的 Amazon S3 儲存貯體的權限。服務角色也必須指定 HealthLake 做為服務委託人。如需設定許可的詳細資訊，請參閱 [設定匯出任務的許可](getting-started-setting-up.md#setting-up-export-permissions)。
## 授權 `$export`請求
若要使用 FHIR REST API 提出成功的匯出請求，請使用 IAM 或 OAuth2.0. 您還必須擁有 服務角色。
**使用 IAM 授權請求**
當您提出`$export`請求時，使用者、群組或角色必須在政策中包含 IAM 動作。如需詳細資訊，請參閱[設定匯出任務的許可](getting-started-setting-up.md#setting-up-export-permissions)。
**在 FHIR 上使用 SMART 授權請求 (OAuth 2.0)**
當您在啟用 FHIR 的 HealthLake 資料存放區上對 SMART 提出`$export`請求時，您必須指派適當的範圍。如需詳細資訊，請參閱[HealthLake 的 FHIR 資源範圍上的 SMART](reference-smart-on-fhir-oauth-scopes.md#smart-on-fhir-scopes-rest)。
**注意**
`$export` 具有`GET`請求的 FHIR 需要相同的身分驗證方法或承載字符 （在 FHIR 上使用 SMART 的情況下） 來請求匯出和擷取檔案。使用 FHIR `$export` 搭配 匯出的檔案`GET`可供下載 48 小時。
## 提出`$export`請求
本節說明使用 FHIR REST API 提出匯出請求時必須採取的必要步驟。
為了避免 AWS 您的帳戶意外產生費用，我們建議您在不提供`$export`語法的情況下提出請求來測試您的`POST`請求。
若要提出請求，您必須執行下列動作：
1. 在支援端點的`POST`請求 URL `$export`中指定 。
1. 指定必要的標頭參數。
1. 指定定義必要參數的請求內文。
### 步驟 1：在支援[端點](reference-healthlake-endpoints-quotas.md#reference-healthlake-endpoints)的`POST`請求 URL `$export`中指定 。
HealthLake 支援三種類型的大量匯出端點請求。若要提出大量匯出請求，您必須在三個支援的端點之一上提出`POST`以 為基礎的請求。下列範例示範要在請求 URL `$export`中指定何處。
+ `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/$export`
+ `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/$export`
+ `POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Group/id/$export`
您可以在`POST`請求字串中使用下列支援的搜尋參數。
#### 支援的搜尋參數
HealthLake 在大量匯出請求中支援下列搜尋修飾詞。
下列範例包含特殊字元，在提交請求之前必須先編碼。
| 名稱 | 是否為必要？ | Description | 範例 |
| --- | --- | --- | --- |
| \$1outputFormat | 否 | 要產生的請求大量資料檔案格式。接受的值為 application/fhir\$1ndjson、application/ndjson、ndjson。 | |
| \$1type | 否 | 您想要包含在匯出任務中的逗號分隔 FHIR 資源類型的字串。我們建議包含 ，\$1type因為匯出所有資源時，這可能會牽涉成本。 | &\$1type=MedicationStatement, Observation |
| \$1since | 否 | 在日期時間戳記當天或之後修改的資源類型。如果資源類型沒有上次更新的時間，則會將其包含在回應中。 | &\$1since=2024-05-09T00%3A00%3A00Z |
| \$1until | 否 | 在日期時間戳記當天或之前修改的資源類型。與 結合使用\$1since，以定義匯出的特定時間範圍。如果資源類型沒有上次更新的時間，它們將從您的回應中排除。 | &\$1until=2024-12-31T23%3A59%3A59Z |
### 步驟 2：指定必要的標頭參數
若要使用 FHIR REST API 提出匯出請求，您必須指定下列標頭參數。
+ Content-Type： `application/fhir+json`
+ 偏好： `respond-async`
接著，您必須在請求內文中指定必要的元素。
### 步驟 3：指定 定義必要參數的請求內文。
匯出請求也需要 `JSON` 格式的內文。內文可以包含下列參數。
| 金錀 | 是否為必要？ | Description | Value |
| --- | --- | --- | --- |
| DataAccessRoleArn | 是 | HealthLake 服務角色的 ARN。使用的服務角色必須指定 HealthLake 做為服務委託人。 | arn:aws:iam::444455556666:role/your-healthlake-service-role |
| JobName | 否 | 匯出請求的名稱。 | your-export-job-name |
| S3Uri | 是 | OutputDataConfig 金鑰的一部分。要下載匯出資料之目的地儲存貯體的 S3 URI。 | s3://amzn-s3-demo-bucket/EXPORT-JOB/ |
| KmsKeyId | 是 | OutputDataConfig 金鑰的一部分。用於保護 Amazon S3 儲存貯體之 AWS KMS 金鑰的 ARN。 | arn:aws:kms:region-of-bucket:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab |
**Example 使用 FHIR REST API 提出的匯出請求內文**
若要使用 FHIR REST API 提出匯出請求，您必須指定內文，如下所示。
```
{
"DataAccessRoleArn": "arn:aws:iam::444455556666:role/your-healthlake-service-role",
"JobName": "your-export-job",
"OutputDataConfig": {
"S3Configuration": {
"S3Uri": "s3://amzn-s3-demo-bucket/EXPORT-JOB",
"KmsKeyId": "arn:aws:kms:region-of-bucket:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
}
}
```
當您的請求成功時，您將會收到下列回應。
*回應標頭*
```
content-location: https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/export/your-export-request-job-id
```
*回應內文*
```
{
"datastoreId": "your-data-store-id",
"jobStatus": "SUBMITTED",
"jobId": "your-export-request-job-id"
}
```
## 管理您的匯出請求
成功提出匯出請求後，您可以使用 管理請求`$export`，以描述目前匯出請求的狀態，以及`$export`取消目前的匯出請求。
當您使用 REST API 取消匯出請求時，您只需支付截至您提交取消請求之前匯出的部分資料的費用。
下列主題說明如何取得狀態或取消目前的匯出請求。
### 取消匯出請求
若要取消匯出請求，請提出`DELETE`請求並在請求 URL 中提供任務 ID。
```
DELETE https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/export/your-export-request-job-id
```
當您的請求成功時，您會收到以下內容。
```
{
"exportJobProperties": {
"jobId": "your-original-export-request-job-id",
"jobStatus": "CANCEL_SUBMITTED",
"datastoreId": "your-data-store-id"
}
}
```
當您的請求不成功時，您會收到以下內容。
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "not-supported",
"diagnostics": "Interaction not supported."
}
]
}
```
### 描述匯出請求
若要取得匯出請求的狀態，請使用 `export`和 提出`GET`請求`export-request-job-id`。
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/export/your-export-request-id
```
JSON 回應將包含 `ExportJobProperties` 物件。它可能包含下列索引鍵：值對。
| 名稱 | 是否為必要？ | Description | Value |
| --- | --- | --- | --- |
| DataAccessRoleArn | 否 | HealthLake 服務角色的 ARN。使用的服務角色必須指定 HealthLake 做為服務委託人。 | arn:aws:iam::444455556666:role/your-healthlake-service-role |
| SubmitTime | 否 | 匯出任務提交的日期。 | Apr 21, 2023 5:58:02 |
| EndTime | 否 | 匯出任務完成的時間。 | Apr 21, 2023 6:00:08 PM |
| JobName | 否 | 匯出請求的名稱。 | your-export-job-name |
| JobStatus | 否 | | 有效的值如下：SUBMITTED | IN_PROGRESS | COMPLETED_WITH_ERRORS | COMPLETED |
FAILED
|
| S3Uri | 是 | [OutputDataConfig](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_OutputDataConfig.html) 物件的一部分。要下載匯出資料之目的地儲存貯體的 Amazon S3 URI。 | s3://amzn-s3-demo-bucket/EXPORT-JOB/ |
| KmsKeyId | 是 | [OutputDataConfig](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_OutputDataConfig.html) 物件的一部分。用於保護 Amazon S3 儲存貯體之 AWS KMS 金鑰的 ARN。 | arn:aws:kms:region-of-bucket:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab |
**Example ：描述使用 FHIR REST API 提出之匯出請求的內文**
成功時，您會收到下列 JSON 回應。
```
{
"exportJobProperties": {
"jobId": "your-export-request-id",
"JobName": "your-export-job",
"jobStatus": "SUBMITTED",
"submitTime": "Apr 21, 2023 5:58:02 PM",
"endTime": "Apr 21, 2023 6:00:08 PM",
"datastoreId": "your-data-store-id",
"outputDataConfig": {
"s3Configuration": {
"S3Uri": "s3://amzn-s3-demo-bucket/EXPORT-JOB",
"KmsKeyId": "arn:aws:kms:region-of-bucket:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab""
}
},
"DataAccessRoleArn": "arn:aws:iam::444455556666:role/your-healthlake-service-role",
}
}
```
# HealthLake 的 FHIR `$inquire`操作
`$inquire` 操作可讓您檢查先前提交的預先授權請求的狀態。此操作實作 [Da Vinci 預先授權支援 (PAS) 實作指南](https://hl7.org/fhir/us/davinci-pas/)，提供標準化的 FHIR 工作流程來擷取目前的授權決策。
## 運作方式
+ **提交查詢**：您傳送 FHIR 套件，其中包含您要檢查的宣告和支援資訊
+ **搜尋**：HealthLake 會在您的資料存放區中搜尋對應的 ClaimResponse
+ **擷取**：擷取最新的授權狀態
+ **回應**：您會收到目前授權狀態的立即回應 （佇列、核准、拒絕等）
**注意**
`$inquire` 是**擷取現有授權狀態的唯讀操作**。它不會修改或更新資料存放區中的任何資源。
## API 端點
```
POST /datastore/{datastoreId}/r4/Claim/$inquire
Content-Type: application/fhir+json
```
## 請求結構
### 套件需求
您的請求必須是具有下列項目的 FHIR 套件資源：
+ **Bundle.type**：必須為 `"collection"`
+ **Bundle.entry**：必須包含**一個**具有下列項目的宣告資源：
+ `use = "preauthorization"`
+ `status = "active"`
+ **參考資源**： 宣告參考的所有資源必須包含在套件中
**Query-by-Example**
輸入套件中的資源做為搜尋範本。HealthLake 會使用提供的資訊來尋找對應的 ClaimResponse。
### 必要的資源
| 資源 | 基數 | 設定檔 | Description |
| --- | --- | --- | --- |
| 宣告 | 1 | PAS 宣告查詢 | 您正在查詢的預先授權 |
| 病患 | 1 | PAS 受益人病患 | 病患人口統計資訊 |
| Organization （保險業者） | 1 | PAS 保險公司組織 | 保險公司 |
| Organization （提供者） | 1 | PAS 請求組織 | 提交請求的醫療保健供應商 |
### 重要搜尋條件
HealthLake 使用下列項目搜尋 ClaimResponse：
+ 來自宣告**的患者參考**
+ 來自宣告的**保險業者參考**
+ 來自宣告的**提供者參考**
+ 從宣告**建立的日期** （做為時間篩選條件）
**僅限患者特定的查詢**
所有查詢都必須繫結至特定病患。不允許沒有患者識別的全系統查詢。
## 範例請求
```
POST /datastore/example-datastore/r4/Claim/$inquire
Content-Type: application/fhir+json
Authorization: Bearer
{
"resourceType": "Bundle",
"id": "PASClaimInquiryBundleExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-pas-inquiry-request-bundle"]
},
"identifier": {
"system": "http://example.org/SUBMITTER_TRANSACTION_IDENTIFIER",
"value": "5269368"
},
"type": "collection",
"timestamp": "2005-05-02T14:30:00+05:00",
"entry": [
{
"fullUrl": "http://example.org/fhir/Claim/MedicalServicesAuthorizationExample",
"resource": {
"resourceType": "Claim",
"id": "MedicalServicesAuthorizationExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim-inquiry"]
},
"status": "active",
"type": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/claim-type",
"code": "professional"
}]
},
"use": "preauthorization",
"patient": {
"reference": "Patient/SubscriberExample"
},
"created": "2005-05-02T11:01:00+05:00",
"insurer": {
"reference": "Organization/InsurerExample"
},
"provider": {
"reference": "Organization/UMOExample"
}
}
},
{
"fullUrl": "http://example.org/fhir/Patient/SubscriberExample",
"resource": {
"resourceType": "Patient",
"id": "SubscriberExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-beneficiary"]
},
"name": [{
"family": "SMITH",
"given": ["JOE"]
}],
"gender": "male"
}
},
{
"fullUrl": "http://example.org/fhir/Organization/UMOExample",
"resource": {
"resourceType": "Organization",
"id": "UMOExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-requestor"]
},
"name": "Provider Organization"
}
},
{
"fullUrl": "http://example.org/fhir/Organization/InsurerExample",
"resource": {
"resourceType": "Organization",
"id": "InsurerExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-insurer"]
},
"name": "Insurance Company"
}
}
]
}
```
## 回應格式
### 成功回應 (200 OK)
您將會收到 PAS 查詢回應套件，其中包含：
+ 具有目前授權狀態的 **ClaimResponse**；如果符合搜尋條件，則為多個 **ClaimResponse**
+ 請求中的所有原始資源 （已回呼）
+ 組合回應時的時間戳記
**可能的 ClaimResponse 結果**
| 結果 | Description |
| --- | --- |
| queued | 授權請求仍在等待審核 |
| complete | 已做出授權決策 （檢查disposition是否已核准/遭拒） |
| error | 處理期間發生錯誤 |
| partial | 已授予部分授權 |
```
{
"resourceType": "Bundle",
"identifier": {
"system": "http://example.org/SUBMITTER_TRANSACTION_IDENTIFIER",
"value": "5269367"
},
"type": "collection",
"timestamp": "2005-05-02T14:30:15+05:00",
"entry": [
{
"fullUrl": "http://example.org/fhir/ClaimResponse/InquiryResponseExample",
"resource": {
"resourceType": "ClaimResponse",
"id": "InquiryResponseExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claimresponse-inquiry"]
},
"status": "active",
"type": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/claim-type",
"code": "professional"
}]
},
"use": "preauthorization",
"patient": {
"reference": "Patient/SubscriberExample"
},
"created": "2005-05-02T11:05:00+05:00",
"insurer": {
"reference": "Organization/InsurerExample"
},
"request": {
"reference": "Claim/MedicalServicesAuthorizationExample"
},
"outcome": "complete",
"disposition": "Approved",
"preAuthRef": "AUTH12345"
}
},
{
"fullUrl": "http://example.org/fhir/Claim/MedicalServicesAuthorizationExample",
"resource": {
"resourceType": "Claim",
"id": "MedicalServicesAuthorizationExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim-inquiry"]
},
"status": "active",
"type": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/claim-type",
"code": "professional"
}]
},
"use": "preauthorization",
"patient": {
"reference": "Patient/SubscriberExample"
},
"created": "2005-05-02T11:01:00+05:00",
"insurer": {
"reference": "Organization/InsurerExample"
},
"provider": {
"reference": "Organization/UMOExample"
}
}
},
{
"fullUrl": "http://example.org/fhir/Patient/SubscriberExample",
"resource": {
"resourceType": "Patient",
"id": "SubscriberExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-beneficiary"]
},
"name": [{
"family": "SMITH",
"given": ["JOE"]
}],
"gender": "male"
}
},
{
"fullUrl": "http://example.org/fhir/Organization/UMOExample",
"resource": {
"resourceType": "Organization",
"id": "UMOExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-requestor"]
},
"name": "Provider Organization"
}
},
{
"fullUrl": "http://example.org/fhir/Organization/InsurerExample",
"resource": {
"resourceType": "Organization",
"id": "InsurerExample",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-insurer"]
},
"name": "Insurance Company"
}
}
]
}
```
## 錯誤回應
### 400 錯誤的請求
當請求格式無效或驗證失敗時傳回。
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "required",
"diagnostics": "Reference 'Patient/SubscriberExample' at path 'patient' for 'CLAIM' resource not found(at Bundle.entry[0].resource)"
}
]
}
```
### 401 (未經授權)
當身分驗證憑證遺失或無效時傳回。
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "forbidden",
"diagnostics": "Invalid authorization header"
}
]
}
```
### 403 禁止
當已驗證的使用者缺少存取所請求資源的許可時傳回。
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "exception",
"diagnostics": "Insufficient SMART scope permissions."
}
]
}
```
### 400 當找不到時
查詢找不到相符的 ClaimResponse 時傳回。
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "not-found",
"diagnostics": "Resource not found. No ClaimResponse found from the input Claim that matches the specified Claim properties patient, insurer, provider, and created(at Bundle.entry[0].resource)"
}]
}
```
### 415 不支援的媒體類型
當 Content-Type 標頭不是 application/fhir\$1json 時傳回。
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "value",
"diagnostics": "Incorrect MIME-type. Update request Content-Type header."
}]
}
```
### 429 太多請求
超過速率限制時傳回。
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "throttled",
"diagnostics": "Rate limit exceeded. Please retry after some time."
}]
}
```
## 驗證規則
HealthLake 會對您的查詢執行全面的驗證：
### 套件驗證
+ 必須符合 PAS 查詢請求套件描述檔
+ `Bundle.type` 必須 `"collection"`
+ 必須僅包含一個宣告資源
+ 套件中必須包含所有參考的資源
### 宣告驗證
+ 必須符合 PAS 宣告查詢設定檔
+ `Claim.use` 必須 `"preauthorization"`
+ `Claim.status` 必須 `"active"`
+ 必要欄位：`patient`、`insurer`、`provider`、 `created`
### 資源驗證
+ 所有資源必須符合其各自的 PAS 查詢設定檔
+ 必要的支援資源必須存在 （病患、保險公司組織、提供者組織）
+ 交互參考在套件中必須是有效且可解析的
## 效能規格
| 指標 | 規格 |
| --- | --- |
| 資源計數限制 | 每個套件 500 個資源 |
| 套件大小限制 | 最多 5 MB |
## 所需的許可
若要使用 `$inquire`操作，請確定您的 IAM 角色具有：
+ `healthlake:InquirePreAuthClaim` - 呼叫 操作
**FHIR 範圍上的 SMART**
**所需範圍下限：**
+ **SMART v1**： `user/ClaimResponse.read`
+ **SMART v2**： `user/ClaimResponse.s`
## 重要實作備註
### 搜尋行為
當您提交查詢時，HealthLake 會使用下列方式搜尋 ClaimResponse：
+ 來自輸入宣告**的患者參考**
+ 來自輸入 Claim **的保險業者參考**
+ 來自輸入宣告的**提供者參考**
+ 從輸入宣告**建立日期** （做為時間篩選條件）
**多個相符項目**：如果多個 ClaimResponses 符合您的搜尋條件，則 HealthLake 會傳回所有相符結果。您應該使用最新的`ClaimResponse.created`時間戳記來識別最新狀態。
### 已更新宣告
如果您已提交相同預先授權的多個更新 （例如 Claim v1.1、v1.2、v1.3)，`$inquire`操作會根據提供的搜尋條件擷取與**最新版本**相關聯的 ClaimResponse。
### 唯讀操作
`$inquire` 操作：
+ **會**擷取現有的授權狀態
+ **會**傳回最新的 ClaimResponse
+ **不**修改或更新任何資源
+ **不**建立新資源
+ **不會**觸發新的授權處理
## 工作流程範例
**典型的預先授權查詢工作流程**
```
1. Provider submits PA request
POST /Claim/$submit
→ Returns ClaimResponse with outcome="queued"
2. Payer reviews request (asynchronous)
→ Updates ClaimResponse status internally
3. Provider checks status
POST /Claim/$inquire
→ Returns ClaimResponse with outcome="queued" (still pending)
4. Provider checks status again later
POST /Claim/$inquire
→ Returns ClaimResponse with outcome="complete", disposition="Approved"
```
## 相關的 操作
+ `Claim/$submit` - 提交新的預先授權請求或更新現有的預先授權請求
+ `Patient/$everything` - 針對預先授權內容擷取完整的患者資料
# 使用 擷取概念詳細資訊 `$lookup`
AWS HealthLake 現在支援 CodeSystem 資源的 `$lookup`操作，可讓您透過提供程式碼等識別資訊，擷取程式碼系統中特定概念的詳細資訊。當您需要：
+ 擷取特定醫療代碼的詳細資訊
+ 驗證程式碼意義和屬性
+ 存取概念定義和關係
+ 使用準確的術語資料支援臨床決策
## Usage
您可以使用 GET 和 POST 方法在 CodeSystem 資源上叫用 `$lookup`操作：
**受支援的 操作**
```
GET [base]/CodeSystem/$lookup?system=http://snomed.info/sct&code=73211009&version=20230901
POST [base]/CodeSystem/$lookup
```
## 支援的參數
HealthLake 支援 FHIR R4 `$lookup` 參數的子集：
| 參數 | Type | 必要 | Description |
| --- | --- | --- | --- |
| code | code | 是 | 您要查詢的概念代碼 （例如 SNOMED CT 中的 "71620000") |
| system | uri | 是 | 程式碼系統的正式 URL （例如 "[http://snomed.info/sct](http://snomed.info/sct)") |
| version | string | 否 | 特定版本的程式碼系統 |
## 範例
**GET 請求**
```
GET [base]/CodeSystem/$lookup?system=http://snomed.info/sct&code=71620000&version=2023-09
```
**POST 請求**
```
POST [base]/CodeSystem/$lookup
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "system",
"valueUri": "http://snomed.info/sct"
},
{
"name": "code",
"valueCode": "71620000"
},
{
"name": "version",
"valueString": "2023-09"
}
]
}
```
**回應範例**
操作會傳回參數資源，其中包含概念詳細資訊：
```
{
"resourceType": "Parameters",
"parameter": [{
"name": "name",
"valueString": "SNOMED CT Fractures"
},
{
"name": "version",
"valueString": "2023-09"
},
{
"name": "display",
"valueString": "Fracture of femur"
},
{
"name": "property",
"part": [{
"name": "code",
"valueCode": "child"
},
{
"name": "value",
"valueCode": "263225007"
},
{
"name": "description",
"valueString": "Fracture of neck of femur"
}
]
},
{
"name": "property",
"part": [{
"name": "code",
"valueCode": "child"
},
{
"name": "value",
"valueCode": "263227004"
},
{
"name": "description",
"valueString": "Fracture of shaft of femur"
}
]
}
]
}
```
## 回應參數
回應會在可用時包含下列參數：
| 參數 | 類型 | Description |
| --- | --- | --- |
| name | string | 程式碼系統的名稱 |
| version | string | 程式碼系統的版本 |
| display | string | 顯示概念的名稱 |
| designation | BackboneElement | 此概念的其他表示法。 |
| property | BackboneElement | 概念的其他屬性 （定義、關係等） |
## Behavior (行為)
`$lookup` 操作：
1. 驗證所需的參數 (`code` 和 `system`)
1. 在存放在資料存放區的指定程式碼系統中搜尋概念
1. 傳回詳細的概念資訊，包括顯示名稱、指定項目和屬性。
1. 提供 `version` 參數時支援版本特定的查詢
1. 僅在明確存放在 HealthLake 資料存放區的程式碼系統上操作
## 錯誤處理
操作會處理下列錯誤條件：
+ 400 錯誤的請求：無效的`$lookup`操作 （不符合的請求或缺少必要的參數）
+ 找不到 404：找不到程式碼系統，或在指定的程式碼系統中找不到程式碼
## 警告
在此版本中，不支援下列項目：
+ `$lookup` 透過呼叫外部術語伺服器進行 操作
+ `$lookup` CodeSystems 上的 操作由 HealthLake 管理，但未明確存放在資料存放區中
如需 `$lookup`操作規格的詳細資訊，請參閱 [FHIR R4 CodeSystem `$lookup`](https://www.hl7.org/fhir/R4/codesystem-operation-lookup.html) 文件。
# `$member-add` HealthLake 的 操作
FHIR `$member-add`操作會將成員 （病患） 新增至群組資源，特別是成員屬性清單。此操作是 DaVinci 成員屬性實作指南的一部分，並支援管理成員屬性的調校程序。
## 操作端點
```
POST [base]/datastore/{datastoreId}/r4/Group/{groupId}/$member-add
Content-Type: application/json
```
## Parameters
操作接受具有下列參數組合的 FHIR 參數資源：
### 參數選項
您可以使用下列其中一個參數組合：
選項 1：成員 ID \$1 供應商 NPI
`memberId` \$1 `providerNpi`
`memberId` \$1 `providerNpi` \$1 `attributionPeriod`
選項 2：病患參考 \$1 提供者參考
`patientReference` \$1 `providerReference`
`patientReference` \$1 `providerReference` \$1 `attributionPeriod`
### 參數詳細資訊
memberId （選用）
要新增至群組之成員的識別符。
類型：Identifier
系統：病患識別符系統
```
{
"name": "memberId",
"valueIdentifier": {
"system": "http://example.org/patient-id",
"value": "patient-new"
}
}
```
providerNpi （選用）
屬性提供者的國家提供者識別符 (NPI)。
類型：Identifier
系統：https：//http://terminology.hl7.org/CodeSystem/NPI
```
{
"name": "providerNpi",
"valueIdentifier": {
"system": "http://terminology.hl7.org/CodeSystem/NPI",
"value": "1234567890"
}
}
```
patientReference （選用）
要新增之病患資源的直接參考。
類型：參考
```
{
"name": "patientReference",
"valueReference": {
"reference": "Patient/patient-123"
}
}
```
providerReference （選用）
直接參考提供者資源。
類型：參考
```
{
"name": "providerReference",
"valueReference": {
"reference": "Practitioner/provider-456"
}
}
```
attributionPeriod（選用）
病患歸因於提供者的期間。
類型：期間
```
{
"name": "attributionPeriod",
"valuePeriod": {
"start": "2024-07-15",
"end": "2025-07-14"
}
}
```
## 請求範例
### 使用成員 ID 和提供者 NPI
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "memberId",
"valueIdentifier": {
"system": "http://example.org/patient-id",
"value": "patient-new"
}
},
{
"name": "providerNpi",
"valueIdentifier": {
"system": "http://terminology.hl7.org/CodeSystem/NPI",
"value": "1234567890"
}
},
{
"name": "attributionPeriod",
"valuePeriod": {
"start": "2024-07-15",
"end": "2025-07-14"
}
}
]
}
```
### 使用病患和提供者參考
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "patientReference",
"valueReference": {
"reference": "Patient/patient-123"
}
},
{
"name": "providerReference",
"valueReference": {
"reference": "Practitioner/provider-456"
}
},
{
"name": "attributionPeriod",
"valuePeriod": {
"start": "2024-07-15",
"end": "2025-07-14"
}
}
]
}
```
## 回應格式
### 成功的新增回應
```
HTTP Status: 200 OK
Content-Type: application/fhir+json
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "success",
"code": "informational",
"details": {
"text": "Member Patient/patient-new successfully added to the Member Attribution List."
}
}
]
}
```
### 錯誤回應
無效的請求語法
HTTP 狀態：400 錯誤的請求
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "invalid",
"details": {
"text": "Invalid parameter combination provided"
}
}
]
}
```
找不到資源
HTTP 狀態：找不到 404
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "not-found",
"details": {
"text": "Resource not found."
}
}
]
}
```
版本衝突
HTTP 狀態：409 衝突
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "conflict",
"details": {
"text": "Resource version conflict detected"
}
}
]
}
```
無效的屬性狀態
HTTP 狀態：422 無法處理的實體
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "business-rule",
"details": {
"text": "Cannot add member to Attribution List with status 'final'. Status must be 'draft' or 'open'."
}
}
]
}
```
## 業務規則
屬性狀態驗證
只有在群組的屬性狀態為：
+ `draft`
+ `open`
當狀態為 時，不允許操作`final`。
防止重複成員
系統會根據以下項目的唯一組合，防止新增重複的成員：
+ 成員識別符
+ 付款人識別符
+ 涵蓋範圍識別符
涵蓋期間驗證
提供 `attributionPeriod` 時，必須落在成員涵蓋期間的界限內。系統會：
+ 搜尋成員的涵蓋範圍資源
+ 如果存在多個 ，請使用最新的涵蓋範圍 （最高 versionId)
+ 驗證歸因期間未超過涵蓋期間
參考驗證
當同時為相同的資源 （病患或提供者） 提供 ID 和參考時，系統會驗證它們是否對應至相同的資源。
當同時為相同的資源 （病患或提供者） 提供 ID 和 reference.identifier 欄位時，會擲回錯誤。
## 身分驗證與授權
此操作需要對下列項目進行 FHIR 上的 SMART 授權：
+ 讀取許可 - 驗證患者、提供者和群組資源
+ 搜尋許可 - 依識別符尋找資源
+ 更新許可 - 修改群組資源
## 操作行為
資源更新
+ 更新群組資源版本 ID
+ 在操作之前建立具有原始資源狀態的歷史記錄項目
+ 使用 新增成員資訊至 Group.member 陣列：
+ entity.reference 中的病患參考
+ 期間的屬性期間
+ 延伸欄位中的涵蓋範圍和提供者資訊
驗證步驟
+ 參數驗證 - 確保有效的參數組合
+ 資源存在 - 驗證存在的患者、提供者和群組資源
+ 屬性狀態 - 確認群組狀態允許修改
+ 重複檢查 - 防止新增現有成員
+ 涵蓋範圍驗證 - 確保歸因期間在涵蓋範圍內
## 限制
+ 所有參考的資源都必須存在於相同的資料存放區中
+ 操作僅適用於成員屬性清單群組資源
+ 屬性期間必須在涵蓋範圍內
+ 無法修改具有「最終」狀態的群組
# `$member-match` HealthLake 的 操作
AWS HealthLake 現在支援 病患資源`$member-match`的操作，讓醫療保健組織能夠使用人口統計和涵蓋範圍資訊，在不同醫療保健系統中尋找成員的唯一識別符。此操作對於實現 CMS 合規和促進安全payer-to-payer資料交換，同時維護患者隱私至關重要。
當您需要：
+ 啟用組織之間的安全醫療保健資料交換
+ 維持不同系統的患者持續照護
+ 支援 CMS 合規要求
+ 促進跨醫療保健網路的準確成員識別
## Usage
您可以使用 POST 方法，在病患資源上叫用 `$member-match`操作：
```
POST [base]/Patient/$member-match
```
## 支援的參數
HealthLake 支援下列 FHIR `$member-match` 參數：
| 參數 | Type | 必要 | 預設 | Description |
| --- | --- | --- | --- | --- |
| MemberPatient | 病患 | 是 | — | 包含要比對之成員人口統計資訊的患者資源 |
| CoverageToMatch | 涵蓋範圍 | 是 | — | 將用於比對現有記錄的涵蓋資源 |
| CoverageToLink | 涵蓋範圍 | 否 | — | 比對程序期間要連結的覆蓋資源 |
| 同意 | 同意 | 否 | — | 授權用途的同意資源 |
## 範例
### 具有參數的 POST 請求
```
POST [base]/Patient/$member-match
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "MemberPatient",
"resource": {
"resourceType": "Patient",
"name": [
{
"family": "Jones",
"given": ["Sarah"]
}
],
"gender": "female",
"birthDate": "1985-05-15"
}
},
{
"name": "CoverageToMatch",
"resource": {
"resourceType": "Coverage",
"status": "active",
"beneficiary": {
"reference": "Patient/1"
},
"relationship": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
"code": "self",
"display": "Self"
}
]
},
"payor": [
{
"reference": "Organization/payer456"
}
]
}
},
{
"name": "Consent",
"resource": {
"resourceType": "Consent",
"status": "active",
"scope": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentscope",
"code": "patient-privacy"
}
]
},
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "IDSCL"
}
]
}
],
"patient": {
"reference": "Patient/1"
},
"performer": [
{
"reference": "Patient/patient123"
}
],
"sourceReference": {
"reference": "Document/someconsent"
},
"policy": [
{
"uri": "http://hl7.org/fhir/us/davinci-hrex/StructureDefinition-hrex-consent.html#regular"
}
]
}
}
]
}
```
### 回應範例
操作會傳回參數資源，其中包含相符的結果：
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "MemberIdentifier",
"valueIdentifier": {
"system": "http://hospital.org/medical-record-number",
"value": "MRN-123456"
}
},
{
"name": "MemberId",
"valueReference": {
"reference": "Patient/patient123"
}
},
{
"name": "matchAlgorithm",
"valueString": "DEMOGRAPHIC_MATCH"
},
{
"name": "matchDetails",
"valueString": "Demographic match: DOB + Name"
},
{
"name": "matchedFields",
"valueString": "given,birthdate,gender,family"
}
]
}
```
## 回應參數
找到相符項目時，回應會包含下列參數：
| 參數 | 類型 | 說明 |
| --- | --- | --- |
| MemberIdentifier | 識別符 | 相符成員的唯一識別符 |
| MemberId | 參考資料 | 患者資源的參考 |
| matchAlgorithm | String | 使用的比對演算法類型 (EXACT\$1MATCH、STRONG\$1MATCH 或 DEMOGRAPHIC\$1MATCH) |
| matchDetails | String | 比對程序的詳細資訊 |
| matchedFields | String | 已成功相符的特定欄位清單 |
## 相符演算法
`$member-match` API 採用多層比對方法，以確保準確的成員識別：
EXACT\$1MATCH
使用與 Coverage SubscriberId 結合的患者識別符
為成員比對提供最高的可信度層級
STRONG\$1MATCH
使用具有最低涵蓋範圍資訊的患者識別符
不符合完全相符條件時，提供高可信度
DEMOGRAPHIC\$1MATCH
依賴基本人口統計資訊
當無法進行識別符型比對時使用
## Behavior (行為)
`$member-match` 操作：
+ 接受患者人口統計特性、涵蓋範圍詳細資訊和選用的同意資訊做為輸入
+ 傳回可用於後續互動的唯一成員識別符
+ 實作多層比對 （確切、強大、人口統計），以確保在不同醫療保健系統中正確識別成員
+ 儲存任何提供的同意資訊以供未來授權之用
+ 支援安全payer-to-payer資料交換，同時維護患者隱私權
+ 符合醫療資料交換的 CMS 要求
## Authorization
API 在 FHIR 授權通訊協定上使用 SMART 搭配下列必要範圍：
+ `system/Patient.read`
+ `system/Coverage.read`
+ `system/Organization.read` （有條件）
+ `system/Practitioner.read` （有條件）
+ `system/PractitionerRole.read` （有條件）
+ `system/Consent.write` （有條件）
## 錯誤處理
操作會處理下列錯誤條件：
+ `400 Bad Request`：無效的`$member-match`操作 （不符合的請求或缺少必要的參數）
+ `422 Unprocessable Entity`：找不到相符項目或多個相符項目
# `$member-remove` HealthLake 的 操作
`$member-remove` 操作可讓您從 FHIR 成員屬性清單 （群組資源） 中移除成員 AWS HealthLake。此操作是 DaVinci 成員屬性實作指南的一部分，並支援管理成員屬性的調校程序。
## 先決條件
+ AWS HealthLake FHIR 資料存放區
+ HealthLake 操作的適當 IAM 許可
+ 草稿或開啟狀態的成員屬性清單 （群組資源）
## 操作詳細資訊
Endpoint
`POST /Group/{id}/$member-remove`
內容類型
`application/fhir+json`
## Parameters
操作接受具有下列選用參數的 FHIR 參數資源：
| 參數 | 基數 | Type | 說明 |
| --- | --- | --- | --- |
| memberId | 0..1 | 識別符 | 要移除之成員的業務識別符 |
| providerNpi | 0..1 | 識別符 | 屬性提供者的 NPI |
| patientReference | 0..1 | 參考資料 | 直接參考 病患資源 |
| providerReference | 0..1 | 參考資料 | 直接參考提供者資源 (Practitioner、PractitionerRole 或 Organization) |
| coverageReference | 0..1 | 參考資料 | 涵蓋範圍資源的參考 |
### 支援的參數組合
支援下列參數組合：
+ `memberId` 僅限 - 移除指定成員的所有屬性
+ `memberId` \$1 `providerNpi` - 移除特定成員提供者組合的屬性
+ `patientReference` 僅限 - 移除指定病患的所有屬性
+ `patientReference` \$1 `providerReference` - 移除特定患者提供者組合的屬性
+ `patientReference` \$1 `providerReference` \$1 `coverageReference` - 根據病患、提供者和涵蓋範圍移除特定歸因
## 請求範例
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "patientReference",
"valueReference": {
"reference": "Patient/12345"
}
},
{
"name": "providerReference",
"valueReference": {
"reference": "Practitioner/67890"
}
}
]
}
```
## 回應
### 成功回應
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "result",
"valueBoolean": true
},
{
"name": "effectiveDate",
"valueDate": "2024-06-30"
},
{
"name": "status",
"valueCode": "inactive"
},
{
"name": "message",
"valueString": "Member successfully removed from attribution list"
}
]
}
```
## Behavior (行為)
狀態需求
操作僅適用於狀態為 `draft`或 的屬性清單 `open`
`final` 狀態為 的清單將拒絕 422 錯誤的 操作
成員移除程序
*草稿狀態清單*：成員標示為非作用中 (`inactive: true`)，且其`changeType`延伸項目已更新為 `changed`
*開啟狀態清單*：類似草稿狀態的行為
*最終狀態清單*：操作遭拒
驗證
驗證參考以確保它們存在於 HealthLake 資料存放區中
如果同時為相同的資源類型提供識別符和參考，它們必須對應至相同的資源
根據支援的模式驗證參數組合
## 錯誤處理
### 常見錯誤回應
找不到資源 (404)
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "not-found",
"details": {
"text": "Patient with identifier 'http://example.org/fhir/identifiers|99999' not found in system"
},
"diagnostics": "Cannot remove member from attribution list. Verify patient identifier and try again.",
"expression": ["memberId"]
}
]
}
```
屬性清單最終狀態 (422)
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "business-rule",
"details": {
"coding": [
{
"system": "http://hl7.org/fhir/us/davinci-atr/CodeSystem/atr-error-codes",
"code": "list-final",
"display": "Attribution list is final and cannot be modified"
}
]
},
"diagnostics": "Cannot modify attribution list with status 'final'. List modifications are not permitted after finalization.",
"expression": ["Group.status"]
}
]
}
```
無效操作 (400)
當參數組合無效或格式不正確時傳回。
找到多個相符項目 (412)
當提供的參數符合屬性清單中的多個成員時傳回。
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "Multiple members found matching the criteria"
}
]
}
```
## 最佳實務
+ *使用特定參數*：盡可能使用最特定的參數組合，以避免意外移除
+ *檢查清單狀態*：嘗試移除之前，請先驗證屬性清單狀態
+ *正常處理錯誤*：針對所有可能的錯誤條件實作適當的錯誤處理
+ *驗證參考*：確定所有參考的資源都存在，然後再提出請求
# 使用 移除病患室資源 `$purge`
AWS HealthLake 支援 `$purge`操作，可永久刪除病患隔室內的所有資源。當您需要執行下列動作時，此操作特別有用：
+ 移除與病患相關聯的所有資料
+ 遵循病患資料移除請求
+ 管理病患資料生命週期
+ 執行全面的病患記錄清除
## Usage
您可以在病患資源上叫用 `$purge`操作：
```
POST [base]/Patient/[ID]/$purge?deleteAuditEvent=true
```
## Parameters
| 參數 | Type | 必要 | 預設 | Description |
| --- | --- | --- | --- | --- |
| deleteAuditEvent | 布林值 | 否 | false | 為 true 時， 會刪除相關聯的稽核事件 |
| \$1since | string | 否 | 資料存放區建立時間 | 輸入時， 會根據其lastModified的時間選取開始截止時間以尋找資源。無法與開始或結束搭配使用 |
| start | string | 否 | 資料存放區建立時間 | 輸入時， 會根據資源的lastModified時間選取截止時間來尋找資源。可與 end 搭配使用 |
| end | string | 否 | 任務提交時間 | 輸入時， 會根據其lastModified的時間選取結束截止時間以尋找資源 |
## 範例
**範例請求**
```
POST [base]/Patient/example-patient/$purge?deleteAuditEvent=true
```
**回應範例**
```
{
"resourceType": "OperationOutcome",
"id": "purge-job",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "Purge job started successfully. Job ID: 12345678-1234-1234-1234-123456789012"
}
]
}
```
## 任務狀態
若要檢查清除任務的狀態：
```
GET [base]/$purge/[jobId]
```
操作會傳回任務狀態資訊：
```
{
"datastoreId": "36622996b1fcecb7e12ee2ee085308d3",
"jobId": "3dd1c7a5b6c0ef8c110f566eb87e2ef9",
"status": "COMPLETED",
"submittedTime": "2025-10-31T18:43:21.822Z"
}
```
## Behavior (行為)
`$purge` 操作：
1. 以非同步方式處理多個資源
1. 維護 ACID 交易的資料完整性
1. 提供具有資源刪除計數的任務狀態追蹤
1. 永久移除病患隔室中的所有資源
1. 包括刪除活動的完整稽核記錄
1. 支援選擇性刪除稽核事件
## 稽核記錄
`$purge` 操作會記錄為 StartFHIRBulkDeleteJob 和 DescribeFHIRBulkDeleteJob，其中包含詳細的操作資訊。
## 限制
+ 清除的資源不會出現在搜尋回應中
+ 正在清除的資源在處理期間可能暫時無法存取
+ 病患隔室中的所有資源都會永久移除
# HealthLake 的 FHIR `$questionnaire-package`操作
`$questionnaire-package` 操作會擷取完整的套件，其中包含 FHIR 問卷及其轉譯和處理問卷所需的所有相依性。此操作會實作 [Da Vinci 文件範本和規則 (DTR) 實作指南](https://hl7.org/fhir/us/davinci-dtr/OperationDefinition-questionnaire-package.html)，針對醫療工作流程中的文件需求啟用動態表單轉譯。
## 運作方式
+ **請求**：您傳送識別所需問卷的參數 （以及涵蓋範圍和順序內容）
+ **擷取**：HealthLake 會收集問卷和所有相依性 (ValueSets、CQL 程式庫等）
+ **套件**：所有資源都以標準化格式綁定在一起
+ **回應**：您收到準備轉譯和資料收集的完整套件
**使用案例**
+ **預先授權文件**：收集預先授權請求所需的臨床資訊
+ **涵蓋範圍需求**：收集滿足付款人涵蓋範圍需求所需的文件
+ **臨床資料交換**：結構臨床資料以提交給付款人
+ **動態表單**：使用預先填入的患者資料和條件式邏輯轉譯問卷
## API 端點
```
POST /datastore/{datastoreId}/r4/Questionnaire/$questionnaire-package
Content-Type: application/fhir+json
```
## 請求參數
### 輸入參數
請求內文必須包含具有下列參數的 FHIR 參數資源：
| 參數 | Type | 基數 | Description |
| --- | --- | --- | --- |
| coverage | 涵蓋範圍 | 1..\$1 （必要） | 用於建立文件成員和涵蓋範圍的 （涵蓋範圍） 資源 |
| questionnaire | 正式 | 0..\$1 | 要傳回之特定問卷的正式 URL (s) （可能包含版本） |
| order | 資源 | 0..\$1 | 訂購資源 (DeviceRequest、ServiceRequest、MedicationRequest、Encounter、Appointment) 以建立內容 |
| changedSince | dateTime | 0..1 | 如果存在，則只會傳回在此時間戳記之後變更的資源 |
### 參數驗證規則
**至少必須提供下列其中一項** （除了必要的 之外`coverage`)：
+ 一或多個`questionnaire`正式 URLs
+ 一或多個`order`資源
**有效的請求組合：**
+ `coverage` \$1 `questionnaire`
+ `coverage` \$1 `order`
+ `coverage` \$1 `questionnaire` \$1 `order`
## 範例請求
```
POST /datastore/example-datastore/r4/Questionnaire/$questionnaire-package
Content-Type: application/fhir+json
Authorization: Bearer
{
"resourceType": "Parameters",
"parameter": [
{
"name": "coverage",
"resource": {
"resourceType": "Coverage",
"id": "example-coverage",
"status": "active",
"beneficiary": {
"reference": "Patient/example-patient"
},
"payor": [{
"reference": "Organization/example-payer"
}],
"class": [{
"type": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "group"
}]
},
"value": "12345"
}]
}
},
{
"name": "questionnaire",
"valueCanonical": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0"
},
{
"name": "order",
"resource": {
"resourceType": "ServiceRequest",
"id": "example-service-request",
"status": "active",
"intent": "order",
"code": {
"coding": [{
"system": "http://www.ama-assn.org/go/cpt",
"code": "94660",
"display": "Continuous positive airway pressure ventilation (CPAP)"
}]
},
"subject": {
"reference": "Patient/example-patient"
}
}
},
{
"name": "changedSince",
"valueDateTime": "2024-01-01T00:00:00Z"
}
]
}
```
## 回應格式
### 成功回應 (200 OK)
操作會傳回包含一或多個**套件套件的** FHIR 參數資源。每個套件套件都包含：
| 項目類型 | 基數 | Description |
| --- | --- | --- |
| 問卷 | 1 | 要轉譯的問卷 |
| QuestionnaireResponse | 0..1 | 預先填入或部分完成的回應 （如適用） |
| Library (程式庫) | 0..\$1 | 包含預先填入和條件式邏輯的 CQL 程式庫 |
| ValueSet | 0..\$1 | 擴展的 ValueSets （適用於 <40 個擴展的答案選項） |
**Example 回應範例**
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "PackageBundle",
"resource": {
"resourceType": "Bundle",
"id": "questionnaire-package-example",
"meta": {
"profile": ["http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/DTR-QPackageBundle"]
},
"type": "collection",
"timestamp": "2024-03-15T10:30:00Z",
"entry": [
{
"fullUrl": "http://example.org/fhir/Questionnaire/home-oxygen-therapy",
"resource": {
"resourceType": "Questionnaire",
"id": "home-oxygen-therapy",
"url": "http://example.org/fhir/Questionnaire/home-oxygen-therapy",
"version": "2.0",
"status": "active",
"title": "Home Oxygen Therapy Documentation",
"item": [
{
"linkId": "1",
"text": "Patient diagnosis",
"type": "choice",
"answerValueSet": "http://example.org/fhir/ValueSet/oxygen-diagnoses"
}
]
}
},
{
"fullUrl": "http://example.org/fhir/Library/oxygen-prepopulation",
"resource": {
"resourceType": "Library",
"id": "oxygen-prepopulation",
"url": "http://example.org/fhir/Library/oxygen-prepopulation",
"version": "1.0",
"type": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/library-type",
"code": "logic-library"
}]
},
"content": [{
"contentType": "text/cql",
"data": "bGlicmFyeSBPeHlnZW5QcmVwb3B1bGF0aW9u..."
}]
}
},
{
"fullUrl": "http://example.org/fhir/ValueSet/oxygen-diagnoses",
"resource": {
"resourceType": "ValueSet",
"id": "oxygen-diagnoses",
"url": "http://example.org/fhir/ValueSet/oxygen-diagnoses",
"status": "active",
"expansion": {
"timestamp": "2024-03-15T10:30:00Z",
"contains": [
{
"system": "http://hl7.org/fhir/sid/icd-10",
"code": "J44.0",
"display": "COPD with acute lower respiratory infection"
},
{
"system": "http://hl7.org/fhir/sid/icd-10",
"code": "J96.01",
"display": "Acute respiratory failure with hypoxia"
}
]
}
}
},
{
"fullUrl": "http://example.org/fhir/QuestionnaireResponse/example-prepopulated",
"resource": {
"resourceType": "QuestionnaireResponse",
"id": "example-prepopulated",
"questionnaire": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0",
"status": "in-progress",
"subject": {
"reference": "Patient/example-patient"
},
"basedOn": [{
"reference": "ServiceRequest/example-service-request"
}],
"item": [
{
"linkId": "1",
"text": "Patient diagnosis",
"answer": [{
"valueCoding": {
"system": "http://hl7.org/fhir/sid/icd-10",
"code": "J44.0",
"display": "COPD with acute lower respiratory infection"
}
}]
}
]
}
}
]
}
},
{
"name": "Outcome",
"resource": {
"resourceType": "OperationOutcome",
"issue": [{
"severity": "information",
"code": "informational",
"details": {
"text": "Successfully retrieved questionnaire package"
}
}]
}
}
]
}
```
## 操作工作流程
**HealthLake 如何處理您的請求**
當您呼叫 時`$questionnaire-package`，HealthLake 會執行下列步驟：
1. **識別患者和付款人**：從您的 `coverage` 參數擷取患者和保險組織。
1. **尋找正確的問卷**：
+ **搭配 **`questionnaire`** 參數**：使用您提供的正式 URL
+ **使用 **`order`** 參數**：比對訂單代碼 (CPT/HCPCS/LOINC) 和付款人，以尋找適當的問卷
1. **收集相依性**：自動擷取轉譯問卷所需的一切：
+ **CQL 程式庫** - 預先填入和條件式問題的邏輯
+ **ValueSets** - 答案選項 （如果 <40 個選項，則自動展開）
+ **QuestionnaireResponse** - 任何現有的進行中或已完成的回應
1. **將所有內容一起封裝**：
+ 封裝所有資源 （每個資源僅包含一次）
+ 如果提供，則依`changedSince`時間戳記篩選
+ `Outcome` 如果遺失任何資源，將警告新增至
**結果**：準備進行轉譯的完整、獨立套件。
## 錯誤回應
### 400 錯誤的請求
請求驗證失敗時傳回。
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "required",
"details": {
"text": "At least one of 'questionnaire' or 'order' must be provided along with 'coverage'"
}
}]
}
```
### 424 失敗相依性
當無法擷取相依資源時傳回。
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "warning",
"code": "not-found",
"details": {
"text": "Referenced Library 'http://example.org/fhir/Library/missing-library' could not be retrieved"
}
}]
}
```
### 401 (未經授權)
當身分驗證憑證遺失或無效時傳回。
### 403 禁止
當已驗證的使用者缺少存取所請求資源的許可時傳回。
### 406 無法接受
當無法提供請求的內容類型時傳回。
### 409 衝突
發生版本或並行衝突時傳回。
### 410 Gone
當請求的資源永久刪除時傳回。
### 429 太多請求
超過速率限制時傳回。
### 500 內部伺服器錯誤
發生非預期的伺服器錯誤時傳回。
### 501 未實作
請求的操作尚未實作時傳回。
## 驗證規則
### 輸入驗證
+ `coverage` 參數為**必要** (1..\$1 基數）
+ 至少`order`必須提供其中一個 `questionnaire`或
+ 所有涵蓋範圍資源都必須是有效的 FHIR 資源
+ 所有訂單資源必須是有效的 FHIR 資源
+ 正式 URLs 必須正確格式化
+ `changedSince` 必須是有效的 ISO 8601 dateTime
### QuestionnaireResponse驗證
+ `status` 必須適當 (`in-progress`、`completed`、`amended`)
+ 結構必須符合參考的問卷
+ `basedOn` 必須參考有效的訂單資源
+ `subject` 必須參考有效的病患資源
### 資源重複資料刪除
+ 每個資源只會在套件中出現一次
+ 例外狀況：可能同時包含相同資源的不同版本
+ 透過其正式 URL 和版本來識別資源
## 效能規格
| 指標 | 規格 |
| --- | --- |
| 資源計數限制 | 每個套件 500 個資源 |
| 套件大小限制 | 最多 5 MB |
## 所需的許可
若要使用 `$questionnaire-package`操作，請確定您的 IAM 角色具有：
+ `healthlake:QuestionnairePackage` - 呼叫 操作
+ `healthlake:ReadResource` - 擷取問卷和相依資源
+ `healthlake:SearchWithPost` - 搜尋 QuestionnaireResponse和相關資源
**FHIR 範圍上的 SMART**
**所需範圍下限：**
+ **SMART v1**： `user/Questionnaire.read user/Library.read user/ValueSet.read user/QuestionnaireResponse.read`
+ **SMART v2**： `user/Questionnaire.rs user/Library.rs user/ValueSet.rs user/QuestionnaireResponse.rs`
## 重要實作備註
### 資源擷取策略
**問卷識別優先順序：**
+ **正式 URL **（如果提供`questionnaire`參數） - 最高優先順序
+ **訂單分析** （如果提供 `order` 參數）：
+ 比對訂單代碼 (CPT、HCPCS、LOINC) 與付款人醫療政策
+ 使用涵蓋範圍付款人篩選付款人特定的問卷
+ 考慮其他內容的原因代碼
### 相依性解析
**CQL 程式庫：**
+ 透過問卷資源上的`cqf-library`擴充功能擷取
+ 透過 `Library.relatedArtifact`類型以遞迴方式擷取相依程式庫 `depends-on`
+ 套件中包含所有程式庫相依性
**ValueSets：**
+ 如果包含的概念少於 40 個，則自動擴展
+ 包含較大的 ValueSets，無需擴展
+ 包括問卷和程式庫資源中參考ValueSets
### QuestionnaireResponse預先填入
下列情況下，操作可能會傳回具有預先填入資料的 QuestionnaireResponse：
+ 找到現有的進行中或已完成的回應
+ 關聯程式庫中的 CQL 邏輯可以從病患記錄擷取資料
+ 回應會連結到相關順序和涵蓋範圍
**QuestionnaireResponse的搜尋條件：**
| 搜尋參數 | FHIR 路徑 | Description |
| --- | --- | --- |
| based-on | QuestionnaireResponse.basedOn | ServiceRequest 或 CarePlan 的連結 |
| patient | QuestionnaireResponse.subject | 做為主體的患者 |
| questionnaire | QuestionnaireResponse.questionnaire | 回答的問卷 |
### 變更資源篩選
提供 `changedSince` 參數時：
+ 僅包含指定時間戳記**後**修改的資源
+ 如果沒有變更任何資源， `200 OK` 會以空的套件傳回
+ 適用於增量更新和快取策略
+ 時間戳記比較使用資源`meta.lastUpdated`欄位
### 多個套件套件
下列情況下，操作可能會傳回**多個套件套件**：
+ 透過正式 URLs請求多個問卷
+ 多個訂單需要不同的問卷
+ 相同問卷的不同版本適用
每個套件套件都與所有必要的相依性獨立。
## 常用案例
### 使用案例 1：預先授權文件
**案例**：提供者需要收集家庭供氧治療預先授權的文件。
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "coverage",
"resource": { /* Patient's insurance coverage */ }
},
{
"name": "order",
"resource": {
"resourceType": "ServiceRequest",
"code": {
"coding": [{
"system": "http://www.ama-assn.org/go/cpt",
"code": "94660"
}]
}
}
}
]
}
```
**結果**：傳回包含氧氣治療問卷的套件，預先填入來自 EHR 的患者生命值和診斷碼。
### 使用案例 2：擷取特定問卷版本
**案例**：供應商需要特定版本的問卷才能合規。
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "coverage",
"resource": { /* Coverage resource */ }
},
{
"name": "questionnaire",
"valueCanonical": "http://example.org/fhir/Questionnaire/dme-request|3.1.0"
}
]
}
```
**結果**：傳回含所有相依性的確切版本 3.1.0 的 DME 請求問卷。
### 使用案例 3：檢查更新
**案例**：供應商想要檢查自上次擷取以來是否有任何問卷資源已更新。
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "coverage",
"resource": { /* Coverage resource */ }
},
{
"name": "questionnaire",
"valueCanonical": "http://example.org/fhir/Questionnaire/medication-request"
},
{
"name": "changedSince",
"valueDateTime": "2024-03-01T00:00:00Z"
}
]
}
```
**結果**：僅傳回在 2024 年 3 月 1 日之後修改的資源，如果沒有變更，則傳回空白套件。
### 使用案例 4：多個訂單
**案例**：供應商提交多個可能需要不同問卷的服務請求。
```
{
"resourceType": "Parameters",
"parameter": [
{
"name": "coverage",
"resource": { /* Coverage resource */ }
},
{
"name": "order",
"resource": { /* ServiceRequest for imaging */ }
},
{
"name": "order",
"resource": { /* ServiceRequest for DME */ }
}
]
}
```
**結果**：傳回多個套件套件，每個適用的問卷各一個。
## 與其他 Da Vinci IGs整合
### 涵蓋範圍需求探索 (CRD)
**工作流程整合：**
+ 供應商在其 EHR 中訂購服務
+ CRD 勾點觸發，檢查涵蓋範圍需求
+ 付款人回應，指出需要文件
+ 供應商呼叫 `$questionnaire-package` 以擷取文件表單
+ 供應商完成問卷
+ 文件是透過 PAS 或 CDex 提交
### 預先授權支援 (PAS)
**工作流程整合：**
+ 使用 `$questionnaire-package` 擷取文件需求
+ 使用所需的臨床資料完成 QuestionnaireResponse
+ 使用 `Claim/$submit`搭配已完成的 QuestionnaireResponse提交預先授權
+ 使用 檢查狀態 `Claim/$inquire`
### 臨床資料交換 (CDex)
**工作流程整合：**
+ 付款人請求申請其他文件
+ 提供者使用 `$questionnaire-package` 擷取結構化資料收集表單
+ 供應商完成 QuestionnaireResponse
+ 文件會透過 CDex 連接工作流程提交給付款人
## 故障診斷指南
### 問題：未傳回問卷
**可能的原因：**
+ 正式 URL 不符合資料存放區中的任何問卷
+ 訂單代碼未對應至付款人醫療政策中的任何問卷
+ 涵蓋範圍付款人沒有相關聯的問卷
**解決方案：**
+ 確認正式 URL 正確且問卷存在
+ 檢查訂單代碼 (CPT/HCPCS) 是否正確指定
+ 確認付款人組織已設定問卷
### 問題：套件中缺少相依性
**可能的原因：**
+ 參考的程式庫或 ValueSet 不存在於資料存放區中
+ 程式庫參考已中斷或不正確
+ ValueSet 擴展失敗
**解決方案：**
+ 檢查 `Outcome` 參數是否有資源遺失的相關警告
+ 驗證資料存放區中存在所有參考的資源
+ 確保 ValueSet URLs正確且可解決
### 問題：含 changedSince 的空套件
**可能的原因：**
+ 這是預期的行為 - 自指定的時間戳記以來未修改任何資源
**解決方案：**
+ 使用套件的快取版本
+ 移除`changedSince`參數以擷取完整套件
### 問題：未預先填入 QuestionnaireResponse
**可能的原因：**
+ 找不到現有的 QuestionnaireResponse
+ CQL Library 邏輯無法擷取所需的資料
+ 病患資料遺失或不完整
**解決方案：**
+ 這可能是預期的 - 並非所有問卷都有預先填入邏輯
+ 檢查資料存放區中是否存在病患資料
+ 檢閱 CQL Library 邏輯以了解資料擷取需求
## 最佳實務
### 1. 搭配版本使用正式 URLs
請求特定問卷時，請務必指定版本編號：
```
{
"name": "questionnaire",
"valueCanonical": "http://example.org/fhir/Questionnaire/dme|2.1.0"
}
```
**原因**：確保一致性，並防止更新問卷時的意外變更。
### 2. 利用 changedSince for Performance
對於經常存取的問卷，請使用 `changedSince` 將資料傳輸降至最低：
```
{
"name": "changedSince",
"valueDateTime": "2024-03-10T15:30:00Z"
}
```
**原因**：僅擷取更新的資源，以減少延遲和頻寬使用量。
### 3. 包含完整涵蓋範圍資訊
提供全面的涵蓋範圍詳細資訊，以確保正確的問卷選擇：
```
{
"name": "coverage",
"resource": {
"resourceType": "Coverage",
"beneficiary": { "reference": "Patient/123" },
"payor": [{ "reference": "Organization/payer-abc" }],
"class": [{ /* Group/plan information */ }]
}
}
```
**原因**：協助 HealthLake 識別付款人特定的問卷和要求。
## 相關的 操作
+ `Claim/$submit` - 提交包含已完成文件的預先授權請求
+ `Claim/$inquire` - 檢查提交的預先授權狀態
+ `ValueSet/$expand` - 展開用於答案選項的 ValueSets
# HealthLake 的 FHIR `$submit`操作
`$submit` 此操作可讓您以電子方式提交預先授權請求給付款人以進行核准。此操作實作 [Da Vinci 預先授權支援 (PAS) 實作指南](https://hl7.org/fhir/us/davinci-pas/)，為預先授權提交提供標準化的 FHIR 工作流程。
## 運作方式
+ **提交**：您傳送 FHIR 套件，其中包含您的預先授權請求和支援的臨床資料
+ **驗證**：HealthLake 會根據 PAS 要求驗證提交
+ **持久**性：所有資源都存放在 HealthLake 資料存放區中
+ **回應**：您立即收到「佇列」狀態的回應
+ **程序**：由付款人非同步處理授權決策
## API 端點
```
POST /datastore/{datastoreId}/r4/Claim/$submit
Content-Type: application/fhir+json
```
## 請求結構
### 套件需求
您的請求必須是具有下列項目的 FHIR 套件資源：
+ **Bundle.type**：必須為 `"collection"`
+ **Bundle.entry**：必須包含**一個**具有 的宣告資源 `use = "preauthorization"`
+ **參考資源**： 宣告參考的所有資源必須包含在套件中
### 必要的資源
| 資源 | 基數 | 設定檔 | Description |
| --- | --- | --- | --- |
| 宣告 | 1 | PAS 宣告 | 預先授權請求 |
| 病患 | 1 | PAS 病患 | 病患人口統計資訊 |
| Organization （保險業者） | 1 | PAS Insurer | 保險公司 |
| Organization （提供者） | 1 | PAS 請求者 | 提交請求的醫療保健供應商 |
| 涵蓋範圍 | 1 個或多個 | PAS 涵蓋範圍 | 保險涵蓋範圍詳細資訊 |
### 選用資源
| 資源 | 基數 | 設定檔 | Description |
| --- | --- | --- | --- |
| 從業人員 | 0 或以上 | PAS 從業人員 | 醫療保健從業人員 |
| PractitionerRole | 0 或以上 | PAS PractitionerRole | 從業人員角色 |
| ServiceRequest | 0 或以上 | PAS ServiceRequest | 請求的醫療保健 |
| DeviceRequest | 0 或以上 | PAS DeviceRequest | 請求的醫療設備 |
| MedicationRequest | 0 或以上 | PAS MedicationRequest | 請求的藥品 |
| DocumentReference | 0 或以上 | PAS DocumentReference | 支援臨床文件 |
## 範例請求
```
POST /datastore/example-datastore/r4/Claim/$submit
Content-Type: application/fhir+json
Authorization: Bearer
{
"resourceType" : "Bundle",
"id" : "MedicalServicesAuthorizationBundleExample",
"meta" : {
"profile" : ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-pas-request-bundle"]
},
"identifier" : {
"system" : "http://example.org/SUBMITTER_TRANSACTION_IDENTIFIER",
"value" : "5269367"
},
"type" : "collection",
"timestamp" : "2005-05-02T11:01:00+05:00",
"entry" : [{
"fullUrl" : "http://example.org/fhir/Claim/MedicalServicesAuthorizationExample",
"resource" : {
"resourceType" : "Claim",
"id" : "MedicalServicesAuthorizationExample",
"meta" : {
"profile" : ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim"]
},
"identifier" : [{
"system" : "http://example.org/PATIENT_EVENT_TRACE_NUMBER",
"value" : "111099"
}],
"status" : "active",
"type" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/claim-type",
"code" : "professional"
}]
},
"use" : "preauthorization",
"patient" : {
"reference" : "Patient/SubscriberExample"
},
"created" : "2005-05-02T11:01:00+05:00",
"insurer" : {
"reference" : "Organization/InsurerExample"
},
"provider" : {
"reference" : "Organization/UMOExample"
},
"priority" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/processpriority",
"code" : "normal"
}]
},
"insurance" : [{
"sequence" : 1,
"focal" : true,
"coverage" : {
"reference" : "Coverage/InsuranceExample"
}
}],
"item" : [{
"extension" : [{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-serviceItemRequestType",
"valueCodeableConcept" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/1525",
"code" : "IN",
"display" : "Initial Medical Services Reservation"
}]
}
},
{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-certificationType",
"valueCodeableConcept" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/1322",
"code" : "I",
"display" : "Initial"
}]
}
},
{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-authorizationNumber",
"valueString" : "1122344"
},
{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-administrationReferenceNumber",
"valueString" : "33441122"
}],
"sequence" : 1,
"category" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/1365",
"code" : "1",
"display" : "Medical Care"
}]
},
"productOrService" : {
"coding" : [{
"system" : "http://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets",
"code" : "99212",
"display" : "Established Office Visit"
}]
},
"servicedDate" : "2005-05-10",
"locationCodeableConcept" : {
"coding" : [{
"system" : "https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set",
"code" : "11"
}]
}
}]
}
},
{
"fullUrl" : "http://example.org/fhir/Organization/UMOExample",
"resource" : {
"resourceType" : "Organization",
"id" : "UMOExample",
"meta" : {
"profile" : ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-requestor"]
},
"identifier" : [{
"system" : "http://hl7.org/fhir/sid/us-npi",
"value" : "8189991234"
}],
"active" : true,
"type" : [{
"coding" : [{
"system" : "https://codesystem.x12.org/005010/98",
"code" : "X3"
}]
}],
"name" : "DR. JOE SMITH CORPORATION",
"address" : [{
"line" : ["111 1ST STREET"],
"city" : "SAN DIEGO",
"state" : "CA",
"postalCode" : "92101",
"country" : "US"
}]
}
},
{
"fullUrl" : "http://example.org/fhir/Organization/InsurerExample",
"resource" : {
"resourceType" : "Organization",
"id" : "InsurerExample",
"meta" : {
"profile" : ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-insurer"]
},
"identifier" : [{
"system" : "http://hl7.org/fhir/sid/us-npi",
"value" : "1234567893"
}],
"active" : true,
"type" : [{
"coding" : [{
"system" : "https://codesystem.x12.org/005010/98",
"code" : "PR"
}]
}],
"name" : "MARYLAND CAPITAL INSURANCE COMPANY"
}
},
{
"fullUrl" : "http://example.org/fhir/Coverage/InsuranceExample",
"resource" : {
"resourceType" : "Coverage",
"id" : "InsuranceExample",
"meta" : {
"profile" : ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-coverage"]
},
"status" : "active",
"subscriberId" : "1122334455",
"beneficiary" : {
"reference" : "Patient/SubscriberExample"
},
"relationship" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
"code" : "self"
},
{
"system" : "https://codesystem.x12.org/005010/1069",
"code" : "18"
}]
},
"payor" : [{
"reference" : "Organization/InsurerExample"
}]
}
},
{
"fullUrl" : "http://example.org/fhir/Patient/SubscriberExample",
"resource" : {
"resourceType" : "Patient",
"id" : "SubscriberExample",
"meta" : {
"profile" : ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-subscriber"]
},
"extension" : [{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-militaryStatus",
"valueCodeableConcept" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/584",
"code" : "RU"
}]
}
}],
"identifier" : [{
"type" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0203",
"code" : "MB"
}]
},
"system" : "http://example.org/MIN",
"value" : "12345678901"
}],
"name" : [{
"family" : "SMITH",
"given" : ["JOE"]
}],
"gender" : "male"
}
}]
}
```
## 回應格式
### 成功回應 (200 OK)
您將會收到 PAS 回應套件，其中包含：
+ 使用 `outcome: "queued"`和 的 **ClaimResponse** `status: "active"`
+ 請求中的所有原始資源
+ 確認接收的時間戳記
```
{
"resourceType" : "Bundle",
"identifier": {
"system": "http://example.org/SUBMITTER_TRANSACTION_IDENTIFIER",
"value": "5269367"
},
"type" : "collection",
"timestamp" : "2005-05-02T11:02:00+05:00",
"entry" : [{
"fullUrl" : "http://example.org/fhir/ClaimResponse/PractitionerRequestorPendingResponseExample",
"resource" : {
"resourceType" : "ClaimResponse",
"id" : "PractitionerRequestorPendingResponseExample",
"meta" : {
"profile" : ["http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claimresponse"]
},
"identifier" : [{
"system" : "http://example.org/PATIENT_EVENT_TRACE_NUMBER",
"value" : "111099"
}],
"status" : "active",
"type" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/claim-type",
"code" : "professional"
}]
},
"use" : "preauthorization",
"patient" : {
"reference" : "Patient/SubscriberExample"
},
"created" : "2005-05-02T11:02:00+05:00",
"insurer" : {
"reference" : "Organization/InsurerExample"
},
"requestor" : {
"reference" : "PractitionerRole/ReferralPractitionerRoleExample"
},
"request" : {
"reference" : "Claim/MedicalServicesAuthorizationExample"
},
"outcome" : "queued"
}
},
{
"fullUrl" : "http://example.org/fhir/Claim/MedicalServicesAuthorizationExample",
"resource" : {
"resourceType" : "Claim",
"id" : "MedicalServicesAuthorizationExample",
"meta" : {
"profile": [
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim",
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-claim|2.1.0"
]
},
"identifier" : [{
"system" : "http://example.org/PATIENT_EVENT_TRACE_NUMBER",
"value" : "111099"
}
}],
"status" : "active",
"type" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/claim-type",
"code" : "professional"
}]
},
"use" : "preauthorization",
"patient" : {
"reference" : "Patient/SubscriberExample"
},
"created" : "2005-05-02T11:01:00+05:00",
"insurer" : {
"reference" : "Organization/InsurerExample"
},
"provider" : {
"reference" : "Organization/UMOExample"
},
"priority" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/processpriority",
"code" : "normal"
}]
},
"insurance" : [{
"sequence" : 1,
"focal" : true,
"coverage" : {
"reference" : "Coverage/InsuranceExample"
}
}],
"item" : [{
"extension" : [{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-serviceItemRequestType",
"valueCodeableConcept" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/1525",
"code" : "IN",
"display" : "Initial Medical Services Reservation"
}]
}
},
{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-certificationType",
"valueCodeableConcept" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/1322",
"code" : "I",
"display" : "Initial"
}]
}
},
{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-authorizationNumber",
"valueString" : "1122344"
},
{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-administrationReferenceNumber",
"valueString" : "33441122"
}],
"sequence" : 1,
"category" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/1365",
"code" : "1",
"display" : "Medical Care"
}]
},
"productOrService" : {
"coding" : [{
"system" : "http://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets",
"code" : "99212",
"display" : "Established Office Visit"
}]
},
"servicedDate" : "2005-05-10",
"locationCodeableConcept" : {
"coding" : [{
"system" : "https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set",
"code" : "11"
}]
}
}]
}
},
{
"fullUrl" : "http://example.org/fhir/Organization/UMOExample",
"resource" : {
"resourceType" : "Organization",
"id" : "UMOExample",
"meta" : {
"profile": [
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-requestor",
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-requestor|2.1.0"
]
},
"identifier" : [{
"system" : "http://hl7.org/fhir/sid/us-npi",
"value" : "8189991234"
}],
"active" : true,
"type" : [{
"coding" : [{
"system" : "https://codesystem.x12.org/005010/98",
"code" : "X3"
}]
}],
"name" : "DR. JOE SMITH CORPORATION",
"address" : [{
"line" : ["111 1ST STREET"],
"city" : "SAN DIEGO",
"state" : "CA",
"postalCode" : "92101",
"country" : "US"
}]
}
},
{
"fullUrl" : "http://example.org/fhir/Organization/InsurerExample",
"resource" : {
"resourceType" : "Organization",
"id" : "InsurerExample",
"meta" : {
"profile": [
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-insurer",
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-insurer|2.1.0"
]
},
"identifier" : [{
"system" : "http://hl7.org/fhir/sid/us-npi",
"value" : "1234567893"
}],
"active" : true,
"type" : [{
"coding" : [{
"system" : "https://codesystem.x12.org/005010/98",
"code" : "PR"
}]
}],
"name" : "MARYLAND CAPITAL INSURANCE COMPANY"
}
},
{
"fullUrl" : "http://example.org/fhir/Coverage/InsuranceExample",
"resource" : {
"resourceType" : "Coverage",
"id" : "InsuranceExample",
"meta": {
"profile": [
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-coverage",
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-coverage|2.1.0"
]
},
"status" : "active",
"subscriberId" : "1122334455",
"beneficiary" : {
"reference" : "Patient/SubscriberExample"
},
"relationship" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/subscriber-relationship",
"code" : "self"
},
{
"system" : "https://codesystem.x12.org/005010/1069",
"code" : "18"
}]
},
"payor" : [{
"reference" : "Organization/InsurerExample"
}]
}
},
{
"fullUrl" : "http://example.org/fhir/Patient/SubscriberExample",
"resource" : {
"resourceType" : "Patient",
"id" : "SubscriberExample",
"meta": {
"profile": [
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-subscriber",
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-beneficiary",
"http://hl7.org/fhir/us/davinci-pas/StructureDefinition/profile-beneficiary|2.1.0"
]
},
"extension" : [{
"url" : "http://hl7.org/fhir/us/davinci-pas/StructureDefinition/extension-militaryStatus",
"valueCodeableConcept" : {
"coding" : [{
"system" : "https://codesystem.x12.org/005010/584",
"code" : "RU"
}]
}
}],
"identifier" : [{
"type" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v2-0203",
"code" : "MB"
}]
},
"system" : "http://example.org/MIN",
"value" : "12345678901"
}],
"name" : [{
"family" : "SMITH",
"given" : ["JOE"]
}],
"gender" : "male"
}
}]
}
```
## 錯誤回應
### 400 錯誤的請求
當請求格式無效或格式不正確時傳回。
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "invalid",
"diagnostics": "The provided payload was invalid and could not be parsed correctly."
}]
}
```
### 412 先決條件失敗
已提交相同的預先授權請求時傳回 （偵測到重複提交）。
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "processing",
"diagnostics": "PreAuth Claim already exists"
}]
}
```
**冪等性**
`$submit` 操作是等冪的。多次提交相同的請求不會建立重複的預先授權請求。反之，您會收到 412 錯誤，指示您使用 `$inquire`來檢查原始提交的狀態。
### 422 無法處理的實體
FHIR 驗證失敗時傳回。
```
{
"resourceType": "OperationOutcome",
"issue": [{
"severity": "error",
"code": "required",
"diagnostics": "Bundle contains more than one preauthorization claim"
}]
}
```
## 驗證規則
HealthLake 會對您的提交執行全面的驗證：
### 套件驗證
+ 必須符合 PAS 請求套件描述檔
+ `Bundle.type` 必須 `"collection"`
+ 可以包含多個宣告資源
+ 不過， 必須包含一個具有預先授權使用的宣告資源
+ 此宣告資源必須是套件中的第一個項目
+ 套件中必須包含所有參考的資源
### 宣告驗證
+ 必須符合 PAS 宣告描述檔
+ `Claim.use` 必須 `"preauthorization"`
+ 必要欄位：`patient`、`insurer`、`provider`、`created`、 `priority`
+ 業務識別符必須存在且有效
### 資源驗證
+ 所有資源必須符合其各自的 PAS 設定檔
+ 必要的支援資源必須存在 （病患、涵蓋範圍、組織）
+ 交互參考在套件中必須是有效且可解析的
## 效能規格
| 指標 | 規格 |
| --- | --- |
| 套件大小限制 | 最多 5 MB |
| 資源計數限制 | 每個套件 500 個資源 |
## 所需的許可
若要使用 `$submit`操作，使用者可以在 FHIR 上使用 AWS Sigv4 或 SMART：
+ 確保您的 IAM 角色具有：`healthlake:SubmitPreAuthClaim`- 呼叫 操作
**FHIR 範圍上的 SMART**
**所需範圍下限：**
+ **SMART v1**： `user/Claim.write & .write`
+ **SMART v2**： `user/Claim.c & .c or system/*.*`
## 重要實作備註
### 資源持久性
+ 所有套件項目都會保留為資料存放區中的個別 FHIR 資源
+ 客戶提供IDs 會在提供時保留
+ 維護版本歷史記錄以供稽核之用
+ 重複偵測可防止資源衝突
### 處理行為
+ 每個有效的提交只會產生一個 ClaimResponse `"queued"`結果
+ 無效提交會傳回 400 或 422 狀態碼，其中包含詳細的錯誤資訊
+ 系統錯誤會傳回適當的 5xx 狀態碼
+ 所有成功的提交都會傳回 200 狀態與待定的 ClaimResponse
### 套件需求
+ `Bundle.entry.fullUrl` 值必須是 REST URLs或`"urn:uuid:[guid]"`格式
+ 所有 GUIDs提交之間必須是唯一的 （相同資源執行個體除外）
+ 參考的資源必須存在於套件中或可解析
## 相關的 操作
+ `Claim/$inquire` - 查詢提交的預先授權請求的狀態
+ `Patient/$everything` - 針對預先授權內容擷取完整的患者資料
# 使用 驗證 FHIR 資源 `$validate`
AWS HealthLake 現在支援 FHIR 資源`$validate`的操作，可讓您根據 FHIR 規格驗證資源，並檢查其是否符合指定的設定檔或基本資源定義，而無需執行任何儲存操作。當您需要：
+ 驗證 FHIR CMS 合規要求
+ 在生產環境中使用資源之前進行測試
+ 在使用者編輯臨床資料時提供即時驗證意見回饋
+ 減少無效的資料提交以建立和更新 APIs
## Usage
您可以使用 POST 方法在 FHIR 資源上叫用 `$validate`操作：
**受支援的 操作**
```
POST [base]/[type]/[id]/$validate
POST [base]/[type]/$validate
```
## 支援的承載
**參數資源**
HealthLake 支援下列 FHIR `$validate` 參數：
| 參數 | Type | 必要 | Description |
| --- | --- | --- | --- |
| resource | 資源 | 是 | 要驗證的資源 |
| profile | 正式 | 否 | 要驗證之設定檔的正式 URL |
| mode | code | 否 | 驗證模式： create或 update |
**具有查詢參數的直接資源**
| 參數 | Type | 必要 | Description |
| --- | --- | --- | --- |
| profile | 正式 | 否 | 要驗證之設定檔的正式 URL |
| mode | code | 否 | 驗證模式： create或 update |
## 範例
**具有 ID 和參數承載之資源的 POST 請求**
```
POST [base]/Patient/example-patient/$validate
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "resource",
"resource": {
"resourceType": "Patient",
"id": "example-patient",
"name": [
{
"family": "Smith",
"given": ["John"]
}
],
"gender": "male",
"birthDate": "1990-01-01"
}
},
{
"name": "profile",
"valueCanonical": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
},
{
"name": "mode",
"valueString": "create"
}
]
}
```
**資源類型和參數承載的 POST 請求**
```
POST [base]/Patient/$validate
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "resource",
"resource": {
"resourceType": "Patient",
"name": [
{
"family": "Doe",
"given": ["Jane"]
}
],
"gender": "female",
"birthDate": "1985-05-15"
}
},
{
"name": "profile",
"valueCanonical": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
},
{
"name": "mode",
"valueString": "update"
}
]
}
```
**具有 ID 和直接資源承載的資源 POST 請求**
```
POST [base]/Patient/example-patient/$validate?profile=http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient&mode=create
Content-Type: application/fhir+json
{
"resourceType": "Patient",
"id": "example-patient",
"name": [
{
"family": "Smith",
"given": ["John"]
}
],
"gender": "male",
"birthDate": "1990-01-01"
}
```
**資源類型和直接資源承載的 POST 請求**
```
POST [base]/Patient/$validate?profile=http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient&mode=create
Content-Type: application/fhir+json
{
"resourceType": "Patient",
"id": "example-patient",
"name": [
{
"family": "Smith",
"given": ["John"]
}
],
"gender": "male",
"birthDate": "1990-01-01"
}
```
**回應範例**
操作會傳回具有驗證結果的 OperationOutcome 資源：
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "Validation successful"
}
]
}
```
**驗證錯誤的回應範例**
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "required",
"details": {
"text": "Missing required element"
},
"diagnostics": "Patient.identifier is required by the US Core Patient profile",
"location": [
"Patient.identifier"
]
},
{
"severity": "warning",
"code": "code-invalid",
"details": {
"text": "Invalid code value"
},
"diagnostics": "The provided gender code is not from the required value set",
"location": [
"Patient.gender"
]
}
]
}
```
## Behavior (行為)
`$validate` 操作：
1. 根據 FHIR 規格和基本資源定義驗證資源
1. 提供 `profile` 參數時，檢查是否符合指定的設定檔
1. 根據指定的模式進行驗證 (`create` 或 `update`)
1. 傳回詳細的驗證結果，包括錯誤、警告和資訊性訊息
1. 不執行任何儲存操作 - 僅驗證
1. 在可執行驗證時傳回 HTTP 200 OK，無論是否發現驗證問題
## 驗證模式
+ **create**：將資源驗證為正在建立 （新資源）
+ **更新**：將資源驗證為正在更新 （現有資源）
## 錯誤處理
操作會傳回：
+ 200 OK：已成功執行驗證 （無論驗證結果為何）
+ 400 錯誤的請求：無效的請求格式或參數
+ 找不到 404：找不到資源類型或設定檔
如需 `$validate`操作規格的詳細資訊，請參閱 [FHIR R4 資源`$validate`](https://www.hl7.org/fhir/R4/operation-resource-validate.html)文件。
# 的合規參考 AWS HealthLake
AWS HealthLake 提供旨在協助您追蹤和報告 API 用量的功能，以符合 CMS (Centers for Medicare & Medicaid Services) 互通性需求。這些功能可讓您依 CMS 指定的類別來分類 API 交易，並自動擷取用量指標以供合規報告之用。
**了解您的合規責任**
使用 AWS HealthLake 及其 CMS 互通性端點**本身不足以**達成 CMS 合規。您負責：
根據您的特定使用案例和法規義務，將 API 工作流程正確映射至適當的 CMS 類別端點
實作符合 CMS 要求的適當身分驗證和授權控制
確保您的 FHIR 資源和資料交換符合適用的 CMS 法規和實作指南
設定和監控 CloudWatch 指標，以支援您的合規報告需求
了解哪些 CMS 規則適用於您的組織，並實作適當的技術和操作控制
AWS HealthLake 提供基礎設施和工具以支援您的合規工作，但您必須根據您的特定法規要求適當地使用這些功能。只要透過這些端點路由 API 呼叫，您的應用程式就不會自動符合 CMS 法規。
**Topics**
+ [CMS](reference-compliance-cms.md)
# CMS 合規功能
AWS HealthLake 提供 功能，協助您符合 CMS (Centers for Medicare & Medicaid Services) 互通性和合規要求。這些功能可讓您依 CMS 類別追蹤 API 用量，然後基於合規目的報告用量指標。
**Topics**
+ [CMS 互通性端點](#cms-interoperability-endpoints)
+ [CMS 合規的增強型 CloudWatch 指標](#cms-cloudwatch-metrics)
## CMS 互通性端點
### 概觀
HealthLake 提供四個對應於 CMS 指定 API 類別的 CMS 互通性端點。HealthLake 資料存放區的基礎 URL 不會變更。這些端點僅提供針對 CMS 報告目的分類和追蹤 API 呼叫的方法。
### 用途
這些互通性端點的主要目的是讓客戶能夠：
+ 依 CMS 類別**輕鬆追蹤** API 交易
+ **自動報告** CMS 合規的用量指標
+ 以最少的變更**維護**現有的 FHIR 工作流程
無論您使用互通性端點或標準 FHIR 端點，所有 API 呼叫的功能都相同 - 唯一的區別是如何在 CloudWatch 指標中分類交易。
### 支援的 CMS 互通性端點
| CMS 類別 | 互通性端點 | 使用範例 |
| --- | --- | --- |
| 病患存取 | /patientaccess/v2/r4 | baseURL/patientaccess/v2/r4/Patient/123 |
| 提供者存取 | /provideraccess/v2/r4 | baseURL/provideraccess/v2/r4/Observation?patient=123 |
| 付款人到付款人 | /payertopayerdx/v2/r4 | baseURL/payertopayerdx/v2/r4/Practitioner/456 |
| 先前的驗證服務 | /priorauthservice/v2/r4 | baseURL/priorauthservice/v2/r4/ExplanationOfBenefit?patient=789 |
### 互通性端點的運作方式
**標準 HealthLake API 呼叫：**
```
baseURL/resourceType/[id]
baseURL/resourceType?[parameters]
```
**使用 CMS 互通性端點：**
```
baseURL/interoperability-endpoint/resourceType/[id]
baseURL/interoperability-endpoint/resourceType?[parameters]
```
互通性端點路徑只會插入您的基本 URL 和資源類型之間。互通性端點路徑之後的所有內容都與您目前的 API 呼叫完全相同。
### 使用範例
#### 範例 1：病患存取 API
**目前的 API 呼叫 （仍然有效）：**
```
curl -X GET \
https://healthlake.us-east-1.amazonaws.com/datastore/abc123/r4/Patient/123 \
-H "Authorization: Bearer " \
-H "Content-Type: application/fhir+json"
```
**使用病患存取互通性端點 （用於 CMS 追蹤）：**
```
curl -X GET \
https://healthlake.us-east-1.amazonaws.com/datastore/abc123/patientaccess/v2/r4/Patient/123 \
-H "Authorization: Bearer " \
-H "Content-Type: application/fhir+json"
```
**重點：**
+ 保留基本 URL： `https://healthlake.us-east-1.amazonaws.com/datastore/abc123`
+ 插入的互通性端點： `/patientaccess/v2/r4`
+ 資源路徑不變： `/Patient/123`
+ **兩個呼叫都會傳回相同的回應**
+ CloudWatch `URIType=patient-access`中的 會自動追蹤互通性端點呼叫
+ POST、PUT、PATCH、DELETE 操作的運作方式相同。
+ 請求內文保持不變。
### 端點轉譯參考
| 互通性端點 | 轉換為 | CMS 類別 |
| --- | --- | --- |
| baseURL/patientaccess/v2/r4/Patient | baseURL/r4/Patient | 病患存取 |
| baseURL/provideraccess/v2/r4/Observation | baseURL/r4/Observation | 提供者存取 |
| baseURL/payertopayerdx/v2/r4/Practitioner/456 | baseURL/r4/Practitioner/456 | 付款人對付款人資料交換 |
| baseURL/priorauthservice/v2/r4/ExplanationOfBenefit?patient=789 | baseURL/r4/ExplanationOfBenefit?patient=789 | 預先授權 |
### 重要說明
+ **沒有功能差異**：互通性端點和標準 FHIR 端點會傳回相同的回應，並支援相同的操作
+ **基本 URL 未變更**：您的 HealthLake 資料存放區端點保持不變
+ **簡易整合**：在您的基本 URL 和資源類型之間插入互通性端點路徑
+ **自動追蹤**：CloudWatch 指標會依使用的互通性端點自動分類呼叫
+ **回溯相容**：沒有互通性端點的現有 API 呼叫會繼續正常運作
## CMS 合規的增強型 CloudWatch 指標
### 概觀
當您使用 CMS 互通性端點時，HealthLake 會自動發出具有額外維度的增強型 CloudWatch 指標，以支援 CMS 報告需求。這些指標會依呼叫者身分、應用程式和 CMS 特定的 URI 類型追蹤 API 用量，**而不需要任何其他組態**。
### 運作方式
當您使用互通性端點進行 API 呼叫時：
```
# This call...
curl https://healthlake.us-east-1.amazonaws.com/datastore/abc123/patientaccess/v2/r4/Patient/123
# Automatically generates metrics with:
# - URIType: "patient-access"
# - Sub: extracted from your bearer token (SMART on FHIR datastores only)
# - ClientId: extracted from your bearer token (SMART on FHIR datastores only)
# - Plus all standard dimensions (DatastoreId, Operation, etc.)
```
**不需要額外的程式碼或組態。**只需使用互通性端點，即可自動擷取增強型指標。
**注意**
對於 FHIR 資料存放區上的非 SMART，仍會擷取`URIType`維度，讓您可以依 CMS 類別追蹤 API 用量。只有在 FHIR 身分驗證上使用 SMART 搭配包含這些宣告的承載字符時，才能使用 `Sub`和 `ClientId`維度。
### 新的指標維度
除了現有的維度 (`DatastoreId`、`DatastoreType`、`Operation`) 之外，使用互通性端點時也會自動新增下列維度：
| 維度 | Description | 範例數值 | 來源 |
| --- | --- | --- | --- |
| URIType | CMS 合規類別 | patient-access, provider-access, payer-to-payer, prior-authorization | 從互通性端點路徑自動確定 |
| 子 | 來電者身分 | 使用者/實體識別符 | 從承載字符sub宣告擷取 |
| ClientId | 應用程式識別符 | portal\$1app, ehr\$1system | 從承載字符client\$1id宣告擷取 |
### 可用的指標
所有現有的 HealthLake 指標現在都包含使用互通性端點時的額外維度：
+ **CallCount** - API 呼叫總數
+ **延遲** - API 回應時間，以毫秒為單位
+ **UserErrors** - 4xx 用戶端錯誤計數
+ **SystemErrors** - 5xx 伺服器錯誤的計數
+ **限流** - 限流請求的計數
+ **SuccessfulRequests** - 成功 API 呼叫的計數
### 在 CloudWatch 中查詢指標
#### CloudWatch Insights 查詢範例
**依應用程式查詢所有病患存取 API 呼叫：**
```
SELECT SUM(CallCount)
FROM "AWS/HealthLake"
WHERE DatastoreId = '75c1cf9b0d71cd38fec8f7fb317c4c1a'
AND URIType = 'patient-access'
GROUP BY ClientId
```
# 的支援參考 AWS HealthLake
下列支援參考資料可供 使用 AWS HealthLake。
**注意**
所有原生 HealthLake 動作和資料類型會在單獨的參考中描述。如需詳細資訊，請參閱 [https://docs.aws.amazon.com/healthlake/latest/APIReference/](https://docs.aws.amazon.com/healthlake/latest/APIReference/)。
**Topics**
+ [端點和配額](reference-healthlake-endpoints-quotas.md)
+ [預先載入的資料類型](reference-healthlake-preloaded-data-types.md)
+ [專案範例](reference-healthlake-sample-projects.md)
+ [疑難排解](reference-healthlake-troubleshooting.md)
+ [使用 AWS SDKs](sdk-general-information-section.md)
# AWS HealthLake 端點和配額
下列主題包含 AWS HealthLake 服務端點和配額的相關資訊。
**Topics**
+ [服務端點](#reference-healthlake-endpoints)
+ [Service Quotas](#reference-healthlake-quotas)
## 服務端點
服務端點是識別主機和連接埠做為 Web 服務進入點的 URL。每個 Web 服務請求都會包含一個端點。大多數 AWS 服務為特定區域提供端點，以實現更快的連線能力。下表列出 的服務端點 AWS HealthLake。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/healthlake/latest/devguide/reference-healthlake-endpoints-quotas.html)
## Service Quotas
服務配額定義為您 AWS 帳戶中資源、動作和項目的最大值。
**注意**
對於可調整配額，您可以使用 [Service Quotas 主控台](https://console.aws.amazon.com/servicequotas/)請求增加配額。如需詳細資訊，請參閱「Service Quotas 使用者指南」**中的[請求提高配額](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html)。
同步寫入 API 速率會隨著承載大小按比例增加，每增加 1KB 會消耗額外的容量 （例如，4KB 承載會使用 4 倍的寫入容量）。將選用`x-amz-fhir-history-consistency-level`標頭設定為 會使每個資源的寫入容量消耗`strong`加倍。
套件內的資源會遵循以 1 KB 承載大小為基礎的標準讀取/寫入限制。套件類型*交易*使用的寫入容量是類型*批次*的兩倍，這表示*批次*套件每秒可以處理兩倍於交易套件的資源。
下表列出 的預設配額 AWS HealthLake。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/healthlake/latest/devguide/reference-healthlake-endpoints-quotas.html)
# HealthLake 的 Synthea 預先載入資料類型
HealthLake 僅支援 SYNTHEA 作為預先載入的資料類型。[Synthea](https://synthetichealth.github.io/synthea/) 是一種合成患者產生器，可建立`Patient`醫療歷史記錄的模型。它託管在開放原始碼 Git 儲存庫中，該儲存庫允許 HealthLake 產生 FHIR R4-compliant資源，`Bundle`讓使用者可以在不使用實際患者資料的情況下測試模型。
下列資源類型可在預先載入的 HealthLake 資料存放區中使用。如需使用 Synthea 資料預先載入 HealthLake 資料存放區的詳細資訊，請參閱 [建立 HealthLake 資料存放區](managing-data-stores-create.md)。
**注意**
若要檢視 HealthLake 支援的 FHIR R4 資源的完整清單，請參閱 [HealthLake 的 FHIR R4 支援的資源類型](reference-fhir-resource-types.md)。
**HealthLake 支援的 Synthea FHIR 資源類型**
| | |
| --- |--- |
| AllergyIntolerance | Location |
| CarePlan | MedicationAdministration |
| CareTeam | MedicationRequest |
| 取得 | 觀察 |
| 條件 | 組織 |
| 裝置 | 病患 |
| DiagnosticReport | 從業人員 |
| 遇到 | PractitionerRole |
| ExplanationofBenefit | 程序 |
| ImagingStudy | 證明 |
| 預防 | |
# AWS HealthLake 範例專案
若要進一步分析，您可以搭配其他 AWS 服務使用 HealthLake，如下列部落格文章範例所示。
**HealthLake 整合式分析**
+ [人口運作狀態應用程式 AWS HealthLake – 第 1 部分：使用 Amazon Quick 進行分析和監控](https://aws.amazon.com/blogs/machine-learning/population-health-applications-with-amazon-healthlake-part-1-analytics-and-monitoring-using-amazon-quicksight/)。
+ [使用具有 AWS HealthLake 標準化資料的 Amazon SageMaker AI 建置預測性疾病模型](https://aws.amazon.com/blogs/machine-learning/building-predictive-disease-models-using-amazon-sagemaker-with-amazon-healthlake-normalized-data/)。
+ [使用 AWS AI 服務建立認知搜尋和運作狀態知識圖表](https://aws.amazon.com/blogs/machine-learning/build-a-cognitive-search-and-a-health-knowledge-graph-using-amazon-healthlake-amazon-kendra-and-amazon-neptune/)。
**HealthLake 事件監控**
+ [Amazon EventBridge 與 整合 AWS HealthLake](https://aws.amazon.com/blogs/industries/amazon-eventbridge-integration-for-aws-healthlake/)。
# 故障診斷 AWS HealthLake
下列主題提供使用 、 AWS CLI AWS SDKs 或 HealthLake 主控台時可能遇到的錯誤和問題的疑難排解建議。如果您發現本節未列出的問題，請使用此頁面右側的**提供意見回饋**按鈕進行報告。
**Topics**
+ [資料存放區動作](#troubleshooting-data-store)
+ [匯入動作](#troubleshooting-import)
+ [FHIR APIs](#troubleshooting-fhir-apis)
+ [NLP 整合](#troubleshooting-nlp-integrations)
+ [SQL 整合](#troubleshooting-sql-integrations)
## 資料存放區動作
**問題：***當我嘗試建立 HealthLake 資料存放區時，會收到下列錯誤：*
```
AccessDeniedException: Insufficient Lake Formation permission(s): Required Database on Catalog
```
2022 年 11 月 14 日，HealthLake 更新了建立新資料存放區所需的 IAM 許可。如需詳細資訊，請參閱[設定 IAM 使用者或角色以使用 HealthLake (IAM 管理員）](getting-started-setting-up.md#setting-up-configure-iam)。
**問題：***使用 AWS SDKs 建立 HealthLake 資料存放區時，資料存放區建立狀態會傳回例外狀況或未知狀態。*
如果您的 `DescribeFHIRDatastore`或 `ListFHIRDatastores` API 呼叫傳回例外狀況或未知的資料存放區狀態，請將 SDK 更新 AWS 為最新版本。
## 匯入動作
**問題：***如果我的資料不是 FHIR R4 格式，我是否仍然可以使用 HealthLake？*
只有 FHIR R4 格式的資料可以匯入 HealthLake 資料存放區。如需可協助將現有運作狀態資料轉換為 FHIR R4 格式的合作夥伴清單，請參閱 [AWS HealthLake 合作夥伴](https://docs.aws.amazon.com/healthlake/partners/)。
**問題：***為什麼我的 FHIR 匯入任務失敗？*
成功的匯入任務將產生具有`.ndjson`格式結果 （輸出日誌） 的資料夾，不過，個別記錄可能無法匯入。發生這種情況時，會產生第二個`FAILURE`資料夾，其中包含無法匯入的記錄清單。如需詳細資訊，請參閱[使用 匯入 FHIR 資料 AWS HealthLake](importing-fhir-data.md)。
若要分析匯入任務失敗的原因，請使用 `DescribeFHIRImportJob` API 來分析 JobProperties。建議使用下列項目：
+ 如果狀態為 `FAILED`且訊息存在，則失敗與任務參數有關，例如輸入資料大小或輸入檔案的數量超出 HealthLake 配額。
+ 如果匯入任務狀態為 `COMPLETED_WITH_ERRORS`，請檢查資訊清單檔案 `manifest.json`，以取得哪些檔案未成功匯入的資訊。
+ 如果匯入任務狀態為 `FAILED`且訊息不存在，請前往任務輸出位置以存取資訊清單檔案 `manifest.json`。
對於每個輸入檔案，都有失敗輸出檔案，其中包含任何無法匯入之資源的輸入檔案名稱。回應包含對應於輸入資料位置的行號 (lineId)、FHIR 回應物件 (UpdateResourceResponse) 和回應的狀態碼 (statusCode)。
範例輸出檔案可能類似下列內容：
```
{"lineId":3, UpdateResourceResponse:{"jsonBlob":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"processing","diagnostics":"1 validation error detected: Value 'Patient123' at 'resourceType' failed to satisfy constraint: Member must satisfy regular expression pattern: [A-Za-z]{1,256}"}]}, "statusCode":400}
{"lineId":5, UpdateResourceResponse:{"jsonBlob":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"processing","diagnostics":"This property must be an simple value, not a com.google.gson.JsonArray","location":["/EffectEvidenceSynthesis/name"]},{"severity":"error","code":"processing","diagnostics":"Unrecognised property '@telecom'","location":["/EffectEvidenceSynthesis"]},{"severity":"error","code":"processing","diagnostics":"Unrecognised property '@gender'","location":["/EffectEvidenceSynthesis"]},{"severity":"error","code":"processing","diagnostics":"Unrecognised property '@birthDate'","location":["/EffectEvidenceSynthesis"]},{"severity":"error","code":"processing","diagnostics":"Unrecognised property '@address'","location":["/EffectEvidenceSynthesis"]},{"severity":"error","code":"processing","diagnostics":"Unrecognised property '@maritalStatus'","location":["/EffectEvidenceSynthesis"]},{"severity":"error","code":"processing","diagnostics":"Unrecognised property '@multipleBirthBoolean'","location":["/EffectEvidenceSynthesis"]},{"severity":"error","code":"processing","diagnostics":"Unrecognised property '@communication'","location":["/EffectEvidenceSynthesis"]},{"severity":"warning","code":"processing","diagnostics":"Name should be usable as an identifier for the module by machine processing applications such as code generation [name.matches('[A-Z]([A-Za-z0-9_]){0,254}')]","location":["EffectEvidenceSynthesis"]},{"severity":"error","code":"processing","diagnostics":"Profile http://hl7.org/fhir/StructureDefinition/EffectEvidenceSynthesis, Element 'EffectEvidenceSynthesis.status': minimum required = 1, but only found 0","location":["EffectEvidenceSynthesis"]},{"severity":"error","code":"processing","diagnostics":"Profile http://hl7.org/fhir/StructureDefinition/EffectEvidenceSynthesis, Element 'EffectEvidenceSynthesis.population': minimum required = 1, but only found 0","location":["EffectEvidenceSynthesis"]},{"severity":"error","code":"processing","diagnostics":"Profile http://hl7.org/fhir/StructureDefinition/EffectEvidenceSynthesis, Element 'EffectEvidenceSynthesis.exposure': minimum required = 1, but only found 0","location":["EffectEvidenceSynthesis"]},{"severity":"error","code":"processing","diagnostics":"Profile http://hl7.org/fhir/StructureDefinition/EffectEvidenceSynthesis, Element 'EffectEvidenceSynthesis.exposureAlternative': minimum required = 1, but only found 0","location":["EffectEvidenceSynthesis"]},{"severity":"error","code":"processing","diagnostics":"Profile http://hl7.org/fhir/StructureDefinition/EffectEvidenceSynthesis, Element 'EffectEvidenceSynthesis.outcome': minimum required = 1, but only found 0","location":["EffectEvidenceSynthesis"]},{"severity":"information","code":"processing","diagnostics":"Unknown extension http://synthetichealth.github.io/synthea/disability-adjusted-life-years","location":["EffectEvidenceSynthesis.extension[3]"]},{"severity":"information","code":"processing","diagnostics":"Unknown extension http://synthetichealth.github.io/synthea/quality-adjusted-life-years","location":["EffectEvidenceSynthesis.extension[4]"]}]}, "statusCode":400}
{"lineId":7, UpdateResourceResponse:{"jsonBlob":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"processing","diagnostics":"2 validation errors detected: Value at 'resourceId' failed to satisfy constraint: Member must satisfy regular expression pattern: [A-Za-z0-9-.]{1,64}; Value at 'resourceId' failed to satisfy constraint: Member must have length greater than or equal to 1"}]}, "statusCode":400}
{"lineId":9, UpdateResourceResponse:{"jsonBlob":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"processing","diagnostics":"Missing required id field in resource json"}]}, "statusCode":400}
{"lineId":15, UpdateResourceResponse:{"jsonBlob":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"processing","diagnostics":"Invalid JSON found in input file"}]}, "statusCode":400}
```
上述範例顯示輸入檔案中對應輸入行的第 3、4、7、9、15 行失敗。對於每行，說明如下：
+ 在第 3 行，回應說明輸入檔案第 3 行`resourceType`所提供的 是無效的。
+ 在第 5 行，回應說明輸入檔案的第 5 行中存在 FHIR 驗證錯誤。
+ 在第 7 行，回應說明`resourceId`提供 做為輸入時發生驗證問題。
+ 在第 9 行，回應說明輸入檔案必須包含有效的資源 ID。
+ 在第 15 行，輸入檔案的回應是檔案不是有效的 JSON 格式。
## FHIR APIs
**問題：***如何實作 FHIR RESTful APIs的授權？*
決定[資料存放區授權策略](getting-started-concepts.md#concept-data-store-authorization-strategy)要使用的 。
若要使用 建立 SigV4 授權 適用於 Python (Boto3) 的 AWS SDK，請建立類似下列範例的指令碼。
```
import boto3
import requests
import json
from requests_auth_aws_sigv4 import AWSSigV4
# Set the input arguments
data_store_endpoint = 'https://healthlake.us-east-1.amazonaws.com/datastore//r4//'
resource_path = "Patient"
requestBody = {"resourceType": "Patient", "active": True, "name": [{"use": "official","family": "Dow","given": ["Jen"]},{"use": "usual","given": ["Jen"]}],"gender": "female","birthDate": "1966-09-01"}
region = 'us-east-1'
#Frame the resource endpoint
resource_endpoint = data_store_endpoint+resource_path
session = boto3.session.Session(region_name=region)
client = session.client("healthlake")
# Frame authorization
auth = AWSSigV4("healthlake", session=session)
# Call data store FHIR endpoint using SigV4 auth
r = requests.post(resource_endpoint, json=requestBody, auth=auth, )
print(r.json())
```
**問題：***為什麼針對使用客戶受管 KMS 金鑰加密的資料存放區使用 FHIR RESTful APIs 時收到`AccessDenied`錯誤？*
使用者或角色需要客戶受管金鑰和 IAM 政策的許可，才能存取資料存放區。使用者必須擁有使用客戶受管金鑰所需的 IAM 許可。如果使用者撤銷或淘汰授予 HealthLake 使用客戶受管 KMS 金鑰的許可，HealthLake 將傳回`AccessDenied`錯誤。
HealthLake 必須具備存取客戶資料的許可、加密匯入資料存放區的新 FHIR 資源，以及在請求時解密 FHIR 資源。如需詳細資訊，請參閱[故障診斷 AWS KMS 許可](https://docs.aws.amazon.com/kms/latest/developerguide/policy-evaluation.html)。
**問題：***使用 10MB 文件的 FHIR `POST` API 操作向 HealthLake 傳回`413 Request Entity Too Large`錯誤。*
AWS HealthLake 具有 5MB 的同步建立和更新 API 限制，以避免增加延遲和逾時。您可以使用大量匯入 API，使用 `Binary` 資源類型擷取最多 164MB 的大型文件。
## NLP 整合
**問題：***如何開啟 HealthLake 整合的自然語言處理功能？*
截至 2022 年 11 月 14 日，HealthLake 資料存放區的預設行為已變更。
**目前的資料存放**區：所有目前的 HealthLake 資料存放區都將停止使用 base64 編碼`DocumentReference`資源上的自然語言處理 (NLP)。這表示將不會使用 NLP 分析新`DocumentReference`資源，也不會根據資源類型中的文字產生新`DocumentReference`資源。對於現有`DocumentReference`資源，透過 NLP 產生的資料和資源仍會保留，但不會在 2023 年 2 月 20 日之後更新。
**新資料存放**區：2023 年 2 月 20 日之後建立的 HealthLake 資料存放區*將不會*對 base64 編碼`DocumentReference`的資源執行自然語言處理 (NLP)。
若要開啟 HealthLake NLP 整合，請使用 建立支援案例[AWS Support Center Console](https://console.aws.amazon.com/support/home#/)。若要建立您的案例，請登入您的 AWS 帳戶，然後選擇**建立案例**。若要進一步了解如何建立案例和案例管理，請參閱*支援 《 使用者指南*》中的[建立支援案例和案例管理](https://docs.aws.amazon.com/awssupport/latest/user/case-management.html)。
**問題：***>如何尋找整合式 NLP 無法處理`DocumentReference`的資源？*
如果`DocumentReference`資源無效，HealthLake 會提供表示驗證錯誤的延伸，而不是在整合的醫療 NLP 輸出中提供。若要尋找在 NLP 處理期間導致驗證錯誤`DocumentReference`的資源，您可以使用 HealthLake 的 FHIR `search`函數搭配搜尋索引鍵 **cm-decoration-status** 和搜尋值 **VALIDATION\$1ERROR**。此搜尋會列出導致驗證錯誤的所有`DocumentReference`資源，以及描述錯誤性質的錯誤訊息。這些`DocumentReference`資源中具有驗證錯誤的延伸欄位結構將類似下列範例。
```
"extension": [
{
"extension": [
{
"url": "http://healthlake.amazonaws.com/aws-cm/status/",
"valueString": "VALIDATION_ERROR"
},
{
"url": "http://healthlake.amazonaws.com/aws-cm/message/",
"valueString": "Resource led to too many nested objects after NLP operation processed the document. 10937 nested objects exceeds the limit of 10000."
}
],
"url": "http://healthlake.amazonaws.com/aws-cm/"
}
]
```
**注意**
如果 NLP 裝飾建立超過 10，000 個巢狀物件，`VALIDATION_ERROR`也可能發生 。發生這種情況時，文件必須在處理之前分割成較小的文件。
## SQL 整合
**問題：***新增資料湖管理員`permissions error: lakeformation:PutDataLakeSettings`時，為什麼要取得 Lake Formation？*
如果您的 IAM 使用者或角色包含 `AWSLakeFormationDataAdmin` AWS 受管政策，則無法新增資料湖管理員。您會收到包含下列內容的錯誤：
```
User arn:aws:sts::111122223333:assumed-role/lakeformation-admin-user is not authorized to perform: lakeformation:PutDataLakeSettings on resource: arn:aws:lakeformation:us-east-2:111122223333:catalog:111122223333 with an explicit deny in an identity-based policy
```
`AdministratorAccess` 需要 AWS 受管政策，才能將 IAM 使用者或角色新增為 AWS Lake Formation 資料湖管理員。如果您的 IAM 使用者或角色也包含 `AWSLakeFormationDataAdmin` 動作將會失敗。`AWSLakeFormationDataAdmin` AWS 受管政策包含 AWS Lake Formation API 操作 的明確拒絕`PutDataLakeSetting`。即使是具有 AWS 使用 `AdministratorAccess`受管政策之完整存取權的管理員，也可以受到`AWSLakeFormationDataAdmin`政策的限制。
**問題：***如何遷移現有的 HealthLake 資料存放區以使用 Amazon Athena SQL 整合？*
在 2022 年 11 月 14 日之前建立的 HealthLake 資料存放區可正常運作，但無法使用 SQL 在 Athena 中查詢。若要使用 Athena 查詢預先存在的資料存放區，您必須先將其遷移至新的資料存放區。
**將 HealthLake 資料遷移至新的資料存放區**
1. 建立新的資料存放區。
1. 從預先存在的資料匯出至 Amazon S3 儲存貯體。
1. 從 Amazon S3 儲存貯體將資料匯入新的資料存放區。
**注意**
將資料匯出至 Amazon S3 儲存貯體會產生額外費用。額外費用取決於您匯出的資料大小。
**問題：***為 SQL 整合建立新的 HealthLake 資料存放區時，資料存放區狀態不會從 變更`Creating`。*
如果您嘗試建立新的 HealthLake 資料存放區，且資料存放區狀態並未從**建立**中變更，則需要更新 Athena 才能使用 AWS Glue Data Catalog。如需詳細資訊，請參閱《Amazon Athena [AWS 使用者指南》中的step-by-step升級至 Glue Data Catalog](https://docs.aws.amazon.com/athena/latest/ug/glue-upgrade.html)。 *Amazon Athena *
成功升級 後 AWS Glue Data Catalog，您可以建立 HealthLake 資料存放區。
若要移除舊的 HealthLake 資料存放區，請使用 建立支援案例[AWS Support Center Console](https://console.aws.amazon.com/support/home#/)。若要建立您的案例，請登入您的 AWS 帳戶，然後選擇**建立案例**。若要進一步了解，請參閱*支援 《 使用者指南*》中的[建立支援案例和案例管理](https://docs.aws.amazon.com/awssupport/latest/user/case-management.html)。
**問題：***Athena 主控台在將資料匯入新的 HealthLake 資料存放區後無法運作*
將資料匯入新的 HealthLake 資料存放區後，資料可能無法立即使用。這是為了讓資料有時間擷取到 Apache Iceberg 資料表。請稍後重試。
**問題：***如何將 Athena 中的搜尋結果連接到其他 AWS 服務？*
當您將 Athena 的搜尋結果與其他 AWS 服務共用時，當您使用 `json_extract[1]`做為 SQL 搜尋查詢的一部分時，可能會發生問題。若要修正此問題，您必須更新為 `CATVAR`。
嘗試**建立**儲存結果、**資料表** （靜態） 或**檢視** （動態） 時，您可能會遇到此問題。
# 搭配 AWS SDK 使用 HealthLake
AWS 軟體開發套件 (SDKs) 適用於許多熱門的程式設計語言。每個 SDK 都提供 API、程式碼範例和說明文件，讓開發人員能夠更輕鬆地以偏好的語言建置應用程式。
| SDK 文件 | 代碼範例 |
| --- | --- |
| [適用於 C\$1\$1 的 AWS SDK](https://docs.aws.amazon.com/sdk-for-cpp) | [適用於 C\$1\$1 的 AWS SDK 程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp) |
| [AWS CLI](https://docs.aws.amazon.com/cli) | [AWS CLI 程式碼範例](https://docs.aws.amazon.com/code-library/latest/ug/cli_2_code_examples.html) |
| [適用於 Go 的 AWS SDK](https://docs.aws.amazon.com/sdk-for-go) | [適用於 Go 的 AWS SDK 程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2) |
| [適用於 Java 的 AWS SDK](https://docs.aws.amazon.com/sdk-for-java) | [適用於 Java 的 AWS SDK 程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2) |
| [適用於 JavaScript 的 AWS SDK](https://docs.aws.amazon.com/sdk-for-javascript) | [適用於 JavaScript 的 AWS SDK 程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3) |
| [適用於 Kotlin 的 AWS SDK](https://docs.aws.amazon.com/sdk-for-kotlin) | [適用於 Kotlin 的 AWS SDK 程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin) |
| [適用於 .NET 的 AWS SDK](https://docs.aws.amazon.com/sdk-for-net) | [適用於 .NET 的 AWS SDK 程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv3) |
| [適用於 PHP 的 AWS SDK](https://docs.aws.amazon.com/sdk-for-php) | [適用於 PHP 的 AWS SDK 程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php) |
| [AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell) | [AWS Tools for PowerShell 程式碼範例](https://docs.aws.amazon.com/code-library/latest/ug/powershell_5_code_examples.html) |
| [適用於 Python (Boto3) 的 AWS SDK](https://docs.aws.amazon.com/pythonsdk) | [適用於 Python (Boto3) 的 AWS SDK 程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python) |
| [適用於 Ruby 的 AWS SDK](https://docs.aws.amazon.com/sdk-for-ruby) | [適用於 Ruby 的 AWS SDK 程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby) |
| [適用於 Rust 的 AWS SDK](https://docs.aws.amazon.com/sdk-for-rust) | [適用於 Rust 的 AWS SDK 程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1) |
| [適用於 SAP ABAP 的 AWS SDK](https://docs.aws.amazon.com/sdk-for-sapabap) | [適用於 SAP ABAP 的 AWS SDK 程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap) |
| [適用於 Swift 的 AWS SDK](https://docs.aws.amazon.com/sdk-for-swift) | [適用於 Swift 的 AWS SDK 程式碼範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift) |
**可用性範例**
找不到所需的內容嗎？ 請使用本頁面底部的**提供意見回饋**連結申請程式碼範例。