Menyiapkan kontrol akses sumber data

Catatan: Fitur ini adalah penawaran Pratinjau, yang tunduk pada "Persyaratan Penawaran Pra-GA" dari Persyaratan Khusus Layanan GCP. Produk dan fitur pra-GA mungkin memiliki dukungan terbatas, dan perubahan pada produk serta fitur pra-GA mungkin tidak kompatibel dengan versi pra-GA lainnya. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran. Selanjutnya, dengan menggunakan fitur ini, Anda menyetujui persyaratan dan ketentuan Pratinjau AI Generatif ("Persyaratan Pratinjau"). Untuk fitur ini, Anda dapat memproses data pribadi sebagaimana diuraikan dalam Adendum Pemrosesan Data Cloud, dengan tunduk pada batasan dan kewajiban yang berlaku dalam Perjanjian (sebagaimana didefinisikan dalam Persyaratan Pratinjau).

Halaman ini menjelaskan cara menerapkan kontrol akses sumber data untuk aplikasi penelusuran di Vertex AI Search.

Kontrol akses untuk sumber data Anda di Vertex AI Search membatasi data yang dapat dilihat pengguna dalam hasil aplikasi penelusuran Anda. Google menggunakan penyedia identitas Anda untuk mengidentifikasi pengguna akhir yang melakukan penelusuran dan menentukan apakah mereka memiliki akses ke dokumen yang ditampilkan sebagai hasil.

Misalnya, karyawan di perusahaan Anda menelusuri dokumen Confluence menggunakan aplikasi penelusuran Anda. Namun, Anda harus memastikan mereka tidak dapat melihat konten melalui aplikasi yang tidak boleh mereka akses. Jika telah menyiapkan kumpulan tenaga kerja di Google Cloud untuk penyedia identitas organisasi Anda, maka Anda juga dapat menentukan kumpulan tenaga kerja tersebut di Vertex AI Search. Sekarang, jika karyawan menggunakan aplikasi Anda, mereka hanya akan mendapatkan hasil penelusuran untuk dokumen yang sudah dapat diakses oleh akun mereka di Confluence.

Tentang kontrol akses sumber data

Mengaktifkan kontrol akses adalah prosedur satu kali.

Kontrol akses tersedia untuk Cloud Storage, BigQuery, Google Drive, dan semua sumber data pihak ketiga.

Untuk mengaktifkan kontrol akses sumber data untuk Vertex AI Search, Anda harus mengonfigurasi penyedia identitas organisasi Anda di Google Cloud. Framework autentikasi berikut didukung:

• Identitas Google:

  • Kasus 1: Jika Anda menggunakan Google Identity, semua identitas pengguna dan grup pengguna akan ada dan dikelola melalui Google Cloud. Untuk mengetahui informasi selengkapnya tentang Google Identity, lihat dokumentasi Google Identity.

  • Kasus 2: Anda menggunakan penyedia identitas pihak ketiga, dan Anda telah menyinkronkan identitas dengan Google Identity. Pengguna akhir Anda menggunakan Google Identity untuk melakukan autentikasi sebelum mengakses resource Google atau Google Workspace.

  • Kasus 3: Anda menggunakan penyedia identitas pihak ketiga, dan Anda telah menyinkronkan identitas dengan Google Identity. Namun, Anda masih menggunakan penyedia identitas pihak ketiga yang ada untuk melakukan autentikasi. Anda telah mengonfigurasi SSO dengan Identitas Google sehingga pengguna memulai login menggunakan Identitas Google, lalu diarahkan ke penyedia identitas pihak ketiga Anda. (Anda mungkin telah melakukan sinkronisasi ini saat menyiapkan resource Google Cloud lain atau Google Workspace.)

