จัดการช่องของผู้ใช้ที่กำหนดเอง

คุณสามารถระบุช่องที่กำหนดเองสำหรับผู้ใช้ในโดเมนของคุณได้โดยการเพิ่มสคีมาของผู้ใช้ที่กำหนดเองลงในโดเมน คุณสามารถใช้ช่องเหล่านี้เพื่อจัดเก็บข้อมูลต่างๆ เช่น โครงการที่ผู้ใช้ทำงาน สถานที่ตั้งจริง วันที่จ้าง หรือสิ่งอื่นๆ ที่เหมาะกับความต้องการทางธุรกิจของคุณ

หากต้องการเริ่มต้นใช้งาน ให้สร้างสคีมาอย่างน้อย 1 รายการเพื่อกำหนดช่องที่กำหนดเองที่เหมาะกับโดเมนของคุณ คุณระบุแอตทริบิวต์ได้หลายรายการ เช่น ชื่อของช่อง ประเภท (สตริง บูลีน จำนวนเต็ม ฯลฯ) ไม่ว่าจะเป็นค่าเดี่ยวหรือหลายค่า และใครๆ ในโดเมนก็ดูค่านั้นได้หรือเฉพาะผู้ดูแลระบบและผู้ใช้ที่เกี่ยวข้องเท่านั้น

เมื่อกำหนดสคีมาแล้ว ช่องที่กำหนดเองจะทำงานเหมือนกับช่องมาตรฐาน โดยคุณจะตั้งค่าได้เมื่ออัปเดตผู้ใช้ในโดเมน ดึงข้อมูลผู้ใช้ด้วย users.get และ users.list และค้นหาช่องที่กำหนดเอง

ตั้งค่าช่องที่กำหนดเองในโปรไฟล์ผู้ใช้

หากต้องการอัปเดตหรือสร้างสคีมา ให้สร้างพร็อพเพอร์ตี้ customSchemas แล้วเพิ่มลงในทรัพยากรของผู้ใช้ ภายในพร็อพเพอร์ตี้ customSchemas ระบบจะจัดกลุ่มช่องที่กำหนดเองตามสคีมาในรูปแบบ JSON มาตรฐาน ดังนี้

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

ช่องที่กำหนดเองแบบค่าเดียวจะตั้งค่าเป็นคู่คีย์-ค่าแบบง่าย เช่น "field1": "value1" ช่องที่กำหนดเองที่มีหลายค่าจะตั้งค่าเป็นอาร์เรย์ของออบเจ็กต์ เช่น ช่องที่มีหลายค่าแบบมาตรฐานใน API เช่น addresses และ phones ออบเจ็กต์ค่าเหล่านี้รองรับคีย์ต่อไปนี้

คีย์
value ค่าที่จะจัดเก็บ ต้องระบุ
type ประเภทของค่า (ไม่บังคับ) ค่าที่เป็นไปได้มีดังนี้
  • custom
  • home
  • other
  • work
customType ประเภทค่าที่กำหนดเอง ไม่บังคับ ต้องใช้เมื่อตั้งค่า type เป็น custom

หากไม่ได้ระบุช่องที่กำหนดเองในสคีมา ณ เวลาที่อัปเดต ช่องนั้นจะไม่เปลี่ยนแปลง หากไม่ได้ระบุสคีมาไว้ใน customFields ณ เวลาที่อัปเดต ช่องที่กำหนดเองทั้งหมดในสคีมานั้นจะไม่เปลี่ยนแปลง หากต้องการลบช่องที่กำหนดเองหรือสคีมาที่กำหนดเองออกจากโปรไฟล์ คุณต้องตั้งค่าเป็น null อย่างชัดแจ้ง ดังนี้

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

คำขอ JSON

การเรียกในตัวอย่างด้านล่างจะอัปเดตผู้ใช้และกำหนดค่าสำหรับสคีมาที่กำหนดเอง 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" }
      ]
    }
  }
}

อ่านช่องที่กำหนดเองในโปรไฟล์ผู้ใช้

คุณดึงข้อมูลช่องที่กำหนดเองในโปรไฟล์ผู้ใช้ได้โดยตั้งค่าพารามิเตอร์ projection ในคำขอ users.get หรือ users.list เป็น custom หรือ full

ค้นหาช่องที่กำหนดเองในโปรไฟล์ผู้ใช้

คุณจะค้นหาภายในช่องที่กำหนดเองได้โดยใช้พารามิเตอร์ query ในคำขอ users.list คุณต้องขอช่องที่กำหนดเองด้วยไวยากรณ์ schemaName.fieldName เช่น

employmentData.projects:"GeneGnome"

ส่งคืนพนักงานทั้งหมดที่ทำงานในโปรเจ็กต์ GeneGnome ข้อความค้นหา

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

ส่งคืนพนักงานทั้งหมดในแอตแลนตาที่สูงกว่าระดับงาน 7 ดูข้อมูลเพิ่มเติมได้ที่ค้นหาผู้ใช้

สร้างสคีมาของผู้ใช้ที่กําหนดเอง

