จัดการบัญชีผู้ใช้

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

สร้างบัญชีผู้ใช้

คุณเพิ่มบัญชีผู้ใช้ลงในโดเมนของบัญชี Google Workspace ได้ ก่อนเพิ่มบัญชีผู้ใช้ ให้ยืนยันการเป็นเจ้าของโดเมน

หากอัปเกรดบัญชี Gmail ส่วนตัวเป็นบัญชีอีเมลธุรกิจที่มีชื่อโดเมนของคุณเอง คุณจะสร้างบัญชีผู้ใช้ใหม่ไม่ได้จนกว่าจะปลดล็อกการตั้งค่า Google Workspace เพิ่มเติม ดูรายละเอียดได้ที่อัปเดตบัญชีอีเมลธุรกิจของ G Suite เป็น G Suite Basic แล้ว

หากต้องการสร้างบัญชีผู้ใช้โดยใช้โดเมนใดโดเมนหนึ่ง ให้ใช้คำขอ POST ต่อไปนี้และรวมการให้สิทธิ์ที่อธิบายไว้ในดูข้อมูลเกี่ยวกับการตรวจสอบสิทธิ์และการให้สิทธิ์ คุณดูขอบเขตที่ใช้ได้สำหรับ Directory API ได้ในรายการขอบเขต OAuth 2.0 สำหรับพร็อพเพอร์ตี้สตริงคำค้นหาของคำขอ โปรดดูเมธอด users.insert()

POST https://admin.googleapis.com/admin/directory/v1/users

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

คำขอ JSON

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

{
"primaryEmail": "liz@example.com",
"name": {
 "givenName": "Elizabeth",
 "familyName": "Smith"
},
"suspended": false,
"password": "new user password",
"hashFunction": "SHA-1",
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"ims": [
 {
  "type": "work",
  "protocol": "gtalk",
  "im": "liz_im@talk.example.com",
  "primary": true
 }
],
"emails": [
 {
  "address": "liz@example.com",
  "type": "home",
  "customType": "",
  "primary": true
 }
],
"addresses": [
 {
  "type": "work",
  "customType": "",
  "streetAddress": "1600 Amphitheatre Parkway",
  "locality": "Mountain View",
  "region": "CA",
  "postalCode": "94043"
 }
],
"externalIds": [
 {
  "value": "12345",
  "type": "custom",
  "customType": "employee"
 }
],
"organizations": [
 {
  "name": "Google Inc.",
  "title": "SWE",
  "primary": true,
  "type": "work",
  "description": "Software engineer"
 }
],
"phones": [
 {
  "value": "+1 nnn nnn nnnn",
  "type": "work"
 }
],
"orgUnitPath": "/corp/engineering",
"includeInGlobalAddressList": true
}

หากอัตราการค้นหาสำหรับคำขอสร้างสูงเกินไป คุณอาจได้รับการตอบกลับ HTTP 503 จากเซิร์ฟเวอร์ API ซึ่งบ่งชี้ว่าคุณใช้โควต้าเกินแล้ว หากได้รับการตอบกลับเหล่านี้ ให้ใช้อัลกอริทึมการถอยแบบทวีคูณเพื่อลองส่งคำขออีกครั้ง

สิ่งที่ควรทราบเกี่ยวกับบัญชีใหม่มีดังนี้