• Federasi penyedia identitas pihak ketiga: Jika Anda menggunakan penyedia identitas eksternal, misalnya, Microsoft Entra ID, Okta, atau Ping, tetapi tidak ingin menyinkronkan identitas Anda ke Google Cloud Identity, Anda harus menyiapkan Workforce Identity Federation di Google Cloud sebelum dapat mengaktifkan kontrol akses sumber data untuk Vertex AI Search.

  Jika Anda menggunakan konektor pihak ketiga, atribut google.subject harus dipetakan ke kolom alamat email di penyedia identitas eksternal. Berikut adalah contoh pemetaan atribut google.subject dan google.groups untuk penyedia identitas yang umum digunakan:

  • Microsoft Entra ID dengan protokol OIDC

    google.subject=assertion.email
    google.groups=assertion.groups
    

  • Microsoft Entra ID dengan protokol SAML

    google.subject=assertion.attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'][0]
    google.groups=assertion.attributes['http://schemas.microsoft.com/ws/2008/06/identity/claims/groups']
    

  • Okta dengan protokol OIDC

    google.subject=assertion.email
    google.groups=assertion.groups
    

  • Okta dengan protokol SAML

    google.subject=assertion.subject
    google.groups=assertion.attributes['groups']
    

Batasan

Kontrol akses memiliki batasan berikut:

• Maksimal 3.000 pembaca per dokumen. Setiap akun utama dihitung sebagai pembaca, dengan akun utama dapat berupa grup atau pengguna perorangan.
• Anda dapat memilih satu penyedia identitas per lokasi yang didukung Vertex AI Search.
• Untuk menetapkan sumber data sebagai dikontrol akses, Anda harus memilih setelan ini selama pembuatan penyimpanan data. Anda tidak dapat mengaktifkan atau menonaktifkan setelan ini untuk penyimpanan data yang ada.
• Tab Data > Dokumen di konsol tidak menampilkan data untuk sumber data yang dikontrol aksesnya karena data ini hanya boleh terlihat oleh pengguna yang memiliki akses lihat.
• Untuk melihat pratinjau hasil UI untuk aplikasi penelusuran yang menggunakan kontrol akses pihak ketiga, Anda harus login ke konsol gabungan. Lihat Hasil pratinjau untuk aplikasi yang dikontrol aksesnya.

Sebelum memulai

Prosedur ini mengasumsikan bahwa Anda telah menyiapkan penyedia identitas di project Google Cloud Anda.

• Google Identity: Jika Anda menggunakan Google Identity, Anda dapat melanjutkan ke prosedur Menghubungkan ke penyedia identitas Anda.
• Penyedia identitas pihak ketiga: Pastikan Anda telah menyiapkan kumpulan identitas tenaga kerja untuk penyedia identitas pihak ketiga Anda. Pastikan Anda telah menentukan pemetaan atribut subjek dan grup saat menyiapkan kumpulan tenaga kerja. Untuk mengetahui informasi tentang pemetaan atribut, lihat Pemetaan atribut dalam dokumentasi IAM. Untuk mengetahui informasi selengkapnya tentang workforce identity pool, lihat Mengelola penyedia workforce identity pool dalam dokumentasi IAM.

Menghubungkan ke penyedia identitas Anda

Untuk menentukan penyedia identitas untuk Vertex AI Search dan mengaktifkan kontrol akses sumber data, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman AI Applications.

   AI Applications

2. Buka halaman Settings > Authentication.

3. Klik ikon edit untuk lokasi yang ingin Anda perbarui.

4. Pilih penyedia identitas Anda dalam dialog Tambahkan penyedia identitas. Jika Anda memilih penyedia identitas pihak ketiga, pilih juga kumpulan tenaga kerja yang berlaku untuk sumber data Anda.

5. Klik Simpan perubahan.

Mengonfigurasi sumber data dengan kontrol akses

Untuk menerapkan kontrol akses ke sumber data, ikuti langkah-langkah berikut, bergantung pada jenis sumber data yang Anda siapkan:

• Sumber data pihak ketiga: Tidak ada konfigurasi tambahan yang diperlukan saat Anda membuat aplikasi. Lanjutkan ke Melihat pratinjau hasil untuk aplikasi dengan kontrol akses pihak ketiga
• Google Drive: Tidak ada konfigurasi tambahan yang diperlukan saat Anda membuat aplikasi.
• Data tidak terstruktur dari Cloud Storage
• Data terstruktur dari Cloud Storage
• Data tidak terstruktur dari BigQuery
• Data terstruktur dari BigQuery

