Kelola Kolom Pengguna Kustom

Anda dapat menentukan kolom kustom untuk pengguna di domain dengan menambahkan skema pengguna kustom ke domain. Anda dapat menggunakan kolom ini untuk menyimpan informasi seperti project yang dikerjakan pengguna, lokasi fisik mereka, tanggal mereka dipekerjakan, atau apa pun yang sesuai dengan kebutuhan bisnis Anda.

Untuk memulai, buat satu atau beberapa skema untuk menentukan kolom kustom yang sesuai untuk domain Anda. Anda dapat menentukan sejumlah atribut, seperti nama kolom, jenis (string, boolean, bilangan bulat, dll.), apakah kolom tersebut memiliki satu nilai atau beberapa nilai, dan apakah nilainya dapat dilihat oleh pengguna mana pun di domain Anda atau hanya administrator dan pengguna terkait.

Setelah skema ditentukan, kolom kustom akan berperilaku seperti kolom standar. Anda dapat menetapkannya saat memperbarui pengguna di domain, mengambilnya dengan users.get dan users.list, serta menelusuri kolom kustom.

Catatan: Kolom kustom juga dapat digunakan oleh Cloud Identity Groups API untuk membuat kueri grup dinamis guna menentukan keanggotaan grup. Lihat Memformulasikan dan menguji kueri keanggotaan untuk mengetahui informasi selengkapnya.

Peringatan: Anda tidak boleh menggunakan fitur ini untuk menyimpan informasi identitas pribadi yang sensitif, seperti kredensial akun, nomor identifikasi pemerintah, data pemegang kartu, data rekening keuangan, informasi layanan kesehatan, atau informasi latar belakang yang sensitif.

Menetapkan kolom kustom di profil pengguna

Untuk memperbarui atau membuat skema, buat customSchemasproperti dan tambahkan ke resource pengguna. Di dalam properti customSchemas, kolom kustom dikelompokkan menurut skema dalam format JSON standar:

"customSchemas": {
  "schema1": {
    "field1": "value1",
    "field2": [
      { "value": "value2a" },
      { "value": "value2b" },
      ...
    ],
    ...
  },
  "schema2": {
    "field3": "value3",
    ...
  },
  ...
}

Catatan: Setiap schemaName harus unik dalam satu pelanggan. Menggunakan kembali nama akan menghasilkan error 409: Entity already exists.

Kolom kustom bernilai tunggal ditetapkan sebagai pasangan nilai kunci sederhana, seperti "field1": "value1". Kolom kustom multi-nilai ditetapkan sebagai array objek, seperti kolom multi-nilai standar di API seperti addresses dan phones. Objek nilai ini mendukung kunci berikut:

Kunci
value	Nilai yang akan disimpan, wajib diisi.
type	Jenis nilai, opsional. Kemungkinan nilainya adalah: custom home other work
customType	Jenis nilai kustom, opsional. Harus digunakan saat type ditetapkan ke custom.

Jika kolom kustom dalam skema tidak ditentukan pada waktu pembaruan, kolom tersebut tidak akan berubah. Jika skema itu sendiri tidak ditentukan di customFields pada waktu pembaruan, semua kolom kustom dalam skema tersebut tidak akan diubah. Untuk menghapus kolom kustom atau skema kustom dari profil, Anda harus menetapkannya ke null secara eksplisit:

"schema1": {
  "field1": null // deletes field1 from this profile.
}

Permintaan JSON

Panggilan dalam contoh di bawah memperbarui pengguna dan menetapkan nilai untuk skema kustom employmentData:

PATCH https://admin.googleapis.com/admin/directory/v1/users/[e-mail]

{
  "customSchemas": {
    "employmentData": {
      "employeeNumber": "123456789",
      "jobFamily": "Engineering"
      "location": "Atlanta",
      "jobLevel": 8,
      "projects": [
        { "value": "GeneGnome" },
        { "value": "Panopticon", "type": "work" },
        { "value": "MegaGene", "type": "custom", "customType": "secret" }
      ]
    }
  }
}

Membaca kolom kustom di profil pengguna

Anda dapat mengambil kolom kustom di profil pengguna dengan menetapkan parameter projection dalam permintaan users.get atau users.list ke custom atau full.

Menelusuri kolom kustom di profil pengguna

Anda dapat menelusuri dalam kolom kustom menggunakan parameter query dalam permintaan users.list. Anda meminta kolom kustom dengan sintaksis schemaName.fieldName. Contoh:

employmentData.projects:"GeneGnome"

menampilkan semua karyawan yang bekerja pada project GeneGnome. Kueri

employmentData.location="Atlanta" employmentData.jobLevel>=7

menampilkan semua karyawan di Atlanta di atas tingkat pekerjaan 7. Untuk mengetahui informasi selengkapnya, lihat Menelusuri Pengguna.

Membuat skema pengguna kustom

Skema pengguna kustom dapat ditambahkan ke semua domain akun Google Workspace Anda. Untuk membuat skema pengguna kustom di domain Anda, gunakan permintaan POST berikut dan sertakan otorisasi yang dijelaskan dalam Mengizinkan permintaan. Untuk properti string kueri permintaan, lihat Referensi API.

POST https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas

Semua permintaan pembuatan mengharuskan Anda mengirimkan informasi yang diperlukan untuk memenuhi permintaan. Jika Anda menggunakan library klien, library tersebut akan mengonversi objek data dari bahasa yang Anda pilih menjadi objek berformat data JSON.

Permintaan JSON

Contoh berikut menunjukkan permintaan untuk membuat skema kustom. Untuk mengetahui daftar lengkap properti permintaan dan respons, lihat Referensi API.