หากบัญชี Google ซื้อใบอนุญาตอีเมลไว้ ระบบจะกำหนดกล่องจดหมายให้กับบัญชีผู้ใช้ใหม่โดยอัตโนมัติ การกำหนดนี้อาจใช้เวลาสักครู่จึงจะเสร็จสมบูรณ์และเปิดใช้งาน
บริการ API จะไม่สนใจการแก้ไขฟิลด์แบบอ่านอย่างเดียวในคำขอ เช่น isAdmin โดยไม่มีการแจ้งเตือน
จำนวนโดเมนสูงสุดที่อนุญาตในบัญชีคือ 600 โดเมน (โดเมนหลัก 1 โดเมน + โดเมนเพิ่มเติม 599 โดเมน)
หากไม่ได้กำหนดผู้ใช้ให้กับหน่วยขององค์กรใดหน่วยหนึ่งเมื่อสร้างบัญชีผู้ใช้ บัญชีจะอยู่ในหน่วยขององค์กรระดับบนสุด หน่วยขององค์กรของผู้ใช้เป็นตัวกำหนดบริการของ Google Workspace ที่ผู้ใช้มีสิทธิ์เข้าถึง หากมีการย้ายผู้ใช้ไปยังองค์กรใหม่ สิทธิ์เข้าถึงของผู้ใช้จะมีการเปลี่ยนแปลง ดูข้อมูลเพิ่มเติมเกี่ยวกับโครงสร้างองค์กรได้ที่ศูนย์ช่วยเหลือด้านการดูแลระบบ ดูข้อมูลเพิ่มเติมเกี่ยวกับการย้ายผู้ใช้ไปยังองค์กรอื่นได้ที่อัปเดตผู้ใช้
ต้องมีpasswordสำหรับบัญชีผู้ใช้ใหม่ หากระบุ hashFunction รหัสผ่านต้องเป็นคีย์แฮชที่ถูกต้อง หากไม่ได้ระบุไว้ รหัสผ่านควรเป็นข้อความธรรมดาและมีความยาวระหว่าง 8-100 อักขระ ASCII ดูข้อมูลเพิ่มเติมได้ที่เอกสารอ้างอิง API
สำหรับผู้ใช้ที่ใช้แพ็กเกจแบบยืดหยุ่นสำหรับ Google Workspace การสร้างผู้ใช้โดยใช้ API นี้จะมีผลกระทบทางการเงิน และจะส่งผลให้มีการเรียกเก็บเงินจากบัญชีสำหรับการเรียกเก็บเงินของลูกค้า ดูข้อมูลเพิ่มเติมได้ที่ข้อมูลการเรียกเก็บเงินของ API
บัญชี Google Workspace สามารถมีโดเมนใดก็ได้ ในบัญชีที่มีหลายโดเมน ผู้ใช้ในโดเมนหนึ่งจะแชร์บริการกับผู้ใช้ในโดเมนบัญชีอื่นๆ ได้ ดูข้อมูลเพิ่มเติมเกี่ยวกับผู้ใช้ในหลายโดเมนได้ที่ข้อมูลหลายโดเมนของ API
อาจมีบัญชีที่ทับซ้อนกัน ตรวจสอบว่าบุคคลที่คุณต้องการเพิ่มมีบัญชี Google อยู่แล้วหรือไม่ จากนั้นทำตามขั้นตอนเพื่อหลีกเลี่ยงไม่ให้บัญชีทับซ้อนกัน ดูหัวข้อค้นหาและแก้ไขบัญชีที่ทับซ้อนกัน
อาจมีบัญชีผู้เข้าชม หากผู้ใช้เชิญบุคคลภายนอกองค์กรที่ไม่มีบัญชี Google ให้ทำงานร่วมกันในไดรฟ์ บุคคลดังกล่าวจะได้รับบัญชีผู้มาเยือนในรูปแบบ visitor's_username@your_domain.com หากคุณเพิ่มผู้ใช้ที่มีชื่อผู้ใช้เดียวกับบัญชีผู้มาเยือน ระบบจะแปลงบัญชีดังกล่าวเป็นบัญชี Google Workspace แบบเต็ม ซึ่งจะเก็บสิทธิ์ของไฟล์ในไดรฟ์ปัจจุบันไว้ โปรดดูที่หัวข้อแชร์เอกสารกับผู้เข้าชม

การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 200 นอกเหนือจากรหัสสถานะแล้ว การตอบสนองจะแสดงพร็อพเพอร์ตี้สำหรับบัญชีผู้ใช้ใหม่ด้วย

อัปเดตบัญชีผู้ใช้

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

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey

ทั้งเนื้อหาคำขอและคำตอบมีอินสแตนซ์ของ User อย่างไรก็ตาม Directory API รองรับความหมายของการแก้ไข คุณจึงต้องส่งเฉพาะช่องที่อัปเดตในคำขอ

ตัวอย่างคำขอ

