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 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 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 menyetelnya 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 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",
    ...
  },
  ...
}

Kolom kustom bernilai tunggal ditetapkan sebagai pasangan nilai kunci 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. Nilai yang mungkin adalah:
  • 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 akan dibiarkan tidak berubah. Jika skema itu sendiri tidak ditentukan di customFields pada waktu pembaruan, semua kolom kustom dalam skema tersebut tidak akan berubah. Untuk menghapus kolom kustom atau skema kustom dari profil, Anda harus menyetelnya 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/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.

Menelusuri kolom kustom dalam 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 tingkat 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 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 data berformat 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, bersama dengan 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 karakter maksimum 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 terdiri dari 100 karakter atau 50 nilai yang masing-masing terdiri dari 500 karakter.
  • Karakter yang diizinkan dalam skema dan nama kolom kustom adalah karakter alfanumerik, garis bawah (_), dan tanda hubung (-).
  • Jenis kolom tidak boleh diubah.
  • Kolom bernilai tunggal dapat dibuat bernilai ganda, tetapi operasi sebaliknya 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 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

Permintaan JSON

Dalam 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 tersebut.

Respons yang berhasil akan menampilkan kode status HTTP 200, bersama dengan 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 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, bersama dengan 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 Mengotorisasi 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, bersama dengan 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"
        }
      ]
    }
  ]
}