Mengelola 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 mereka, tanggal perekrutan mereka, atau hal lain 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 bernilai tunggal atau ganda, 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 Anda, 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 mengetahui informasi selengkapnya.

Peringatan: Anda tidak boleh menggunakan fitur ini untuk menyimpan informasi identitas pribadi yang bersifat sensitif seperti kredensial akun, nomor identifikasi yang dikeluarkan 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 berdasarkan 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. Penggunaan kembali nama akan menghasilkan error 409: Entity already exists.

Kolom kustom bernilai tunggal ditetapkan sebagai key-value pair sederhana, seperti "field1": "value1". Kolom kustom bernilai ganda ditetapkan sebagai array objek, seperti kolom bernilai ganda 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. Nilainya dapat berupa: 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 akan dibiarkan tidak berubah. Jika skema itu sendiri tidak ditentukan di customFields pada waktu pembaruan, semua kolom kustom dalam skema tersebut akan dibiarkan tidak berubah. Untuk menghapus kolom kustom atau skema kustom dari profil, Anda harus menetapkannya ke null secara eksplisit:

"schema1": {
  "field1": null
}

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 projection parameter 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 mengerjakan project GeneGnome. Kueri

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

menampilkan semua karyawan di Atlanta yang memiliki level pekerjaan di atas 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 permintaan Otorisasi. Untuk properti string kueri permintaan, lihat Referensi API.

POST https://admin.googleapis.com/admin/directory/v1/customer/<var>my_customer or customerId</var>/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 satu akun adalah 100.
• Jumlah maksimum kolom kustom yang diizinkan dalam satu akun adalah 100.
• Jumlah maksimum karakter yang diizinkan dalam kolom string untuk kolom kustom bernilai tunggal adalah 500. Untuk kolom kustom bernilai ganda, jumlah elemen yang diizinkan bergantung pada ukuran nilai yang ditetapkan. Misalnya, Anda dapat menambahkan 150 nilai yang masing-masing berisi 100 karakter atau 50 nilai yang masing-masing berisi 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 bernilai ganda, tetapi operasi sebaliknya tidak diizinkan.
• Nama skema atau kolom kustom tidak dapat diubah.

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 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 juga mendukung semantik patch.

Permintaan JSON

Dalam contoh berikut, skema employmentData berisi kolom JobFamily saat pertama kali dibuat. Permintaan ini 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 permintaan 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 GET permintaan berikut dan sertakan otorisasi yang dijelaskan dalam permintaan 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"
        }
      ]
    }
  ]
}