ในตัวอย่างด้านล่าง givenName ของผู้ใช้คือ "Elizabeth" เมื่อมีการสร้างบัญชีผู้ใช้ และมีการระบุอีเมลที่ทำงานเท่านั้น

{
  "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith"
   },
  "emails": [
    {
      "address": "liz@example.com",
      "type": "work",
      "primary": true
    }
  ]
}

คำขอต่อไปนี้จะอัปเดต givenName จาก "Elizabeth" เป็น "Liz" และ เพิ่มอีเมลบ้านด้วย โปรดทราบว่าระบบจะระบุอีเมลทั้ง 2 รายการ อย่างครบถ้วนเนื่องจากช่องนี้เป็นอาร์เรย์

PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

{
  "name": {
    "givenName": "Liz",
   },
  "emails": [
    {
      "address": "liz@example.com",
      "type": "work",
      "primary": true
    },
    {
      "address": "liz@home.com",
      "type": "home"
    }
  ]
}

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

โปรดคำนึงถึงสิ่งต่อไปนี้เมื่ออัปเดตชื่อบัญชีของผู้ใช้

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

กำหนดให้ผู้ใช้เป็นผู้ดูแลระบบ

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

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/makeAdmin

หมายเหตุ: ผู้ใช้ต้องมีอยู่ก่อนจึงจะกำหนดให้เป็นผู้ดูแลระบบขั้นสูงได้ การดำเนินการนี้จะทำได้โดยผู้ดูแลระบบขั้นสูงของบัญชีเท่านั้น ผู้ดูแลระบบที่ได้รับมอบสิทธิ์ไม่สามารถเลื่อนระดับผู้ใช้ให้มีบทบาทผู้ดูแลระบบได้ ดูข้อมูลเกี่ยวกับการใช้คอนโซลผู้ดูแลระบบเพื่อเปลี่ยนบทบาทของผู้ดูแลระบบได้ที่ศูนย์ช่วยเหลือด้านการดูแลระบบ

คำขอ JSON

ในตัวอย่างนี้ ผู้ใช้ที่มี userKey คือ liz@example.com ได้กลายเป็นผู้ดูแลระบบขั้นสูงแล้ว

POST https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/makeAdmin

{
 "status": true
}

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

จัดการความสัมพันธ์ของผู้ใช้

Directory API ใช้ฟิลด์ relations เพื่อกำหนดความสัมพันธ์ประเภทต่างๆ ระหว่างผู้ใช้ ในสภาพแวดล้อมทางธุรกิจ ผู้คนมักใช้ช่องนี้สำหรับความสัมพันธ์ระหว่างผู้จัดการกับพนักงานและผู้ช่วย แต่ช่องนี้รองรับความสัมพันธ์ประเภทอื่นๆ อีกมากมายด้วย ความสัมพันธ์จะแสดงในการ์ด "บุคคลที่เกี่ยวข้อง" ของผู้ใช้ในแอปพลิเคชัน Google Workspace ที่รองรับการ์ด ดูตัวอย่างตำแหน่งที่การ์ดปรากฏได้ที่หัวข้อ เพิ่มข้อมูลไปยังโปรไฟล์ไดเรกทอรีของผู้ใช้

สร้างความสัมพันธ์ระหว่างผู้ใช้

คุณกำหนดความสัมพันธ์ได้ในทิศทางเดียวเท่านั้น โดยเริ่มจากผู้ใช้ที่เป็น "เจ้าของ" ซึ่งมีฟิลด์ relations อยู่ในระเบียน type อธิบายความสัมพันธ์ของบุคคลอื่นกับผู้ใช้ที่เป็นเจ้าของ ตัวอย่างเช่น ในความสัมพันธ์ระหว่างผู้จัดการกับพนักงาน พนักงานจะเป็นผู้ใช้ที่เป็นเจ้าของ และคุณจะเพิ่มฟิลด์ relations ลงในบัญชีของพนักงานโดยมีประเภทเป็น manager สำหรับ ประเภทที่อนุญาต โปรดดูการอ้างอิงออบเจ็กต์ User

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