Data tidak terstruktur dari Cloud Storage

Saat menyiapkan penyimpanan data untuk data tidak terstruktur dari Cloud Storage, Anda juga perlu mengupload metadata ACL dan menetapkan penyimpanan data sebagai dikontrol akses:

1. Saat menyiapkan data, sertakan informasi ACL dalam metadata Anda menggunakan kolom acl_info. Contoh:

   {
      "id": "<your-id>",
      "jsonData": "<JSON string>",
      "content": {
        "mimeType": "<application/pdf or text/html>",
        "uri": "gs://<your-gcs-bucket>/directory/filename.pdf"
      },
      "acl_info": {
        "readers": [
          {
            "principals": [
              { "group_id": "group_1" },
              { "user_id": "user_1" }
            ]
          }
        ]
      }
    }
   

   Untuk mengetahui informasi selengkapnya tentang data tidak terstruktur dengan metadata, lihat bagian Data tidak terstruktur di Menyiapkan data untuk penyerapan.

2. Saat mengikuti langkah-langkah pembuatan penyimpanan data di Membuat penyimpanan data penelusuran, Anda dapat mengaktifkan kontrol akses dengan melakukan hal berikut di konsol atau menggunakan API:

   • Konsol: Saat membuat penyimpanan data, pilih Penyimpanan data ini berisi informasi kontrol akses selama pembuatan penyimpanan data.
   • API: Saat membuat penyimpanan data, sertakan tanda "aclEnabled": "true" dalam payload JSON Anda.

3. Saat mengikuti langkah-langkah untuk impor data di Membuat penyimpanan data penelusuran, pastikan untuk melakukan hal berikut:

   • Mengupload metadata Anda dengan informasi ACL dari bucket yang sama dengan data tidak terstruktur Anda
   • Jika menggunakan API, tetapkan GcsSource.dataSchema ke document

Data terstruktur dari Cloud Storage

Saat menyiapkan penyimpanan data untuk data terstruktur dari Cloud Storage, Anda juga perlu mengupload metadata ACL dan menetapkan penyimpanan data sebagai yang dikontrol aksesnya:

1. Saat menyiapkan data, sertakan informasi ACL dalam metadata Anda menggunakan kolom acl_info. Contoh:

   {
      "id": "<your-id>",
      "jsonData": "<JSON string>",
      "acl_info": {
        "readers": [
          {
            "principals": [
              { "group_id": "group_1" },
              { "user_id": "user_1" }
            ]
          }
        ]
      }
    }
   

2. Saat mengikuti langkah-langkah pembuatan penyimpanan data di Membuat penyimpanan data penelusuran, Anda dapat mengaktifkan kontrol akses dengan melakukan hal berikut di konsol atau menggunakan API:

   • Konsol: Saat membuat penyimpanan data, pilih Penyimpanan data ini berisi informasi kontrol akses selama pembuatan penyimpanan data.
   • API: Saat membuat penyimpanan data, sertakan tanda "aclEnabled": "true" dalam payload JSON Anda.

3. Saat mengikuti langkah-langkah untuk impor data di Membuat penyimpanan data penelusuran, pastikan untuk melakukan hal berikut:

   • Mengupload metadata Anda dengan informasi ACL dari bucket yang sama dengan data tidak terstruktur Anda
   • Jika menggunakan API, tetapkan GcsSource.dataSchema ke document

Data tidak terstruktur dari BigQuery

Saat menyiapkan penyimpanan data untuk data tidak terstruktur dari BigQuery, Anda perlu menetapkan penyimpanan data sebagai yang dikontrol aksesnya dan memberikan metadata ACL menggunakan skema yang telah ditentukan sebelumnya untuk Vertex AI Search:

