本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# HealthLake 支援的 FHIR OAuth 2.0 範圍上的 SMART
<a name="reference-smart-on-fhir-oauth-scopes"></a>

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`、`update`、 `delete`和 `search`許可。
`AWS_AUTH` – 預設的 AWS HealthLake 授權策略；與 FHIR 上的 SMART 無關。

## 獨立啟動範圍
<a name="smart-on-fhir-scopes-launch"></a>

HealthLake 支援獨立啟動模式範圍 `launch/patient`。

在獨立啟動模式中，用戶端應用程式會請求存取病患的臨床資料，因為用戶端應用程式不知道使用者和病患。因此，用戶端應用程式的授權請求會明確請求傳回病患範圍。身分驗證成功後，授權伺服器會發出存取字符，其中包含請求的啟動病患範圍。所需的患者內容會在授權伺服器的回應中與存取字符一起提供。


**支援的啟動模式範圍**  

| Scope (範圍) | 說明 | 
| --- | --- | 
| `launch/patient` | OAuth 2.0 授權請求中的參數，請求在授權回應中傳回該病患資料。 | 

## HealthLake 的 FHIR 資源範圍上的 SMART
<a name="smart-on-fhir-scopes-rest"></a>

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
<a name="reference-smart-on-fhir-v1"></a>

在 FHIR V1 上使用 SMART 時，用於建構 HealthLake 的 FHIR 資源範圍的一般語法如下。若要在下列範例中檢視整個 URL 路徑，請捲動至**複製**按鈕。

```
('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('read' | 'write' | '*')
```


**FHIR v1 支援的授權範圍上的 SMART**  

| 範圍語法 | 範例範圍 | 結果 | 
| --- | --- | --- | 
| `patient/(fhir-resource \| '*').('read' \| 'write' \| '*')` | patient/AllergyIntolerance.\* | 病患用戶端應用程式具有所有記錄的區分的執行個體層級讀取/寫入存取權。 | 
| `user/(fhir-resource \| '*').('read' \| 'write' \| '*')` | user/Observation.read | 使用者用戶端應用程式具有所有記錄觀察的執行個體層級讀取/寫入存取權。 | 
| system/('read' \| 'write' \| \*) | system/\*.\* | 系統用戶端應用程式具有所有 FHIR 資源資料的讀取/寫入存取權。 | 

### HealthLake 支援的 FHIR V2 範圍上的 SMART
<a name="reference-smart-on-fhir-v2"></a>

在 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 美國核心實作指南*中[支援的精細範圍](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/\*.\* | 系統用戶端應用程式具有所有 FHIR 資源資料的完整create/read/update/刪除/搜尋存取權。 | 

### HealthLake 支援的 FHIR V2.2 範圍上的 SMART
<a name="reference-smart-on-fhir-v2-2"></a>

V2.2 使用以搜尋參數為基礎的篩選來擴展 V2 範圍。授權伺服器現在可以發出限制特定資料特性存取的範圍，而不只是根據資源類型和 CRUDS 操作。

V2 的所有內容保持不變。V2.2 純粹是附加的：
+ 現有的 V2 範圍 （不含篩選條件） 會繼續像以前一樣運作。
+ V2 文法是以選用的`?param=value`查詢字串延伸。
+ 範圍層級 (`patient`/`user`/`system`)、資源類型或 CRUDS 字母沒有變更。

#### 先決條件
<a name="smart-on-fhir-v2-2-prerequisites"></a>

在 FHIR V2.2 上啟用 SMART 之前，請確定下列事項：
+ 您的資料存放區已建立，並將 `AuthorizationStrategy` 設為 `SMART_ON_FHIR`（同時支援 V1 和 V2)。使用 `SMART_ON_FHIR_V1`或 `AWS_AUTH` 的資料存放區不符合資格。
+ 您的資料存放區已包含在`capabilities`陣列`permission-v2`中。V2.2 是擴充 V2 時的附加項目，無法獨立使用。
+ 您的 IDP Lambda 已設定為驗證並傳遞 V2.2 範圍格式 （包含`?`查詢語法的範圍）。

#### 啟用 V2.2
<a name="smart-on-fhir-v2-2-enabling"></a>

啟用路徑取決於您要建立新的資料存放區或更新現有的資料存放區。

##### 新的資料存放區
<a name="smart-on-fhir-v2-2-new-data-stores"></a>

建立新的資料存放區時，請將 `permission-v2.2`新增至 `Metadata`欄位中的 `capabilities`陣列[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)：

```
"capabilities": [
  "launch-ehr",
  "sso-openid-connect",
  "client-public",
  "permission-v2",
  "permission-v2.2"
]
```

##### 現有資料存放區
<a name="smart-on-fhir-v2-2-existing-data-stores"></a>

若要在現有資料存放區上啟用 FHIR V2.2 上的 SMART，請將 `permission-v2.2`新增至 `Metadata`欄位中的`capabilities`陣列，[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)並使用 提交變更`UpdateFHIRDatastore`。如需詳細資訊，請參閱[更新 HealthLake 資料存放區](managing-data-stores-update.md)。

使用要求：
+ `permission-v2` 必須保留在陣列中。V2.2 擴展 V2，無法單獨使用。
+ `AuthorizationStrategy` 必須是 `SMART_ON_FHIR`（不是 `SMART_ON_FHIR_V1`或 `AWS_AUTH`)。
+ 更新身分提供者組態會將其完全取代，因此請包含所有現有的欄位和功能以及 `permission-v2.2`。

變更會立即生效，沒有停機時間。若要驗證，請擷取 [探索文件](reference-smart-on-fhir-discovery-document.md)（需要 SigV4)：

```
GET {healthlake-endpoint}/r4/.well-known/smart-configuration
```

如果回應中的`capabilities`陣列包含 `permission-v2.2`，則 FHIR V2.2 上的 SMART 會處於作用中狀態。

#### 延伸範圍語法
<a name="smart-on-fhir-v2-2-extended-scope-syntax"></a>

V2 文法是以選用的查詢字串延伸：

```
V2:   (patient|user|system) / resource . cruds
V2.2: (patient|user|system) / resource . cruds [? param=value [& param=value ...]]
```


**V2.2 範圍查詢字串元件**  

| 元件 | 說明 | 
| --- | --- | 
| `?param=value` | Search-parameter 篩選條件。只有符合此條件的資源才能存取。 | 
| `&param=value` | 其他篩選條件。多個篩選條件是 ANDed – 所有篩選條件都必須相符。 | 

規則：
+ 篩選條件僅適用於範圍中指定的資源類型。不支援萬用字元 (`*`) 搭配篩選條件。
+ 參數必須根據您資料存放區的搜尋組態對資源類型有效 （透過 檢查`GET /r4/metadata`)。
+ 完整範圍字串 （例如 `patient/Observation.rs?category=laboratory`) 是出現在 OAuth 2.0 範圍參數和存取字符`scp`宣告中的常值。
+ 授權請求中每個 [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) 的 URL `|` 編碼特殊字元 （例如 → `%7C`)。
+ 對於日期、數字和數量參數，V2.2 支援字首[比較器](https://docs.aws.amazon.com/healthlake/latest/devguide/reference-fhir-search-parameters.html#search-comparators) （例如 `?date=eq2023-01-01`)。V2.2 [也支援搜尋參數修改程式](https://docs.aws.amazon.com/healthlake/latest/devguide/reference-fhir-search-parameters.html#search-parameter-modifiers)。

#### 範圍範例
<a name="smart-on-fhir-v2-2-scope-examples"></a>


**V2.2 範圍範例**  

| Scope (範圍) | 授予的存取 | 
| --- | --- | 
| `patient/DiagnosticReport.rs?category=LAB` | 只有 `category`為 `DiagnosticReport`的資源`LAB`。 | 
| `patient/Observation.rs?_security=http://terminology.hl7.org/CodeSystem/v3-Confidentiality\|R` | 只有具有安全標籤 `Observation`的資源`Restricted`。 | 
| `patient/Observation.rs?date=ge2023-01-01` | 只有日期為 2023 年 1 月 1 日或之後`Observation`的資源。 | 
| `patient/Observation.rs?category=laboratory&status=final` | 只有實驗室 AND 最終版`Observation`的資源。 | 
| `user/Condition.rs?clinical-status=active` | 只有作用中`Condition`的資源。 | 

#### 強制執行行為
<a name="smart-on-fhir-v2-2-enforcement"></a>

當字符包含 V2.2 範圍時，HealthLake 會套用每個操作的篩選條件：


**每個操作的 V2.2 強制執行**  

| 作業 | Behavior (行為) | 
| --- | --- | 
| 讀取 (`r`) | 只有在資源符合所有範圍篩選條件時，才會成功。否則會傳回 403。 | 
| 搜尋 (`s`) | 範圍篩選條件與查詢相交。只會傳回相符的資源。 | 
| 建立/更新 (`c`/`u`) | 資源必須符合範圍篩選條件才能寫入。否則會傳回 403。 | 
| 刪除 (`d`) | 目標資源必須符合範圍篩選條件。否則會傳回 403。 | 

##### 範圍優先順序
<a name="smart-on-fhir-v2-2-scope-precedence"></a>
+ 相同資源類型的多個 V2.2 範圍會聯集 （跨範圍的 OR)。
+ 沒有篩選條件的更廣泛 V2 範圍 （例如 `patient/Observation.rs`) 會授予完整存取權，無論相同權杖中任何更窄的 V2.2 範圍為何。
+ 未`permission-v2.2`啟用的資料存放區上的 V2.2 範圍會被無提示地忽略。

