Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# SMART pada cakupan FHIR OAuth 2.0 didukung oleh HealthLake
<a name="reference-smart-on-fhir-oauth-scopes"></a>

HealthLake menggunakan OAuth 2.0 sebagai protokol otorisasi. Menggunakan protokol ini di server otorisasi Anda memungkinkan Anda untuk menentukan izin penyimpanan HealthLake data (membuat, membaca, memperbarui, menghapus, dan mencari) untuk sumber daya FHIR yang dapat diakses oleh aplikasi klien.

SMART on FHIR framework mendefinisikan satu set cakupan yang dapat diminta dari server otorisasi. Misalnya, aplikasi klien yang hanya dirancang untuk memungkinkan pasien melihat hasil lab mereka atau melihat detail kontak mereka hanya boleh *diizinkan* untuk meminta `read` cakupan.

**catatan**  
HealthLake menyediakan dukungan untuk SMART pada FHIR V1 dan V2 seperti yang dijelaskan di bawah ini. SMART di 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)diatur ke salah satu dari tiga nilai berikut saat penyimpanan data Anda dibuat:  
`SMART_ON_FHIR_V1`— Support hanya untuk SMART di FHIR V1, yang mencakup izin `read` (read/search) dan `write` (create/update/delete).
`SMART_ON_FHIR`— Support untuk SMART pada FHIR V1 dan V2, yang mencakup`create`,,`read`, `update``delete`, dan `search` izin.
`AWS_AUTH`— Strategi AWS HealthLake otorisasi default; tidak berafiliasi dengan SMART di FHIR.

## Lingkup peluncuran mandiri
<a name="smart-on-fhir-scopes-launch"></a>

HealthLake mendukung lingkup `launch/patient` mode peluncuran mandiri.

Dalam mode peluncuran mandiri, aplikasi klien meminta akses ke data klinis pasien karena pengguna dan pasien tidak diketahui oleh aplikasi klien. Dengan demikian, permintaan otorisasi aplikasi klien secara eksplisit meminta ruang lingkup pasien dikembalikan. Setelah otentikasi berhasil, server otorisasi mengeluarkan token akses yang berisi ruang lingkup pasien peluncuran yang diminta. Konteks pasien yang diperlukan disediakan bersama token akses dalam respons server otorisasi.


**Cakupan mode peluncuran yang didukung**  

| Lingkup | Deskripsi | 
| --- | --- | 
| `launch/patient` | Parameter dalam permintaan otorisasi OAuth 2.0 yang meminta agar data pasien dikembalikan dalam respons otorisasi. | 

## SMART pada cakupan sumber daya FHIR untuk HealthLake
<a name="smart-on-fhir-scopes-rest"></a>

HealthLake mendefinisikan tiga tingkat SMART pada cakupan sumber daya FHIR.
+ `patient`cakupan memberikan akses ke data spesifik tentang satu Pasien.
+ `user`cakupan memberikan akses ke data tertentu yang dapat diakses pengguna.
+ `system`cakupan memberikan akses ke semua sumber daya FHIR yang ditemukan di penyimpanan HealthLake data.

Bagian berikut mencantumkan sintaks untuk membangun cakupan sumber daya FHIR menggunakan SMART pada FHIR V1 atau SMART di FHIR V2.

**catatan**  
Strategi otorisasi SMART on FHIR diatur saat penyimpanan data Anda dibuat. Untuk informasi selengkapnya, lihat [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) di dalam *Referensi API AWS HealthLake *. 

### SMART pada cakupan FHIR V1 didukung oleh HealthLake
<a name="reference-smart-on-fhir-v1"></a>

Saat menggunakan SMART pada FHIR V1, sintaks umum untuk membangun cakupan sumber daya FHIR untuk berikut. HealthLake Untuk melihat seluruh jalur URL dalam contoh berikut, gulir ke atas tombol **Salin**.

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


**SMART pada cakupan otorisasi yang didukung FHIR v1**  