{
  "relations": [
    {
      "value": "EMAIL_ADDRESS_RELATION_1",
      "type": "manager"
    },
    {
      "value": "EMAIL_ADDRESS_RELATION_2",
      "type": "dotted_line_manager"
    }
  ]
}

อัปเดตหรือลบความสัมพันธ์

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

{
  "relations": [
    {
      "value": "EMAIL_ADDRESS_RELATION_2",
      "type": "manager"
    }
  ]
}

หากต้องการนำความสัมพันธ์ทั้งหมดของผู้ใช้ที่เป็นเจ้าของออก ให้ตั้งค่า relations เป็นค่าว่าง

{
  "relations": []
}

ดึงข้อมูลผู้ใช้

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

GET https://admin.googleapis.com/admin/directory/v1/users/userKey

ตัวอย่างนี้จะแสดงพร็อพเพอร์ตี้บัญชีผู้ใช้สำหรับผู้ใช้ที่มีอีเมลหลักหรืออีเมลแทนเป็น liz@example.com

GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

การตอบสนองของ JSON

การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 200 นอกเหนือจากรหัสสถานะแล้ว การตอบกลับจะแสดงพร็อพเพอร์ตี้สำหรับบัญชีผู้ใช้ด้วย

{
 "kind": "directory#user",
 "id": "the unique user id",
 "primaryEmail": "liz@example.com",
 "name": {
  "givenName": "Liz",
  "familyName": "Smith",
  "fullName": "Liz Smith"
 },
 "isAdmin": true,
 "isDelegatedAdmin": false,
 "lastLoginTime": "2013-02-05T10:30:03.325Z",
 "creationTime": "2010-04-05T17:30:04.325Z",
 "agreedToTerms": true,
 "hashFunction": "SHA-1",
 "suspended": false,
 "changePasswordAtNextLogin": false,
 "ipWhitelisted": false,
 "ims": [
  {
   "type": "work",
   "protocol": "gtalk",
   "im": "lizim@talk.example.com",
   "primary": true
  }
 ],
 "emails": [
  {
   "address": "liz@example.com",
   "type": "home",
   "customType": "",
   "primary": true
  }
 ],
 "addresses": [
  {
   "type": "work",
   "customType": "",
   "streetAddress": "1600 Amphitheatre Parkway",
   "locality": "Mountain View",
   "region": "CA",
   "postalCode": "94043"
  }
 ],
 "externalIds": [
  {
   "value": "employee number",
   "type": "custom",
   "customType": "office"
  }
 ],
 "organizations": [
  {
   "name": "Google Inc.",
   "title": "SWE",
   "primary": true,
   "customType": "",
   "description": "Software engineer"
  }
 ],
 "phones": [
  {
   "value": "+1 nnn nnn nnnn",
   "type": "work"
  }
 ],
 "aliases": [
  "lizsmith@example.com",
  "lsmith@example.com"
 ],
 "nonEditableAliases": [
  "liz@test.com"
 ],
 "customerId": "C03az79cb",
 "orgUnitPath": "corp/engineering",
 "isMailboxSetup": true,
 "includeInGlobalAddressList": true
}

ดึงข้อมูลผู้ใช้ทั้งหมดในโดเมน

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

GET https://admin.googleapis.com/admin/directory/v1/users
?domain=primary domain name&pageToken=token for next results page
&maxResults=max number of results per page
&orderBy=email, givenName, or familyName
&sortOrder=ascending or descending
&query=email, givenName, or familyName:the query's value*

ดูพร็อพเพอร์ตี้คำขอและการตอบกลับได้ในเอกสารอ้างอิง API

การตอบสนองของ JSON

ในตัวอย่างนี้ ระบบจะแสดงผู้ใช้ทั้งหมดในโดเมน example.com โดยมีโดเมนผู้ใช้สูงสุด 2 โดเมนต่อหน้าการตอบกลับ มีnextPageTokenสำหรับรายชื่อผู้ใช้ที่ติดตามในคำตอบนี้ โดยค่าเริ่มต้น ระบบจะแสดงรายชื่อผู้ใช้ 100 รายตามลำดับตัวอักษรของอีเมลของผู้ใช้

GET https://admin.googleapis.com/admin/directory/v1/users?domain=example.com&maxResults=2

การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 200 นอกเหนือจากรหัสสถานะแล้ว การตอบสนองจะแสดงบัญชีผู้ใช้ 2 บัญชีในโดเมน example.com (maxResults=2) ดังนี้

หมายเหตุ: เมื่อดึงข้อมูลผู้ใช้ทั้งหมดในโดเมน ค่าของ lastLoginTime อาจไม่ถูกต้อง หากต้องการรับค่าที่ถูกต้องที่สุดสำหรับ lastLoginTime ให้เรียกข้อมูลผู้ใช้แทน

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "liz@example.com",
   "name": {
    "givenName": "Liz",
    "familyName": "Smith",
    "fullName": "Liz Smith"
   },
   "isAdmin": true,
   "isDelegatedAdmin": false,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "ims": [
    {
     "type": "work",
     "protocol": "gtalk",
     "im": "lizim@talk.example.com",
     "primary": true
    }
   ],
   "emails": [
    {
     "address": "liz@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "addresses": [
    {
     "type": "work",
     "customType": "",
     "streetAddress": "1600 Amphitheatre Parkway",
     "locality": "Mountain View",
     "region": "CA",
     "postalCode": "94043"
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "organizations": [
    {
     "name": "Google Inc.",
     "title": "SWE",
     "primary": true,
     "customType": "",
     "description": "Software engineer"
    }
   ],
   "phones": [
    {
     "value": "+1 nnn nnn nnnn",
     "type": "work"
    }
   ],
   "aliases": [
    "lizsmith@example.com",
    "lsmith@example.com"
   ],
   "nonEditableAliases": [
    "liz@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "user unique ID",
   "primaryEmail": "admin2@example.com",
   "name": {
    "givenName": "admin",
    "familyName": "two",
    "fullName": "admin two"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": true,
   "suspensionReason": "ADMIN",
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "admin2@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "contractor license number",
     "type": "custom",
     "customType": "work"
    }
   ],
   "aliases": [
    "second_admin@example.com"
   ],
   "nonEditableAliases": [
    "admin@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "corp/engineering",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "next page token"
}

ดึงข้อมูลผู้ใช้บัญชีทั้งหมด

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

GET https://admin.googleapis.com/admin/directory/v1/users
?customer=my_customer or customerId&pageToken=token for next results page
&maxResults=max number of results per page
&orderBy=email, givenName, or familyName
&sortOrder=ascending or descending
&query=user attributes

customer สตริงการค้นหาคือค่า my_customer หรือ customerId
ใช้สตริง my_customer เพื่อแสดง customerId ของบัญชี
ในฐานะผู้ดูแลระบบตัวแทนจำหน่าย ให้ใช้ customerId ของลูกค้าที่ซื้อจากตัวแทนจำหน่าย สำหรับ customerId ให้ใช้ชื่อโดเมนหลักของบัญชีในคำขอของการดำเนินการดึงข้อมูลผู้ใช้ทั้งหมดในโดเมน การตอบกลับที่ได้จะมีค่า customerId
orderByสตริงการค้นหาที่ไม่บังคับจะกำหนดว่าระบบจะจัดเรียงรายชื่อตามอีเมลหลัก นามสกุล หรือชื่อของผู้ใช้หรือไม่ เมื่อใช้ orderBy คุณยังใช้สตริงการค้นหา sortOrder เพื่อแสดงผลลัพธ์ในลำดับจากน้อยไปมากหรือมากไปน้อยได้ด้วย
query สตริงการค้นหาที่ไม่บังคับช่วยให้ค้นหาในช่องต่างๆ ในโปรไฟล์ผู้ใช้ได้ รวมถึงทั้งช่องหลักและช่องที่กำหนดเอง ดูตัวอย่างได้ที่ค้นหาผู้ใช้

ดูพร็อพเพอร์ตี้คำขอและการตอบกลับได้ในเอกสารอ้างอิง API

ในตัวอย่างนี้ ผู้ดูแลบัญชีกำลังขอให้ระบบแสดงผู้ใช้ทั้งหมดในบัญชีโดยมีรายการผู้ใช้ 1 รายการในแต่ละหน้าการตอบกลับ nextPageToken จะไปที่หน้าผลการค้นหาที่ตามมา

GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&maxResults=1

ในตัวอย่างนี้ ผู้ดูแลระบบตัวแทนจำหน่ายกำลังขอผู้ใช้ทั้งหมดในบัญชีที่ขายต่อซึ่งมีค่า customerId เป็น C03az79cb

GET https://admin.googleapis.com/admin/directory/v1/users?customer=C03az79cb&maxResults=1

การตอบสนองของ JSON

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

หมายเหตุ: เมื่อเรียกข้อมูลผู้ใช้บัญชีทั้งหมด ค่าของ lastLoginTime อาจไม่ถูกต้อง หากต้องการรับค่าที่ถูกต้องที่สุดสำหรับ lastLoginTime ให้เรียกข้อมูลผู้ใช้แทน

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "admin2@example.com",
   "name": {
    "givenName": "admin",
    "familyName": "two",
    "fullName": "admin two"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "2013-02-05T10:30:03.325Z",
   "creationTime": "2010-04-05T17:30:04.325Z",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "admin2@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
     "second_admin@example.com"
   ],
   "nonEditableAliases": [
     "another_admin@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "liz@example.com",
   "name": {
    "givenName": "Elizabeth",
    "familyName": "Smith",
    "fullName": "Elizabeth Smith"
   },
   "isAdmin": false,
   "isDelegatedAdmin": false,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": false,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "liz@example.com",
     "type": "home",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "bank"
    }
   ],
   "relations": [
    {
     "value": "liz",
     "type": "friend",
     "customType": ""
    }
   ],
   "aliases": [
    "lizsmith@example.com",
    "lsmith@example.com"
   ],
   "nonEditableAliases": [
    "liz@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "test3@example.com",
   "name": {
    "givenName": "Tester",
    "familyName": "Three",
    "fullName": "Tester Three"
   },
   "isAdmin": false,
   "isDelegatedAdmin": false,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "test@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "tester3@example.com"
   ],
   "nonEditableAliases": [
    "third@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "username": "work_admin@example.com",
   "name": {
    "givenName": "Admin",
    "familyName": "Work",
    "fullName": "Admin Work"
   },
   "isAdmin": true,
   "isDelegatedAdmin": true,
   "lastLoginTime": "1336509883546",
   "creationTime": "1404802800000",
   "agreedToTerms": true,
   "hashFunction": "SHA-1",
   "suspended": false,
   "changePasswordAtNextLogin": false,
   "ipWhitelisted": false,
   "emails": [
    {
     "address": "work_admin@example.com",
     "type": "work",
     "customType": "",
     "primary": true
    }
   ],
   "externalIds": [
    {
     "value": "employee number",
     "type": "custom",
     "customType": "office"
    }
   ],
   "aliases": [
    "my_alias@example.com"
   ],
   "nonEditableAliases": [
    "other_alias@test.com"
   ],
   "customerId": "C03az79cb",
   "orgUnitPath": "/",
   "isMailboxSetup": true,
   "includeInGlobalAddressList": true
  }
 ],
 "nextPageToken": "NNNNN"
}