#### 限制
<a name="smart-on-fhir-v2-2-limitations"></a>

V2.2 範圍篩選條件不支援下列項目：
+ 複合搜尋參數 （例如 `code-value-quantity`)。
+ 鏈結搜尋參數 （例如 `subject:Patient.name=Smith`)。
+ `_include` / `_revinclude`搜尋參數。
+ `$export` / `$davinci-data-export`（大量資料） – 不適用 V2.2 篩選條件；大量匯出使用 V2 範圍。
+ 萬用字元資源類型與篩選條件結合 （例如， `patient/*.rs?category=LAB` 無效）。使用搜尋參數篩選條件時，您必須指定明確的資源類型 （例如 `patient/Observation.rs?category=LAB`)。


**疑難排解**  

| 徵狀 | 原因 | 修正 | 
| --- | --- | --- | 
| 無法辨識字符範圍 | 資料存放區上未啟用 V2.2 | 透過支援票證檢查`/.well-known/smart-configuration`並請求啟用。 | 
| 資源上存在的 403 | 資源不符合範圍篩選條件 | 根據範圍參數驗證資源值。 | 
| 空的搜尋結果 | 範圍篩選條件比查詢更窄 | 結果是查詢和範圍篩選條件的交集。 | 
| `InvalidScope` 錯誤 | 範圍內的無效搜尋參數 | 透過 `/metadata` CapabilityStatement 確認參數。 | 

#### 端對端範例
<a name="smart-on-fhir-v2-2-end-to-end-example"></a>

案例：患者應用程式應僅顯示 2023 年以後的最終實驗室結果。

1. 具有範圍的授權伺服器問題字符：

   ```
   patient/Observation.rs?category=laboratory&status=final&date=ge2023-01-01
   ```

1. 用戶端呼叫 HealthLake：

   ```
   GET {endpoint}/r4/Observation?patient=Patient/123
   ```

1. HealthLake 會強制執行範圍篩選條件。回應僅包含 `category=laboratory` AND `status=final` 和 `date ≥ 2023-01-01` – 即使用戶端請求所有觀察`Observation`。