1. Saat menyiapkan data, tentukan skema berikut. Jangan gunakan skema kustom.

   [
     {
       "name": "id",
       "mode": "REQUIRED",
       "type": "STRING",
       "fields": []
     },
     {
       "name": "jsonData",
       "mode": "NULLABLE",
       "type": "STRING",
       "fields": []
     },
     {
       "name": "content",
       "type": "RECORD",
       "mode": "NULLABLE",
       "fields": [
         {
           "name": "mimeType",
           "type": "STRING",
           "mode": "NULLABLE"
         },
         {
           "name": "uri",
           "type": "STRING",
           "mode": "NULLABLE"
         }
       ]
     }
     {
       "name": "acl_info",
       "type": "RECORD",
       "mode": "NULLABLE",
       "fields": [
         {
           "name": "readers",
           "type": "RECORD",
           "mode": "REPEATED",
           "fields": [
             {
               "name": "principals",
               "type": "RECORD",
               "mode": "REPEATED",
               "fields": [
                 {
                   "name": "user_id",
                   "type": "STRING",
                   "mode": "NULLABLE"
                 },
                 {
                   "name": "group_id",
                   "type": "STRING",
                   "mode": "NULLABLE"
                 }
               ]
             }
           ]
         }
       ]
     }
   ]
   

2. Sertakan metadata ACL Anda sebagai kolom di tabel BigQuery Anda.

3. Saat mengikuti langkah-langkah di Membuat penyimpanan data penelusuran, aktifkan kontrol akses di konsol atau menggunakan API:

   • Konsol: Saat membuat penyimpanan data, pilih Penyimpanan data ini berisi informasi kontrol akses selama pembuatan penyimpanan data.
   • API: Saat membuat penyimpanan data, sertakan tanda "aclEnabled": "true" dalam payload JSON Anda.

4. Saat mengikuti langkah-langkah untuk impor data di Membuat penyimpanan data penelusuran, jika menggunakan API, tetapkan BigQuerySource.dataSchema ke document.

Data terstruktur dari BigQuery

Saat menyiapkan penyimpanan data untuk data terstruktur dari BigQuery, Anda perlu menyetel penyimpanan data sebagai yang dikontrol aksesnya dan memberikan metadata ACL menggunakan skema yang telah ditentukan untuk Vertex AI Search:

1. Saat menyiapkan data, tentukan skema berikut. Jangan gunakan skema kustom.

   [
     {
       "name": "id",
       "mode": "REQUIRED",
       "type": "STRING",
       "fields": []
     },
     {
       "name": "jsonData",
       "mode": "NULLABLE",
       "type": "STRING",
       "fields": []
     },
     {
       "name": "acl_info",
       "type": "RECORD",
       "mode": "NULLABLE",
       "fields": [
         {
           "name": "readers",
           "type": "RECORD",
           "mode": "REPEATED",
           "fields": [
             {
               "name": "principals",
               "type": "RECORD",
               "mode": "REPEATED",
               "fields": [
                 {
                   "name": "user_id",
                   "type": "STRING",
                   "mode": "NULLABLE"
                 },
                 {
                   "name": "group_id",
                   "type": "STRING",
                   "mode": "NULLABLE"
                 }
               ]
             }
           ]
         }
       ]
     }
   ]
   

2. Sertakan metadata ACL Anda sebagai kolom di tabel BigQuery Anda.

3. Saat mengikuti langkah-langkah di Membuat penyimpanan data penelusuran, aktifkan kontrol akses di konsol atau menggunakan API:

   • Konsol: Saat membuat penyimpanan data, pilih Penyimpanan data ini berisi informasi kontrol akses selama pembuatan penyimpanan data.
   • API: Saat membuat penyimpanan data, sertakan tanda "aclEnabled": "true" dalam payload JSON Anda.

4. Saat mengikuti langkah-langkah untuk impor data di Membuat penyimpanan data penelusuran, pastikan untuk melakukan hal berikut:

   • Jika menggunakan konsol, saat menentukan jenis data yang Anda upload, pilih JSONL untuk data terstruktur dengan metadata
   • Jika menggunakan API, tetapkan BigQuerySource.dataSchema ke document