คุณสามารถเพิ่มสคีมาของผู้ใช้ที่กำหนดเองลงในโดเมนของบัญชี Google Workspace ทั้งหมดได้ หากต้องการสร้างสคีมาของผู้ใช้ที่กำหนดเองในโดเมน ให้ใช้คำขอ POST ต่อไปนี้และรวมการให้สิทธิ์ที่อธิบายไว้ในคำขอสิทธิ์ สำหรับพร็อพเพอร์ตี้สตริงการค้นหาคำขอ โปรดดูการอ้างอิง API

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

คำขอสร้างทั้งหมดกำหนดให้คุณส่งข้อมูลที่จำเป็นต่อการดำเนินการตามคำขอ หากคุณใช้ไลบรารีของไคลเอ็นต์ ระบบจะแปลงออบเจ็กต์ข้อมูลจากภาษาที่คุณเลือกเป็นออบเจ็กต์ที่มีการจัดรูปแบบข้อมูล JSON

คำขอ JSON

ตัวอย่างต่อไปนี้แสดงคำขอสร้างสคีมาที่กำหนดเอง ดูรายการพร็อพเพอร์ตี้คำขอและการตอบกลับทั้งหมดได้ที่ข้อมูลอ้างอิง API

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

การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 201 พร้อมกับพร็อพเพอร์ตี้สำหรับสคีมาใหม่ที่กำหนดเอง

ขีดจำกัดของสคีมาที่กำหนดเอง

  • จำนวนสคีมาที่กำหนดเองสูงสุดที่อนุญาตในบัญชีคือ 100 รายการ
  • จำนวนช่องที่กำหนดเองสูงสุดที่อนุญาตในบัญชีคือ 100 ช่อง
  • จำนวนอักขระสูงสุดที่อนุญาตในช่อง string สำหรับช่องที่กำหนดเองแบบค่าเดียวคือ 500 ตัว สำหรับช่องที่กำหนดเองที่มีหลายค่า จำนวนองค์ประกอบที่อนุญาตจะขึ้นอยู่กับขนาดของค่าที่กำหนดไว้ ตัวอย่างเช่น คุณจะเพิ่มค่าได้ 150 ค่า โดยแต่ละค่ามีอักขระ 100 ตัว หรือให้มีค่าละ 500 ตัว จำนวน 50 ค่า
  • อักขระที่อนุญาตในสคีมาที่กำหนดเองและชื่อช่องคืออักขระที่เป็นตัวอักษรและตัวเลขคละกัน ขีดล่าง (_) และขีดกลางสั้น (-)
  • ไม่อนุญาตให้เปลี่ยนประเภทของช่อง
  • ช่องที่มีค่าเดียวสามารถทำให้มีหลายค่าได้ แต่ระบบจะไม่อนุญาตการดำเนินการแบบผกผัน
  • เปลี่ยนชื่อสคีมาหรือฟิลด์ที่กำหนดเองไม่ได้

อัปเดตสคีมาของผู้ใช้ที่กำหนดเอง

หากต้องการอัปเดตสคีมาที่กำหนดเอง ให้ใช้คำขอ PUT ต่อไปนี้และรวมการให้สิทธิ์ที่อธิบายไว้ในคำขอให้สิทธิ์ schemaKey อาจเป็นชื่อสคีมาหรือสคีมาที่ไม่ซ้ำกัน id ก็ได้ สำหรับพร็อพเพอร์ตี้คำขอและการตอบกลับ โปรดดูเอกสารอ้างอิง API

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

คำขอ JSON

ในตัวอย่างด้านล่าง สคีมา employmentData มีช่อง JobFamily เมื่อสร้างในตอนแรก คำขอนี้กำลังอัปเดต employmentData ให้มีเฉพาะช่อง 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"
    }
  ]
}

คำขออัปเดตทั้งหมดกำหนดให้คุณต้องส่งข้อมูลที่จำเป็นในการดำเนินการตามคำขอให้เสร็จสมบูรณ์

การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 200 พร้อมกับทรัพยากรสคีมาที่อัปเดตแล้ว

ดึงข้อมูลสคีมาของผู้ใช้ที่กำหนดเอง

หากต้องการเรียกข้อมูลสคีมาที่กำหนดเอง ให้ใช้คำขอ GET ต่อไปนี้และรวมการให้สิทธิ์ที่อธิบายไว้ในคำขอให้สิทธิ์ schemaKey อาจเป็นชื่อสคีมาหรือสคีมาที่ไม่ซ้ำกัน id ก็ได้ สำหรับพร็อพเพอร์ตี้คำขอและการตอบกลับ โปรดดูเอกสารอ้างอิง API

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

การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 200 พร้อมกับพร็อพเพอร์ตี้สำหรับสคีมาที่กำหนดเอง

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

ดึงข้อมูลสคีมาของผู้ใช้ที่กำหนดเองทั้งหมด

หากต้องการเรียกสคีมาที่กําหนดเองทั้งหมดในบัญชีเดียวกัน ให้ใช้คําขอ GET ต่อไปนี้และรวมการให้สิทธิ์ที่อธิบายไว้ในคำขอการให้สิทธิ์ สําหรับพร็อพเพอร์ตี้คําขอและการตอบกลับ โปรดดูข้อมูลอ้างอิง API

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

การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 200 พร้อมกับสคีมาที่กำหนดเองสำหรับบัญชี

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