{
  "schemaName": "employmentData",
  "fields": [
    {
      "fieldName": "EmployeeNumber",
      "fieldType": "STRING",
      "multiValued": "false"
    },
    {
      "fieldName": "JobFamily",
      "fieldType": "STRING",
      "multiValued": "false"
    }
  ]
}

Respons yang berhasil akan menampilkan kode status HTTP 201, beserta properti untuk skema kustom baru.

Batas skema kustom

• Jumlah maksimum skema kustom yang diizinkan dalam akun adalah 100.
• Jumlah maksimum kolom kustom yang diizinkan dalam akun adalah 100.
• Jumlah maksimum karakter yang diizinkan di kolom string untuk kolom kustom bernilai tunggal adalah 500. Untuk kolom kustom multinilai, jumlah elemen yang diizinkan bergantung pada ukuran nilai yang ditetapkan. Misalnya, Anda dapat menambahkan 150 nilai masing-masing 100 karakter atau 50 nilai masing-masing 500 karakter.
• Karakter yang diizinkan dalam skema kustom dan nama kolom adalah karakter alfanumerik, garis bawah (_), dan tanda hubung (-).
• Mengubah jenis kolom tidak diizinkan.
• Kolom bernilai tunggal dapat dibuat multi-nilai, tetapi operasi invers tidak diizinkan.
• Anda tidak dapat mengganti nama skema atau kolom kustom.

Memperbarui skema pengguna kustom

Untuk memperbarui skema kustom, gunakan permintaan PUT berikut dan sertakan otorisasi yang dijelaskan dalam Meminta otorisasi. schemaKey dapat berupa nama skema atau id skema unik. Untuk properti permintaan dan respons, lihat Referensi API.

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey

Catatan: API ini juga mendukung semantik patch.

Permintaan JSON

Pada contoh di bawah, skema employmentData berisi kolom JobFamily saat pertama kali dibuat. Permintaan memperbarui employmentData agar hanya berisi kolom EmployeeNumber:

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer/schemas/employmentData

{
  "kind": "admin#directory#schema",
  "schemaId": "dKaYmUwmSZy5lreXyh75hQ==",
  "etag": "\"St7vIdePbbDsQUvvrssynd-6JLg/PKg63GvWb7bnVSNRomd_O-Vi66w\"",
  "schemaName": "employmentData",
  "fields": [
    {
      "kind": "admin#directory#schema#fieldspec",
      "fieldId": "21_B4iQIRY-dIFGFgAX-Og==",
      "etag": "\"St7vIdePbbDsQUvvrssynd-6JLg/LZxiGaz6_N4R40OpKbDhOcy2qiE\"",
      "fieldType": "STRING",
      "fieldName": "EmployeeNumber",
      "multiValued": "false"
    }
  ]
}

Semua permintaan pembaruan mengharuskan Anda mengirimkan informasi yang diperlukan untuk memenuhi permintaan.

Respons yang berhasil akan menampilkan kode status HTTP 200, beserta resource skema yang diperbarui.

Mengambil skema pengguna kustom

Untuk mengambil skema kustom, gunakan permintaan GET berikut dan sertakan otorisasi yang dijelaskan dalam Meminta otorisasi. schemaKey dapat berupa nama skema atau id skema unik. Untuk properti permintaan dan respons, lihat Referensi API.

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey

Respons yang berhasil akan menampilkan kode status HTTP 200, beserta properti untuk skema kustom.

{
  "kind": "admin#directory#schema",
  "schemaId": "dKaYmUwmSZy5lreXyh75hQ==",
  "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/PKg63GvWb7bnVSNRomd_O-Vi66w\"",
  "schemaName": "employmentData",
  "fields": [
    {
      "kind": "admin#directory#schema#fieldspec",
      "fieldId": "21_B4iQIRY-dIFGFgAX-Og==",
      "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/LZxiGaz6_N4R40OpKbDhOcy2qiE\"",
      "fieldType": "STRING",
      "fieldName": "EmployeeNumber"
    },
    {
      "kind": "admin#directory#schema#fieldspec",
      "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==",
      "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"",
      "fieldType": "STRING",
      "fieldName": "JobFamily"
    }
  ]
}

Mengambil semua skema pengguna kustom

Untuk mengambil semua skema kustom di akun yang sama, gunakan permintaan GET berikut dan sertakan otorisasi yang dijelaskan dalam Meminta otorisasi.Untuk properti permintaan dan respons, lihat Referensi API.

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas

Respons yang berhasil akan menampilkan kode status HTTP 200, beserta skema kustom untuk akun.

{
  "kind": "admin#directory#schemas",
  "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/iJ1eWn5AKuR-xTdwH_2IBlvSSKo\"",
  "schemas": [
    {
      "kind": "admin#directory#schema",
      "schemaId": "dKaYmUwmSZy5lreXyh75hQ==",
      "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/PKg63GvWb7bnVSNRomd_O-Vi66w\"",
      "schemaName": "employmentData",
      "fields": [
        {
          "kind": "admin#directory#schema#fieldspec",
          "fieldId": "21_B4iQIRY-dIFGFgAX-Og==",
          "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/LZxiGaz6_N4R40OpKbDhOcy2qiE\"",
          "fieldType": "STRING",
          "fieldName": "EmployeeNumber"
        },
        {
          "kind": "admin#directory#schema#fieldspec",
          "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==",
          "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"",
          "fieldType": "STRING",
          "fieldName": "JobFamily"
        }
      ]
    }
  ]
}