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

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

หากต้องการเริ่มต้นใช้งาน ให้สร้างสคีมาอย่างน้อย 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

แสดงผลพนักงานทั้งหมดใน Atlanta ที่สูงกว่าระดับงาน 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 ตัวต่อค่า หรือค่า 50 ค่าที่มีอักขระ 500 ตัวต่อค่า
  • อักขระที่อนุญาตในสคีมาและชื่อช่องที่กำหนดเองคืออักขระที่เป็นตัวอักษรและตัวเลขคละกัน ขีดล่าง (_) และขีดกลาง (-)
  • ไม่อนุญาตให้เปลี่ยนประเภทของช่อง
  • ช่องที่มีค่าเดียวสามารถทําให้เป็นช่องที่มีหลายค่าได้ แต่จะทําการดำเนินการแบบย้อนกลับไม่ได้
  • คุณไม่สามารถเปลี่ยนชื่อสคีมาหรือฟิลด์ที่กำหนดเอง

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

หากต้องการอัปเดตสคีมาที่กำหนดเอง ให้ใช้คำขอ 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"
        }
      ]
    }
  ]
}