Quản lý trường người dùng tuỳ chỉnh

Bạn có thể xác định các trường tuỳ chỉnh cho người dùng trên miền của mình bằng cách thêm các giản đồ người dùng tuỳ chỉnh vào miền. Bạn có thể sử dụng các trường này để lưu trữ thông tin như dự án mà người dùng đang làm việc, vị trí thực tế của họ, ngày tuyển dụng hoặc bất kỳ thông tin nào khác phù hợp với nhu cầu kinh doanh của bạn.

Để bắt đầu, hãy tạo một hoặc nhiều giản đồ để xác định các trường tuỳ chỉnh phù hợp với miền của bạn. Bạn có thể chỉ định một số thuộc tính, chẳng hạn như tên của trường, loại (chuỗi, boolean, số nguyên, v.v.), trường đó có phải là trường có một giá trị hay nhiều giá trị hay không và liệu người dùng bất kỳ trong miền của bạn có thể xem các giá trị của trường đó hay chỉ quản trị viên và người dùng được liên kết.

Sau khi bạn xác định một giản đồ, các trường tuỳ chỉnh sẽ hoạt động giống như các trường chuẩn. Bạn có thể đặt các trường này khi cập nhật người dùng trên miền của mình, tìm nạp các trường này bằng users.get và users.list, đồng thời tìm kiếm các trường tuỳ chỉnh.

Đặt trường tuỳ chỉnh trong hồ sơ người dùng

Để cập nhật hoặc tạo một giản đồ, hãy tạo một customSchemasthuộc tính và thêm thuộc tính đó vào tài nguyên người dùng. Bên trong thuộc tính customSchemas, các trường tuỳ chỉnh được nhóm theo giản đồ ở định dạng JSON tiêu chuẩn:

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

Các trường tuỳ chỉnh có một giá trị được đặt làm các cặp khoá-giá trị đơn giản, chẳng hạn như "field1": "value1". Các trường tuỳ chỉnh có nhiều giá trị được đặt làm mảng đối tượng, chẳng hạn như các trường có nhiều giá trị tiêu chuẩn trong API như addresses và phones. Các đối tượng giá trị này hỗ trợ các khoá sau:

Khóa
value Giá trị cần lưu trữ, bắt buộc.
type Loại giá trị (không bắt buộc). Các giá trị có thể sử dụng là:
  • custom
  • home
  • other
  • work
customType Loại tuỳ chỉnh của giá trị (không bắt buộc). Phải được dùng khi type được đặt thành custom.

Nếu bạn không chỉ định một trường tuỳ chỉnh trong giản đồ tại thời điểm cập nhật, thì trường đó sẽ không thay đổi. Nếu bản thân giản đồ không được chỉ định trong customFields tại thời điểm cập nhật, thì tất cả các trường tuỳ chỉnh trong giản đồ đó sẽ không thay đổi. Để xoá một trường tuỳ chỉnh hoặc một giản đồ tuỳ chỉnh khỏi hồ sơ, bạn phải đặt trường đó thành null một cách rõ ràng:

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

Yêu cầu JSON

Lệnh gọi trong ví dụ dưới đây sẽ cập nhật một người dùng và đặt các giá trị cho giản đồ tuỳ chỉnh 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" }
      ]
    }
  }
}

Đọc các trường tuỳ chỉnh trong hồ sơ người dùng

Bạn có thể tìm nạp các trường tuỳ chỉnh trong hồ sơ người dùng bằng cách đặt tham số projection trong yêu cầu users.get hoặc users.list thành custom hoặc full.

Tìm kiếm các trường tuỳ chỉnh trong hồ sơ người dùng

Bạn có thể tìm kiếm trong các trường tuỳ chỉnh bằng cách sử dụng tham số query trong yêu cầu users.list. Bạn yêu cầu trường tuỳ chỉnh bằng cú pháp schemaName.fieldName. Ví dụ:

employmentData.projects:"GeneGnome"

trả về tất cả nhân viên làm việc trong dự án GeneGnome. Truy vấn

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

trả về tất cả nhân viên ở Atlanta có cấp bậc công việc từ 7 trở lên. Để biết thêm thông tin, hãy xem phần Tìm kiếm người dùng.

