Trang này được dịch bởi Cloud Translation API.

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 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 chẳng hạn như dự án mà người dùng của bạn làm việc, vị trí thực tế, ngày thuê của họ 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.), liệu đó là giá trị đơn hay nhiều giá trị và liệu người dùng trong miền của bạn hay chỉ quản trị viên và người dùng được liên kết có thể xem được giá trị của thuộc tính đó.

Sau khi giản đồ được xác định, các trường tuỳ chỉnh hoạt động giống như các trường tiêu chuẩn. Bạn có thể đặt các thuộc tính này khi cập nhật người dùng trên miền của mình, tìm nạp người dùng bằng users.get và users.list, cũng như 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 thuộc tính customSchemas rồi 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 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 thành các cặp khoá-giá trị đơn giản, chẳng hạn như "field1": "value1". Trường tuỳ chỉnh nhiều giá trị được đặt dưới dạng các mảng đối tượng, giống như các trường nhiều giá trị chuẩn trong API, chẳng hạn như addresses và phones. Các đối tượng giá trị này hỗ trợ các khoá sau:

Khoá
`value`	Giá trị cần lưu trữ, là 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 tùy chỉnh của giá trị, không bắt buộc. Bạn phải sử dụng khi đặt `type` thành `custom`.

Nếu một trường tuỳ chỉnh trong giản đồ không được chỉ định tại thời điểm cập nhật, thì trường đó sẽ không thay đổi. Nếu một 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 một 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ụ bên dưới 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 trên cấp độ công việc 7. Để biết thêm thông tin, hãy xem bài viết Người dùng tìm kiếm.

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

Bạn có thể thêm 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 miền của bạn, hãy sử dụng yêu cầu POST sau đây và bao gồm quyền uỷ quyền được mô tả trong phần Yêu cầu cho phép. Để biết các thuộc tính chuỗi truy vấn 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ả yêu cầu tạo đều phải 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ì 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 minh hoạ một yêu cầu tạo giản đồ tuỳ chỉnh. Để biết 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 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 của giản đồ tuỳ chỉnh

Số lượng giản đồ tuỳ chỉnh tối đa được phép trong một tài khoản là 100.
Một tài khoản chỉ được có tối đa 100 trường tuỳ chỉnh.
Số ký tự tối đa được phép trong trường string đối với trường tuỳ chỉnh có một giá trị là 500. Đối với các trường tuỳ chỉnh 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ị gồm 100 ký tự cho mỗi giá trị hoặc 50 giá trị gồm 500 ký tự cho mỗi giá trị.
Ký tự được phép trong giản đồ tuỳ chỉnh và tên trường là ký tự chữ-số, dấu gạch dưới (_) và dấu gạch nối (-).
Không được phép thay đổi loại trường.
Bạn có thể tạo một trường có một giá trị nhiều giá trị nhưng không được phép thực hiện thao tác nghịch đảo.
Bạn không thể đổi tên trường hoặc giản đồ tuỳ chỉnh.

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

Để cập nhật một giản đồ tuỳ chỉnh, hãy sử dụng yêu cầu PUT sau đây và đưa vào uỷ quyền được mô tả trong bài viết Uỷ quyền yêu cầu. schemaKey có thể là tên giản đồ hoặc giản đồ riêng biệt id. Đối với 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.

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ả yêu cầu cập nhật đều phải 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ột 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à đưa vào 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 đồ riêng biệt id. Đối với 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/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 của 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ả 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 và thêm quyền uỷ quyền được mô tả trong phần Cho phép 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 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"
        }
      ]
    }
  ]
}