ดึงข้อมูลผู้ใช้ที่ถูกลบไปล่าสุด

หากต้องการดึงข้อมูลผู้ใช้ทั้งหมดที่ถูกลบในช่วง 20 วันที่ผ่านมาออกจากบัญชีหรือโดเมนใดโดเมนหนึ่งของบัญชี ให้ใช้คำขอ GET ต่อไปนี้และรวมการให้สิทธิ์ที่อธิบายไว้ในคำขอสิทธิ์ หากต้องการยกเลิกการลบผู้ใช้ โปรดดูหัวข้อยกเลิกการลบผู้ใช้

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

GET https://admin.googleapis.com/admin/directory/v1/users
?domain=primary domain name&pageToken=token for next results page
&maxResults=max number of results per page
&showDeleted=true

หมายเหตุ: เมื่อใช้การตั้งค่า showDeleted=false คำขอจะแสดงการตอบกลับเดียวกันกับดึงข้อมูลผู้ใช้ทั้งหมดในโดเมน

หากบัญชีมีหลายโดเมน คุณสามารถดึงข้อมูลผู้ใช้ที่ถูกลบในช่วง 20 วันที่ผ่านมาออกจากทั้งบัญชีได้โดยใช้GETคำขอต่อไปนี้ ตัวอย่างนี้มีการขึ้นบรรทัดใหม่เพื่อให้ง่ายต่อการอ่านทำความเข้าใจ

