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

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 ให้มาทำงานร่วมกันในไดรฟ์ ผู้ใช้เหล่านั้นจะได้รับบัญชีผู้เข้าชมในรูปแบบ traffic'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 รองรับความหมายของแพตช์ ดังนั้นคุณเพียงแค่ส่งช่องที่อัปเดตในคำขอเท่านั้น

null

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

ในตัวอย่างด้านล่าง 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' ซึ่งแปลว่า

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

หากคุณจำเป็นต้องสร้างลิงก์ที่เข้ากันได้จาก JavaScript ไลบรารีปิด 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 เท่านั้น หากต้องการดูบัญชีของผู้ใช้ที่ยกเลิกการลบ ให้ใช้การดำเนินการเรียกข้อมูลผู้ใช้