Tạo giản đồ người dùng tuỳ chỉnh

Bạn có thể thêm một giản đồ người dùng tuỳ chỉnh vào tất cả các miền của tài khoản Google Workspace. Để tạo một giản đồ người dùng tuỳ chỉnh trong các miền của bạn, hãy sử dụng yêu cầu POST sau đây và thêm thông tin uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. Để biết các thuộc tính chuỗi truy vấn của yêu cầu, hãy xem Tài liệu tham khảo API.

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

Tất cả các yêu cầu tạo đều yêu cầu bạn gửi thông tin cần thiết để thực hiện yêu cầu. Nếu bạn đang sử dụng thư viện ứng dụng, thì các thư viện này sẽ chuyển đổi các đối tượng dữ liệu từ ngôn ngữ bạn chọn thành các đối tượng được định dạng dữ liệu JSON.

Yêu cầu JSON

Mẫu sau đây cho thấy một yêu cầu tạo giản đồ tuỳ chỉnh. Để xem danh sách đầy đủ các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo về API.

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

Phản hồi thành công sẽ trả về mã trạng thái HTTP 201, cùng với các thuộc tính cho giản đồ tuỳ chỉnh mới.

Giới hạn về giản đồ tuỳ chỉnh

  • Số lượng lược đồ tuỳ chỉnh tối đa được phép trong một tài khoản là 100.
  • Số lượng trường tuỳ chỉnh tối đa được phép trong một tài khoản là 100.
  • Số lượng ký tự tối đa được phép trong trường string đối với một trường tuỳ chỉnh có một giá trị là 500. Đối với các trường tuỳ chỉnh có nhiều giá trị, số lượng phần tử được phép phụ thuộc vào kích thước của các giá trị được chỉ định. Ví dụ: bạn có thể thêm 150 giá trị, mỗi giá trị có 100 ký tự hoặc 50 giá trị, mỗi giá trị có 500 ký tự.
  • Các ký tự được phép dùng trong tên trường và giản đồ tuỳ chỉnh là ký tự chữ-số, dấu gạch dưới (_) và dấu gạch ngang (-).
  • Bạn không được phép thay đổi loại trường.
  • Bạn có thể chuyển một trường có một giá trị thành trường có nhiều giá trị, nhưng không được phép thực hiện thao tác ngược lại.
  • Bạn không thể đổi tên giản đồ hoặc trường tuỳ chỉnh.

Cập nhật giản đồ người dùng tuỳ chỉnh

Để cập nhật giản đồ tuỳ chỉnh, hãy sử dụng yêu cầu PUT sau đây và thêm thông tin uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. schemaKey có thể là tên giản đồ hoặc giản đồ duy nhất id. Để biết các thuộc tính của yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API.

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

Yêu cầu JSON

Trong ví dụ bên dưới, giản đồ employmentData chứa một trường JobFamily khi được tạo ban đầu. Yêu cầu này đang cập nhật employmentData để chỉ chứa một trường 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"
    }
  ]
}

Tất cả các yêu cầu cập nhật đều yêu cầu bạn gửi thông tin cần thiết để thực hiện yêu cầu.

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200, cùng với tài nguyên giản đồ đã cập nhật.

Truy xuất giản đồ người dùng tuỳ chỉnh

Để truy xuất một giản đồ tuỳ chỉnh, hãy sử dụng yêu cầu GET sau đây và thêm thông tin uỷ quyền như mô tả trong phần Uỷ quyền yêu cầu. schemaKey có thể là tên giản đồ hoặc giản đồ duy nhất id. Để biết các thuộc tính của yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API.

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

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200, cùng với các thuộc tính cho giản đồ tuỳ chỉnh.

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

Truy xuất tất cả giản đồ người dùng tuỳ chỉnh

Để truy xuất tất cả các giản đồ tuỳ chỉnh trong cùng một tài khoản, hãy sử dụng yêu cầu GET sau đây và thêm thông tin uỷ quyền như mô tả trong phần Uỷ quyền yêu cầu.Để biết các thuộc tính yêu cầu và phản hồi, hãy xem Tài liệu tham khảo API.

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

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200, cùng với các giản đồ tuỳ chỉnh cho tài khoản.

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