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

# Document-level kontrol akses
<a name="kb-managed-ds-s3-acl"></a>

**Kesadaran ACL bukanlah otorisasi**  
Basis Pengetahuan Terkelola Batuan Dasar menyediakan ACL-aware penyaringan, bukan batas keamanan. Basis Pengetahuan Terkelola Bedrock tidak mengautentikasi pengguna akhir — aplikasi Anda bertanggung jawab untuk mengautentikasi pengguna dan meneruskan konteks identitas terverifikasi. Karena Basis Pengetahuan Terkelola Bedrock tidak dapat memverifikasi keaslian konteks pengguna yang Anda berikan, fitur ini memfilter hasil berdasarkan identitas yang Anda berikan tetapi bukan merupakan otorisasi yang benar. Anda tidak boleh mengandalkan fitur ini sebagai mekanisme kontrol akses tunggal tanpa otentikasi hulu.

Sumber data Amazon S3 secara opsional mendukung kontrol akses tingkat dokumen. Tidak seperti konektor lainnya, Amazon S3 tidak memiliki sistem izin asli untuk dirayapi, jadi Anda menentukan ACL melalui file konfigurasi yang Anda kelola. Untuk ikhtisar kesadaran ACL di semua konektor, lihat[Akses Kontrol Daftar pemberdayaan kesadaran](kb-managed-acl.md).

## Cara kerjanya
<a name="kb-managed-ds-s3-acl-how"></a>

Untuk sumber data ACL-enabled Amazon S3, Pangkalan Pengetahuan Terkelola Batuan Dasar menerapkan daftar kontrol akses yang disediakan pelanggan selama pemfilteran pra-pengambilan, hanya menampilkan dokumen yang diizinkan untuk diakses oleh pengguna kueri. Real-time Verifikasi ACL tidak didukung untuk Amazon S3 karena metadata ACL yang disediakan pelanggan adalah sumber kebenaran.

## Aktifkan kesadaran ACL
<a name="kb-managed-ds-s3-acl-enable"></a>

Untuk mengaktifkan kesadaran ACL untuk sumber data Amazon S3, `aclEnabled` setel `true` ke dalam `connectorParameters` dan tentukan izin akses menggunakan salah satu dari dua metode:
+ **File konfigurasi ACL global - File** JSON terpusat tunggal yang mendefinisikan izin akses pada tingkat folder (awalan). Ideal untuk organisasi dengan struktur izin yang stabil. Perubahan pada file global memerlukan pengindeksan ulang awalan yang terpengaruh.
+ Document-level file **metadata — Setiap dokumen memiliki file** metadata sendiri yang berisi informasi kontrol akses. Ini memungkinkan pembaruan indeks yang lebih cepat ketika izin berubah karena hanya dokumen yang terpengaruh yang memerlukan pengindeksan ulang.

**penting**  
Untuk sumber data ACL-enabled Amazon S3, dokumen tanpa entri ACL terkait tidak dicerna. Pastikan setiap dokumen memiliki ACL yang ditentukan baik melalui file ACL global atau dalam file metadatanya.

```
"connectorParameters": {
    "type": "S3",
    "version": "1",
    "aclEnabled": true,
    "connectionConfiguration": {
        "bucketName": "{{your-bucket-name}}",
        "bucketOwnerAccountId": "{{123456789012}}"
    },
    "aclConfiguration": {
        "globalAccessControlListS3Uri": "s3://{{your-bucket-name}}/{{acl/global-acl.json}}"
    }
}
```

## Struktur file ACL global
<a name="kb-managed-ds-s3-acl-global"></a>

File ACL global adalah array JSON di mana setiap entri memetakan awalan kunci ke satu set entri kontrol akses. Masing-masing `keyPrefix` adalah URI Amazon S3 absolut dari sebuah folder (berlaku untuk semua dokumen di bawahnya) atau dokumen individual.

