Mengelola Kolom Pengguna Kustom

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Anda dapat menentukan kolom kustom untuk pengguna di domain Anda dengan menambahkan skema pengguna khusus ke domain. Anda dapat menggunakan kolom ini untuk menyimpan informasi seperti project yang dikerjakan pengguna, lokasi fisiknya, tanggal perekrutan, atau hal lain yang sesuai dengan kebutuhan bisnis Anda.

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

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

Menetapkan kolom kustom di profil pengguna

Untuk memperbarui atau membuat skema, buat properti customSchemas, lalu 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",
    ...
  },
  ...
}

Kolom kustom satu nilai ditetapkan sebagai key-value pair sederhana, seperti "field1": "value1". Kolom kustom multinilai ditetapkan sebagai array objek, seperti kolom multinilai bernilai standar di API, seperti addresses dan phones. Objek nilai ini mendukung kunci berikut:

Kunci
value Nilai yang akan disimpan, diperlukan.
type Jenis nilai, opsional. Nilainya dapat berupa:
  • custom
  • home
  • other
  • work
customType Jenis nilai kustom, opsional. Harus digunakan saat type disetel 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 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 ini akan mengupdate pengguna dan menetapkan nilai untuk skema kustom employmentData:

PATCH https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

{
  "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.

Telusuri kolom kustom di profil pengguna

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

employmentData.projects:"GeneGnome"

akan menampilkan semua karyawan yang mengerjakan project GeneGnome. Kueri

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

mengembalikan semua karyawan di Atlanta ke atas tingkat pekerjaan 7. Untuk 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 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 pilihan Anda 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 di akun adalah 100.
  • Jumlah maksimum kolom kustom yang diizinkan di akun adalah 100.
  • Jumlah karakter maksimum yang diizinkan dalam kolom string untuk kolom kustom satu nilai 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 (-).
  • Jenis kolom tidak dapat diubah.
  • Kolom satu nilai dapat dibuat multinilai, 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 Mengotorisasi permintaan. 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

Permintaan JSON

Pada contoh di bawah, skema employmentData berisi kolom JobFamily saat pertama kali dibuat. Permintaan tersebut 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 untuk 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 Mengotorisasi permintaan. 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 di akun yang sama, gunakan permintaan GET berikut dan sertakan otorisasi yang dijelaskan dalam Mengizinkan permintaan.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"
        }
      ]
    }
  ]
}