| Sintaks lingkup | Contoh ruang lingkup | Hasil | 
| --- | --- | --- | 
| `patient/(fhir-resource \| '*').('read' \| 'write' \| '*')` | patient/AllergyIntolerance.\* | Aplikasi klien pasien memiliki read/write akses tingkat instance ke semua alergi yang tercatat. | 
| `user/(fhir-resource \| '*').('read' \| 'write' \| '*')` | user/Observation.read | Aplikasi klien pengguna memiliki read/write akses tingkat instance ke semua pengamatan yang direkam.  | 
| system/('read' \| 'write' \| \*) | system/\*.\* | Aplikasi klien sistem memiliki read/write akses ke semua data sumber daya FHIR. | 

### SMART pada cakupan FHIR V2 didukung oleh HealthLake
<a name="reference-smart-on-fhir-v2"></a>

Saat menggunakan SMART di FHIR V2, sintaks umum untuk membangun cakupan sumber daya FHIR untuk berikut. HealthLake Untuk melihat seluruh jalur URL dalam contoh berikut, gulir ke atas tombol **Salin**.

```
('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('c' | 'r' | 'u' | 'd' | 's')
```

**catatan**  
Untuk menggunakan SMART pada FHIR V2, Anda harus meneruskan nilai [https://hl7.org/fhir/smart-app-launch/STU2/conformance.html#permissions](https://hl7.org/fhir/smart-app-launch/STU2/conformance.html#permissions)ke dalam `capabilities` string metadata, yang merupakan anggota dari tipe data. [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)  
HealthLake mendukung cakupan granular. Untuk informasi lebih lanjut, lihat [cakupan granular yang didukung](https://hl7.org/fhir/us/core/scopes.html#the-following-granular-scopes-shall-be-supported) di Panduan Implementasi *Inti AS FHIR*.


**SMART pada cakupan otorisasi yang didukung FHIR V2**  

| Sintaks lingkup | Contoh lingkup V1 | Hasil | 
| --- | --- | --- | 
| `patient/Observation.rs` | user/Observation.read | Izin untuk membaca dan mencari Observation sumber daya untuk pasien saat ini. | 
| `system/*.cruds` | system/\*.\* | Aplikasi klien sistem memiliki akses create/read update/delete penuh//pencarian ke semua data sumber daya FHIR.  | 

### SMART pada V2.2 cakupan FHIR didukung oleh HealthLake
<a name="reference-smart-on-fhir-v2-2"></a>

V2.2 memperluas cakupan V2 dengan pemfilteran berbasis parameter pencarian. Server otorisasi sekarang dapat mengeluarkan cakupan yang membatasi akses dengan karakteristik data tertentu dan tidak hanya berdasarkan jenis sumber daya dan operasi CRUDS.

Semuanya dari V2 tetap tidak berubah. V2.2 murni aditif:
+ Cakupan V2 yang ada (tanpa filter) terus berfungsi seperti sebelumnya.
+ Tata bahasa V2 diperluas dengan string `?param=value` kueri opsional.
+ Tidak ada perubahan pada tingkat lingkup (`patient`/`user`/`system`), jenis sumber daya, atau huruf CRUDS.

#### Prasyarat
<a name="smart-on-fhir-v2-2-prerequisites"></a>

Sebelum mengaktifkan SMART di FHIR V2.2, pastikan hal berikut:
+ Penyimpanan data Anda dibuat dengan `AuthorizationStrategy` set to `SMART_ON_FHIR` (mendukung V1 dan V2). Penyimpanan data menggunakan `SMART_ON_FHIR_V1` atau `AWS_AUTH` tidak memenuhi syarat.
+ Penyimpanan data Anda sudah termasuk `permission-v2` dalam `capabilities` array. V2.2 aditif karena memperpanjang V2 dan tidak dapat digunakan secara mandiri.
+ Lambda IDP Anda dikonfigurasi untuk memvalidasi dan melewati format cakupan (cakupan V2.2 yang berisi sintaks kueri`?`).

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

Jalur pemberdayaan tergantung pada apakah Anda membuat penyimpanan data baru atau memperbarui yang sudah ada.

##### Menyimpan data baru
<a name="smart-on-fhir-v2-2-new-data-stores"></a>

Saat membuat penyimpanan data baru, tambahkan `permission-v2.2` ke `capabilities` array di `Metadata` bidang [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"
]
```

##### Penyimpanan data yang ada
<a name="smart-on-fhir-v2-2-existing-data-stores"></a>

Untuk mengaktifkan SMART di FHIR V2.2 pada penyimpanan data yang ada, tambahkan `permission-v2.2` ke `capabilities` array di `Metadata` bidang Anda [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)dan kirimkan perubahan dengan`UpdateFHIRDatastore`. Untuk informasi selengkapnya, lihat [Memperbarui penyimpanan HealthLake data](managing-data-stores-update.md).

Persyaratan:
+ `permission-v2`harus tetap dalam array. V2.2 memperluas V2 dan tidak dapat digunakan sendiri.
+ `AuthorizationStrategy`harus `SMART_ON_FHIR` (tidak `SMART_ON_FHIR_V1` atau`AWS_AUTH`).
+ Memperbarui konfigurasi penyedia identitas menggantikannya secara penuh, jadi sertakan semua bidang dan kemampuan yang ada bersama dengan`permission-v2.2`.

Perubahan segera berlaku, tanpa downtime. Untuk memverifikasi, ambil [Dokumen Penemuan](reference-smart-on-fhir-discovery-document.md) (membutuhkan SigV4):

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

Jika `capabilities` array dalam respons termasuk`permission-v2.2`, SMART di FHIR V2.2 aktif.

#### Sintaks lingkup yang diperluas
<a name="smart-on-fhir-v2-2-extended-scope-syntax"></a>

Tata bahasa V2 diperluas dengan string kueri opsional:

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


**V2.2 komponen string kueri lingkup**  

| Komponen | Deskripsi | 
| --- | --- | 
| `?param=value` | Search-parameter menyaring. Hanya sumber daya yang cocok dengan kriteria ini yang dapat diakses. | 
| `&param=value` | Filter tambahan. Beberapa filter di-edD — semua harus cocok. | 

Aturan:
+ Filter hanya berlaku untuk jenis sumber daya yang ditentukan dalam ruang lingkup. Wildcard (`*`) dengan filter tidak didukung.
+ Parameter harus valid untuk jenis sumber daya per konfigurasi pencarian penyimpanan data Anda (periksa via`GET /r4/metadata`).
+ String lingkup penuh (misalnya,`patient/Observation.rs?category=laboratory`) adalah nilai literal yang muncul dalam parameter lingkup OAuth 2.0 dan klaim token `scp` akses.
+ URL-encode karakter khusus per [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) dalam permintaan otorisasi (misalnya, `|` →). `%7C`
+ Untuk parameter tanggal, angka, dan kuantitas, V2.2 mendukung [pembanding](https://docs.aws.amazon.com/healthlake/latest/devguide/reference-fhir-search-parameters.html#search-comparators) awalan (misalnya,`?date=eq2023-01-01`). V2.2 juga mendukung [pengubah parameter pencarian](https://docs.aws.amazon.com/healthlake/latest/devguide/reference-fhir-search-parameters.html#search-parameter-modifiers).

#### Contoh lingkup
<a name="smart-on-fhir-v2-2-scope-examples"></a>


**V2.2 contoh lingkup**  

| Lingkup | Akses diberikan | 
| --- | --- | 
| `patient/DiagnosticReport.rs?category=LAB` | Hanya `DiagnosticReport` sumber daya di `category` mana`LAB`. | 
| `patient/Observation.rs?_security=http://terminology.hl7.org/CodeSystem/v3-Confidentiality\|R` | Hanya `Observation` sumber daya dengan label keamanan`Restricted`. | 
| `patient/Observation.rs?date=ge2023-01-01` | Hanya `Observation` sumber daya tertanggal pada atau setelah 1 Januari 2023. | 
| `patient/Observation.rs?category=laboratory&status=final` | Hanya `Observation` sumber daya yang lab DAN final. | 
| `user/Condition.rs?clinical-status=active` | Hanya `Condition` sumber daya aktif. | 

#### Perilaku penegakan
<a name="smart-on-fhir-v2-2-enforcement"></a>

Saat token menyertakan V2.2 cakupan, HealthLake terapkan filter per operasi:


**V2.2 penegakan per operasi**  

| Operasi | Perilaku | 
| --- | --- | 
| Baca (`r`) | Berhasil hanya jika sumber daya cocok dengan semua filter lingkup. Jika tidak mengembalikan 403. | 
| Cari (`s`) | Filter lingkup berpotongan dengan kueri. Hanya sumber daya yang cocok yang dikembalikan. | 
| Create/Update (`c`/`u`) | Sumber daya harus memenuhi filter lingkup untuk ditulis. Jika tidak mengembalikan 403. | 
| Hapus (`d`) | Sumber daya target harus cocok dengan filter lingkup. Jika tidak mengembalikan 403. | 

##### Ruang lingkup diutamakan
<a name="smart-on-fhir-v2-2-scope-precedence"></a>
+ Beberapa V2.2 cakupan untuk jenis sumber daya yang sama disatukan (ATAU lintas cakupan).
+ Cakupan V2 yang lebih luas tanpa filter (misalnya,`patient/Observation.rs`) memberikan akses penuh terlepas dari V2.2 cakupan yang lebih sempit dalam token yang sama.
+ V2.2 cakupan pada penyimpanan data tanpa `permission-v2.2` diaktifkan diabaikan secara diam-diam.

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

Berikut ini tidak didukung dalam filter V2.2 lingkup:
+ Parameter pencarian komposit (misalnya,`code-value-quantity`).
+ Parameter pencarian berantai (misalnya,`subject:Patient.name=Smith`).
+ `_include`/parameter `_revinclude` pencarian.
+ `$export`/`$davinci-data-export`(Data Massal) — V2.2 filter tidak berlaku; ekspor massal menggunakan cakupan V2.
+ Jenis sumber daya wildcard dikombinasikan dengan filter (misalnya, `patient/*.rs?category=LAB` tidak valid). Anda harus menentukan jenis sumber daya eksplisit saat menggunakan filter parameter pencarian (misalnya,). `patient/Observation.rs?category=LAB`


**Pemecahan masalah**  

| Gejala | Penyebab | Perbaiki | 
| --- | --- | --- | 
| Cakupan token tidak dikenali | V2.2 tidak diaktifkan di penyimpanan data | Periksa `/.well-known/smart-configuration` dan minta pemberdayaan melalui tiket dukungan. | 
| 403 pada sumber daya yang ada | Sumber daya tidak cocok dengan filter lingkup | Verifikasi nilai sumber daya terhadap parameter lingkup. | 
| Hasil pencarian kosong | Filter lingkup lebih sempit dari kueri | Hasil adalah persimpangan filter kueri dan ruang lingkup. | 
| `InvalidScope` kesalahan | Parameter pencarian tidak valid dalam lingkup | Konfirmasikan parameter melalui `/metadata` CapabilityStatement. | 

#### End-to-end contoh
<a name="smart-on-fhir-v2-2-end-to-end-example"></a>

Skenario: Aplikasi pasien seharusnya hanya menampilkan hasil lab yang diselesaikan mulai tahun 2023 dan seterusnya.

1. Server otorisasi mengeluarkan token dengan cakupan:

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

1. Panggilan klien HealthLake:

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

1. HealthLake memberlakukan filter lingkup. Respons hanya berisi `Observation` sumber daya di mana `category=laboratory` `status=final` DAN DAN `date ≥ 2023-01-01` - meskipun klien meminta semua Pengamatan.