GET https://admin.googleapis.com/admin/directory/v1/users
?customer=my_customer or customerId&pageToken=token for next results page
&maxResults=max number of results per page&showDeleted=true

customer สตริงการค้นหาคือค่า my_customer หรือ customerId
ในฐานะผู้ดูแลบัญชี ให้ใช้สตริง my_customer เพื่อแสดง customerId ของบัญชี
ในฐานะผู้ดูแลระบบตัวแทนจำหน่าย ให้ใช้ customerId ของลูกค้าที่ซื้อจากตัวแทนจำหน่าย สำหรับ customerId ให้ใช้ชื่อโดเมนหลักของบัญชีในคำขอของการดำเนินการดึงข้อมูลผู้ใช้ทั้งหมดในโดเมน การตอบกลับที่ได้จะมีค่า customerId

ดูพร็อพเพอร์ตี้คำขอและการตอบกลับได้ในเอกสารอ้างอิง API

หมายเหตุ: การตั้งค่า showDeleted=false จะทำให้คำขอแสดงคำตอบเดียวกันกับดึงข้อมูลผู้ใช้บัญชีทั้งหมด ดูพร็อพเพอร์ตี้คำขอและการตอบกลับของผู้ใช้ได้ที่เอกสารอ้างอิง API

ในตัวอย่างนี้ ผู้ดูแลบัญชีขอผู้ใช้ที่ถูกลบทั้งหมดในบัญชี

GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&showDeleted=true

การตอบสนองของ JSON

การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 200 นอกเหนือจากรหัสสถานะแล้ว การตอบกลับจะแสดงผู้ใช้บัญชีทั้งหมดที่ถูกลบภายใน 20 วันที่ผ่านมา

{
 "kind": "directory#users",
 "users": [
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "user1@example.com"
  },
  {
   "kind": "directory#user",
   "id": "the unique user id",
   "primaryEmail": "user3@example.com"
  }
 ],
 "nextPageToken": "token for next page of deleted users"
}

ดึงรูปภาพของผู้ใช้

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

GET https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

ในตัวอย่างนี้ ระบบจะแสดงรูปภาพล่าสุดของ liz@example.com

GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail

การตอบกลับ JSON

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

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "liz@example.com",
 "mimeType": "the photo mime type",
 "height": "the photo height in pixels",
 "width": "the photo width in pixels",
 "photoData": "web safe base64 encoded photo data"
}

การเข้ารหัส Web-safe base64 ของรูปภาพใน API จะคล้ายกับ RFC 4648 "base64url" ซึ่งหมายความว่า

ระบบจะแทนที่อักขระทับ (/) ด้วยอักขระขีดล่าง (_)
ระบบจะแทนที่อักขระเครื่องหมายบวก (+) ด้วยอักขระขีดกลาง (-)
อักขระเครื่องหมายเท่ากับ (=) จะถูกแทนที่ด้วยเครื่องหมายดอกจัน (*)
สำหรับการเพิ่มแพดดิง ระบบจะใช้อักขระจุด (.) แทนคำจำกัดความ baseURL ของ RFC-4648 ซึ่งใช้เครื่องหมายเท่ากับ (=) สำหรับการเพิ่มแพดดิง ซึ่งทำเพื่อลดความซับซ้อนในการแยกวิเคราะห์ URL
ไม่ว่ารูปภาพที่อัปโหลดจะมีขนาดเท่าใด API จะลดขนาดรูปภาพตามสัดส่วนเป็น 96x96 พิกเซล

หากต้องการสร้างลิงก์ที่เข้ากันได้จาก JavaScript Google Closure Library มีฟังก์ชันการเข้ารหัสและถอดรหัส Base64 ซึ่งเผยแพร่ภายใต้สัญญาอนุญาต Apache

