Menyiapkan kontrol akses sumber data

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

Kontrol akses untuk sumber data Anda di Agent 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, katakanlah karyawan di perusahaan Anda menelusuri dokumen Confluence menggunakan aplikasi penelusuran Anda. Namun, Anda harus memastikan mereka tidak dapat melihat konten melalui aplikasi yang tidak diizinkan untuk mereka akses. Jika telah menyiapkan a workforce pool di Google Cloud penyedia identitas organisasi Anda, maka Anda juga dapat menentukan workforce pool tersebut di Agent Search. Sekarang, jika karyawan menggunakan aplikasi Anda, mereka hanya akan mendapatkan hasil penelusuran untuk dokumen yang sudah 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 Agent Search, Anda harus memiliki penyedia identitas organisasi Anda yang dikonfigurasi di Google Cloud. Framework autentikasi berikut didukung:

  • Google Identity:

    • 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 Google Identity sehingga pengguna memulai login menggunakan Google Identity, 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 Agent 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:

Batasan

Kontrol akses memiliki batasan berikut:

  • 3.000 pembaca diizinkan 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 Agent Search.
  • Untuk menetapkan sumber data sebagai sumber data yang dikontrol aksesnya, Anda harus memilih setelan ini selama pembuatan penyimpanan data. Anda tidak dapat mengaktifkan atau menonaktifkan setelan ini untuk penyimpanan data yang ada.
  • Tab Data > Documents di konsol tidak menampilkan data untuk sumber data yang dikontrol aksesnya karena data ini hanya boleh dilihat 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 Melihat pratinjau hasil untuk aplikasi yang dikontrol aksesnya.

Sebelum memulai

Prosedur ini mengasumsikan bahwa Anda telah menyiapkan penyedia identitas di Google Cloud project 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 workforce identity pool untuk penyedia identitas pihak ketiga Anda. Pastikan Anda telah menentukan pemetaan atribut subjek dan grup saat menyiapkan workforce pool. 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 Agent Search dan mengaktifkan kontrol akses sumber data, ikuti langkah-langkah berikut:

  1. Di Google Cloud konsol, 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 di dialog Add identity provider. Jika Anda memilih penyedia identitas pihak ketiga, pilih juga workforce pool yang berlaku untuk sumber data Anda.

  5. Klik Save changes.

Mengonfigurasi sumber data dengan kontrol akses

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

Data tidak terstruktur dari Cloud Storage

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

  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 untuk 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 This data store contains access control information selama pembuatan penyimpanan data.
    • API: Saat membuat penyimpanan data, sertakan flag "aclEnabled": "true" dalam payload JSON Anda.

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

    • Upload 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 harus mengupload metadata ACL dan menetapkan penyimpanan data sebagai penyimpanan data 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 untuk 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 This data store contains access control information selama pembuatan penyimpanan data.
    • API: Saat membuat penyimpanan data, sertakan flag "aclEnabled": "true" dalam payload JSON Anda.

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

    • Upload 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 harus menetapkan penyimpanan data sebagai penyimpanan data yang dikontrol aksesnya dan memberikan metadata ACL menggunakan skema yang telah ditentukan untuk Agent 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 This data store contains access control information selama pembuatan penyimpanan data.
    • API: Saat membuat penyimpanan data, sertakan flag "aclEnabled": "true" dalam payload JSON Anda.

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

Data terstruktur dari BigQuery

Saat menyiapkan penyimpanan data untuk data terstruktur dari BigQuery, Anda harus menetapkan penyimpanan data sebagai penyimpanan data yang dikontrol aksesnya dan memberikan metadata ACL menggunakan skema yang telah ditentukan untuk Agent 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 This data store contains access control information selama pembuatan penyimpanan data.
    • API: Saat membuat penyimpanan data, sertakan flag "aclEnabled": "true" dalam payload JSON Anda.

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

    • Jika menggunakan konsol, saat menentukan jenis data yang Anda upload, pilih JSONL for structured data with metadata
    • Jika menggunakan API, tetapkan BigQuerySource.dataSchema ke document

Melihat pratinjau hasil di konsol Workforce Identity Federation

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

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

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

    AI Applications

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

  3. Buka halaman Preview.

  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 Preview yang muncul.

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

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

Memberikan izin penelusuran kepada pengguna Anda

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.

  • Google Identity: Jika Anda menggunakan Google Identity, Google merekomendasikan agar Anda membuat grup Google yang menyertakan semua karyawan yang perlu melakukan penelusuran. Jika Anda adalah administrator Google Workspace, Anda dapat menyertakan semua pengguna dalam organisasi ke dalam 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 workforce pool Anda ke satu grup.

Google merekomendasikan agar Anda membuat peran IAM kustom 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 Agent Search menggunakan Identity and Access Management (IAM), lihat Kontrol akses dengan IAM.

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

Mengotorisasi 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 workforce pool Anda yang perlu melakukan panggilan API penelusuran.

  2. Buat token otorisasi untuk diteruskan ke widget Anda:

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

Langkah berikutnya

Mendapatkan hasil penelusuran.