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 như các dự án mà người dùng 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 trường, loại (chuỗi, boolean, số nguyên, v.v.), liệu trường đó có một hay nhiều giá trị và liệu mọi người dùng 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 mới có thể xem.

Sau khi bạn xác định 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 giá trị 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 giá trị này 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 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ó giá trị đơn được đặt dưới dạng 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 dưới dạng mảng đối tượng, giống như các trường nhiều giá trị 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 sử dụng khi `type` được đặt thành `custom`.

Nếu bạn không chỉ định 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 chính 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 giản đồ tuỳ chỉnh khỏi hồ sơ, bạn phải đặt trường hoặc giản đồ đó 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 người dùng và đặt 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 thông 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ấp công việc trên 7. Để biết thêm thông tin, hãy xem phần 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ả miền của tài khoản Google Workspace. Để tạo 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 quyền uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu. Đối với 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 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 đối tượng dữ liệu từ ngôn ngữ bạn chọn thành đối tượng dữ liệu được định dạng 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 giản đồ 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ố ký tự tối đa được phép trong trường string cho 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 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 của trường.
Bạn có thể tạo trường có nhiều giá trị từ trường có một giá trị, nhưng không được phép thực hiện phép toán nghịch đảo.
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 quyền 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. Đố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 trường JobFamily khi được tạo ban đầu. Yêu cầu này đang cập nhật employmentData để chỉ chứa 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 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 giản đồ tuỳ chỉnh, hãy sử dụng yêu cầu GET sau đây và đưa vào quyền 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. Đố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 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à đưa vào thông tin uỷ quyền được mô tả trong phần Uỷ quyền yêu cầu.Đố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

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