ดึงข้อมูลผู้ใช้ในฐานะผู้ใช้ที่ไม่ใช่ผู้ดูแลระบบ

แม้ว่าผู้ดูแลระบบเท่านั้นที่จะแก้ไขบัญชีผู้ใช้ได้ แต่ผู้ใช้ทุกคนในโดเมนจะอ่านโปรไฟล์ผู้ใช้ได้ ผู้ใช้ที่ไม่ใช่ผู้ดูแลระบบสามารถส่งคำขอ users.get หรือ users.list โดยมี พารามิเตอร์ viewType เท่ากับ domain_public เพื่อดึงข้อมูลโปรไฟล์สาธารณะ ของผู้ใช้ ขอบเขต https://www.googleapis.com/auth/admin.directory.user.readonly เหมาะสำหรับกรณีการใช้งานนี้

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

อัปเดตรูปภาพของผู้ใช้

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

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

ในตัวอย่างนี้ รูปภาพของ liz@example.com จะได้รับการอัปเดต

PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail

{
"photoData": "web safe base64 encoded photo data"
}

เมื่ออัปเดตรูปภาพ API จะไม่สนใจ height และ width

การตอบกลับ JSON

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

{
 "kind": "directory#user#photo",
 "id": "the unique user id",
 "primaryEmail": "liz@example.com",
 "mimeType": "the photo mime type",
 "height": "the photo height in pixels",
 "width": "the photo width in pixels",
 "photoData": "web safe base64 encoded photo data"
}

ลบรูปภาพของผู้ใช้

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

DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail

เมื่อลบแล้ว ระบบจะไม่แสดงรูปภาพของผู้ใช้ ระบบจะแสดงภาพเงาแทนรูปภาพของผู้ใช้ในทุกที่ที่จำเป็น

ลบบัญชีผู้ใช้

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

DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey

ในตัวอย่างนี้ ระบบจะลบบัญชีผู้ใช้ liz@example.com

DELETE https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

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

สิ่งสำคัญที่ควรพิจารณาก่อนลบผู้ใช้มีดังนี้

ผู้ใช้ที่ถูกลบจะเข้าสู่ระบบไม่ได้อีกต่อไป
ดูข้อมูลเพิ่มเติมเกี่ยวกับการลบบัญชีผู้ใช้ได้ที่ศูนย์ช่วยเหลือด้านการดูแลระบบ

เลิกการลบบัญชีผู้ใช้

ผู้ใช้ที่ถูกลบในช่วง 20 วันที่ผ่านมาต้องมีคุณสมบัติตรงตามเงื่อนไขบางอย่างก่อนจึงจะกู้คืนบัญชีของผู้ใช้ได้

หากต้องการเลิกการลบบัญชีผู้ใช้ ให้ใช้คำขอ POST ต่อไปนี้และรวมการให้สิทธิ์ที่อธิบายไว้ในคำขอสิทธิ์ userKey คือidผู้ใช้ที่ไม่ซ้ำกันซึ่งพบในคำตอบของการดำเนินการดึงข้อมูลผู้ใช้ที่ถูกลบภายใน 20 วันที่ผ่านมา ใช้อีเมลหลักของผู้ใช้หรืออีเมลแทนของผู้ใช้ไม่ได้ใน userKey สำหรับการดำเนินการนี้ ดูพร็อพเพอร์ตี้คำขอและการตอบกลับได้ในเอกสารอ้างอิง API

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/undelete

ในตัวอย่างนี้ ระบบจะยกเลิกการลบผู้ใช้ liz@example.com ระบบจะกู้คืนพร็อพเพอร์ตี้บัญชีเดิมทั้งหมดของผู้ใช้รายนี้

POST https://admin.googleapis.com/admin/directory/v1/users/12309329403209438205/undelete

การตอบกลับที่สำเร็จจะแสดงเฉพาะรหัสสถานะ HTTP 204 หากต้องการดูบัญชีของผู้ใช้ที่ไม่ได้ลบ ให้ใช้การดำเนินการดึงข้อมูลผู้ใช้