```
[
    {
        "keyPrefix": "s3://{{your-bucket-name}}/{{finance/}}",
        "aclEntries": [
            {
                "Name": "{{user1@example.com}}",
                "Type": "USER",
                "Access": "ALLOW"
            }
        ]
    }
]
```

Setiap `aclEntries` elemen mengandung:
+ `Name`— Alamat email pengguna.
+ `Type`- Harus`USER`.
+ `Access`- Entah `ALLOW` atau`DENY`. Tolak penggantian memungkinkan.

## Per-document file metadata
<a name="kb-managed-ds-s3-acl-perdoc"></a>

Sebagai alternatif untuk file ACL global, Anda dapat menentukan ACL per dokumen menggunakan file metadata. Untuk setiap dokumen, buat file bernama `{{filename}}.metadata.json` di jalur Amazon S3 yang sama. Sertakan `accessControlList` array dengan format entri yang sama dengan file global.

```
{
    "metadataAttributes": {},
    "accessControlList": [
        {
            "Name": "{{user1@example.com}}",
            "Type": "USER",
            "Access": "ALLOW"
        },
        {
            "Name": "{{user2@example.com}}",
            "Type": "USER",
            "Access": "DENY"
        }
    ]
}
```

Per-document metadata lebih diutamakan daripada file ACL global. Jika dokumen memiliki entri awalan global yang cocok dan file metadata per dokumen, metadata per dokumen digunakan.

**catatan**  
File konfigurasi ACL harus disimpan dalam bucket Amazon S3 yang sama dengan konten sumber data Anda.

## Verifikasi konfigurasi Anda
<a name="kb-managed-ds-s3-acl-verify"></a>

Karena Amazon S3 ACL disediakan pelanggan, validasi sebelum Anda melakukan kueri:

1. Konfirmasi `aclEnabled` ada `true` di sumber data`connectorParameters`.

1. Konfirmasikan setiap dokumen memiliki ACL — baik entri dalam file ACL global atau file per `.metadata.json` dokumen. Dokumen tanpa ACL tidak dicerna.

1. Validasi ACL JSON: setiap entri memiliki `Name` (email pengguna), `Type` (`USER`), dan `Access` (`ALLOW`atau`DENY`), dan file ACL berada dalam bucket yang sama dengan konten Anda.

1. Konfirmasikan email pengguna pengujian sama persis dengan `ALLOW` entri `Name` dalam dokumen yang Anda harapkan untuk diambil.

## Pemecahan masalah
<a name="kb-managed-ds-s3-acl-troubleshooting"></a>

**catatan**  
Kesalahan konfigurasi ACL tidak menghasilkan kesalahan eksplisit selama pengambilan. Pengambilan gagal ditutup: dokumen yang terpengaruh dihilangkan secara diam-diam, sehingga kueri mengembalikan hasil yang lebih sedikit atau nol daripada kesalahan. Gunakan pemeriksaan verifikasi di atas untuk mendiagnosis masalah ini.


**ACL-enabled Gejala, penyebab, dan perbaikan Amazon S3**  

| Gejala | Kemungkinan penyebabnya | Perbaiki | 
| --- | --- | --- | 
| Retrieve mengembalikan 0 hasil untuk pengguna yang seharusnya memiliki akses. | Email pengguna tidak cocok dengan entri ACL apa pun (ketidakcocokan email). | Pastikan ACL sama persis Name dengan email pengguna. | 
| Dokumen tidak pernah dikembalikan kepada siapa pun. | Dokumen tidak memiliki entri ACL, jadi tidak tertelan. | Tambahkan ACL untuk dokumen melalui file ACL global atau file per dokumen, lalu .metadata.json sinkronkan ulang. | 
| ACL per dokumen tidak berlaku. | .metadata.jsonFile salah nama atau di jalur yang salah. | Beri nama {{filename}}.metadata.json di jalur S3 yang sama; metadata per dokumen mengesampingkan file global. | 
| Perubahan ACL tidak tercermin. | Perubahan file ACL global memerlukan pengindeksan ulang awalan yang terpengaruh. | Sinkronkan ulang awalan yang terpengaruh. |