Melihat pratinjau hasil di konsol Workforce Identity Federation

Untuk melihat pratinjau hasil aplikasi dengan kontrol akses pihak ketiga di konsolGoogle Cloud , Anda harus login dengan kredensial organisasi Anda.

Untuk melihat pratinjau hasil UI, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman AI Applications.

   AI Applications

2. Klik nama aplikasi penelusuran yang hasilnya ingin Anda lihat pratinjaunya.

3. Buka halaman Pratinjau.

4. Klik Preview with federated identity untuk membuka konsol Workforce Identity Federation.

5. Masukkan kredensial penyedia workforce pool dan organisasi Anda.

6. Lihat pratinjau hasil untuk aplikasi Anda di halaman Pratinjau yang muncul.

   Untuk mengetahui informasi selengkapnya tentang cara melihat pratinjau hasil penelusuran, lihat artikel Mendapatkan hasil penelusuran.

Untuk mengetahui informasi selengkapnya tentang konsol Workforce Identity Federation, lihat Tentang konsol (gabungan).

Memberikan izin penelusuran kepada pengguna Anda

Perhatian: Sebelumnya, Google merekomendasikan pemberian peran Discovery Engine Viewer. Peran ini dapat memberikan izin yang lebih luas ke fitur yang mungkin tidak perlu diakses pengguna. Peran Penampil Discovery Engine cocok untuk pengujian awal, tetapi Google merekomendasikan agar Anda menggunakan peran Identity and Access Management (IAM) khusus untuk penggunaan produksi.

Untuk memberi pengguna kemampuan menelusuri data yang dikontrol aksesnya menggunakan aplikasi Anda, Anda harus memberikan akses kepada pengguna di domain atau workforce pool Anda. Google merekomendasikan agar Anda memberikan peran IAM kustom kepada grup pengguna Anda.

• Identitas Google: Jika Anda menggunakan Identitas Google, Google merekomendasikan agar Anda membuat grup Google yang mencakup semua karyawan yang perlu melakukan penelusuran. Jika Anda adalah administrator Google Workspace, Anda dapat menyertakan semua pengguna dalam organisasi ke grup Google dengan mengikuti langkah-langkah di Menambahkan semua pengguna organisasi Anda ke grup.
• Penyedia identitas pihak ketiga: Jika Anda menggunakan penyedia identitas eksternal, misalnya Okta atau Microsoft Entra ID, tambahkan semua orang di kumpulan workforce Anda ke dalam satu grup.

Google merekomendasikan agar Anda membuat peran IAM khusus untuk diberikan kepada grup pengguna Anda, menggunakan izin berikut:

• discoveryengine.answers.get
• discoveryengine.servingConfigs.answer
• discoveryengine.servingConfigs.search
• discoveryengine.sessions.get
• discoveryengine.widgetConfigs.get

Untuk mengetahui informasi selengkapnya tentang izin untuk resource Vertex AI Search menggunakan Identity and Access Management (IAM), lihat Kontrol akses dengan IAM.

Untuk mengetahui informasi selengkapnya tentang peran khusus, lihat Peran khusus dalam dokumentasi IAM.

Memberi otorisasi widget penelusuran

Jika Anda ingin men-deploy widget penelusuran untuk aplikasi yang dikontrol aksesnya, ikuti langkah-langkah berikut:

1. Berikan peran Discovery Engine Viewer kepada pengguna di domain atau kumpulan tenaga kerja Anda yang perlu melakukan panggilan API penelusuran.

2. Buat token otorisasi untuk diteruskan ke widget Anda:

   • Untuk Google Identity: Buat token akses OAuth 2.0.
   • Untuk Workforce Identity Federation: Ikuti langkah-langkah dalam Mendapatkan token berumur pendek untuk Workforce Identity Federation untuk mendapatkan token Anda.

3. Ikuti langkah-langkah di Menambahkan widget dengan token otorisasi untuk meneruskan token ke widget Anda.

Langkah berikutnya

Mendapatkan hasil penelusuran.