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

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 รหัสผ่านต้องเป็นคีย์แฮชที่ถูกต้อง หากไม่ได้ระบุค่านี้ไว้ รหัสผ่านควรอยู่ในรูปแบบข้อความธรรมดาและมีอักขระ ASCII ระหว่าง 8-100 ตัว ดูข้อมูลเพิ่มเติมได้ที่การอ้างอิง 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) ดังนี้ 

{
 "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 นอกเหนือจากรหัสสถานะแล้ว การตอบสนองจะแสดงผู้ใช้ทั้งหมดในบัญชีนี้ด้วยดังนี้ 

{
 "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
 หากบัญชีมีโดเมนหลายรายการ คุณสามารถเรียกข้อมูลผู้ใช้ที่ถูกลบในช่วง 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

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

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

การเข้ารหัส base64 ที่ปลอดภัยบนเว็บของ API สำหรับรูปภาพจะคล้ายกับ RFC 4648 "base64url" ซึ่งหมายความว่า

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

หากต้องการสร้างลิงก์ที่เข้ากันได้จาก JavaScript ไลบรารี Closure ของ Google มีฟังก์ชันการเข้ารหัสและถอดรหัส 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 หากต้องการดูบัญชีของผู้ใช้ที่ไม่ได้ลบ ให้ใช้การดำเนินการเรียกข้อมูลผู้ใช้