Kelola Kolom Pengguna Kustom

Anda dapat menentukan kolom kustom untuk pengguna di domain Anda dengan menambahkan skema pengguna kustom ke domain. Anda dapat menggunakan kolom ini untuk menyimpan informasi seperti project yang dikerjakan pengguna, lokasi fisik, tanggal mulai bekerja, 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 nilainya tunggal atau multi-nilai, dan apakah nilainya dapat dilihat oleh semua pengguna di domain Anda atau hanya administrator dan pengguna terkait.

Setelah skema ditentukan, kolom kustom akan berperilaku seperti kolom standar. Anda dapat menetapkannya saat mengupdate 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 Merumuskan dan menguji kueri keanggotaan untuk 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 akun keuangan, informasi perawatan kesehatan, atau informasi latar belakang yang sensitif.

Menetapkan kolom kustom di profil pengguna

Untuk memperbarui atau membuat skema, buat properti customSchemas 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 key-value pair sederhana seperti "field1": "value1". Kolom kustom multinilai ditetapkan sebagai array objek, seperti kolom multinilai standar dalam 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 jika 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 dalam customFields pada waktu pembaruan, semua kolom kustom dalam skema tersebut tidak akan berubah. 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 ini mengupdate 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"

mengembalikan semua karyawan yang bekerja pada proyek GeneGnome. Kueri

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

mengembalikan semua karyawan di Atlanta lebih dari tingkat pekerjaan 7. Untuk mengetahui informasi selengkapnya, lihat Pengguna Penelusuran.

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 Permintaan otorisasi. 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 untuk mengirimkan informasi yang diperlukan untuk memenuhi permintaan. Jika Anda menggunakan library klien, library klien akan mengonversi objek data dari bahasa pilihan Anda menjadi objek berformat data JSON.

Permintaan JSON

Contoh berikut menampilkan permintaan untuk membuat skema kustom. Untuk mengetahui daftar lengkap properti permintaan dan respons, baca 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 di satu akun adalah 100.
• Jumlah maksimum kolom kustom yang diizinkan di akun adalah 100.
• Jumlah karakter maksimum yang diizinkan dalam kolom string untuk kolom kustom bernilai tunggal adalah 500. Untuk kolom kustom multi-nilai, jumlah elemen yang diizinkan bergantung pada ukuran nilai yang ditetapkan. Misalnya, Anda dapat menambahkan 150 nilai yang masing-masing terdiri dari 100 karakter atau 50 nilai yang masing-masing terdiri dari 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 menjadi multi-nilai, tetapi operasi terbalik tidak diizinkan.
• Skema atau kolom kustom tidak dapat diganti namanya.

Memperbarui skema pengguna kustom

Untuk memperbarui skema kustom, gunakan permintaan PUT berikut dan sertakan otorisasi yang dijelaskan dalam Permintaan otorisasi. schemaKey dapat berupa nama skema atau skema unik id. 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 update mengharuskan Anda mengirimkan informasi yang diperlukan untuk memenuhi permintaan.

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

Mengambil skema pengguna kustom

Untuk mengambil skema kustom, gunakan permintaan GET berikut dan sertakan otorisasi yang dijelaskan dalam Permintaan otorisasi. schemaKey dapat berupa nama skema atau skema unik id. 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 dalam 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 tersebut.

{
  "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"
        }
      ]
    }
  ]
}