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

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 ได้ซื้อใบอนุญาตอีเมลไว้ ระบบจะมอบหมายกล่องจดหมายให้กับบัญชีผู้ใช้ใหม่โดยอัตโนมัติ งานนี้อาจใช้เวลา 2-3 นาทีจึงจะเสร็จสมบูรณ์และเปิดใช้งาน
• บริการ API จะไม่สนใจการแก้ไขช่องแบบอ่านอย่างเดียวในคำขอ เช่น isAdmin
• จำนวนโดเมนสูงสุดที่อนุญาตในบัญชีคือ 600 รายการ (โดเมนหลัก 1 รายการ + โดเมนเพิ่มเติม 599 รายการ)
• ถ้าไม่ได้มอบหมายผู้ใช้ให้กับหน่วยขององค์กรหนึ่งๆ เมื่อสร้างบัญชีผู้ใช้ บัญชีจะอยู่ในหน่วยขององค์กรระดับบนสุด โดยหน่วยขององค์กรของผู้ใช้จะเป็นตัวกำหนดบริการ Google Workspace ที่ผู้ใช้มีสิทธิ์เข้าถึง หากย้ายผู้ใช้ไปยังองค์กรใหม่ สิทธิ์เข้าถึงของผู้ใช้จะเปลี่ยนแปลงไป สำหรับข้อมูลเพิ่มเติมเกี่ยวกับโครงสร้างองค์กร โปรดดูที่ศูนย์ช่วยเหลือการดูแลระบบ โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับการย้ายผู้ใช้ไปยังองค์กรอื่นที่หัวข้ออัปเดตผู้ใช้
• ต้องมี password สำหรับบัญชีผู้ใช้ใหม่ หากระบุ hashFunction รหัสผ่านต้องเป็นคีย์แฮชที่ถูกต้อง หากไม่ได้ระบุ รหัสผ่านควรเป็นข้อความธรรมดาและมีอักขระ ASCII ระหว่าง 8-100 ตัว สำหรับข้อมูลเพิ่มเติม โปรดดูที่เอกสารอ้างอิง API
• สำหรับผู้ใช้แพ็กเกจแบบยืดหยุ่นสำหรับ Google Workspace การสร้างผู้ใช้โดยใช้ API นี้จะส่งผลทางการเงินและจะมีการเรียกเก็บเงินไปยังบัญชีสำหรับการเรียกเก็บเงินของลูกค้า สำหรับข้อมูลเพิ่มเติม โปรดดูข้อมูลสำหรับการเรียกเก็บเงิน API
• บัญชี Google Workspace จะมีโดเมนใดก็ได้ ในบัญชีของหลายโดเมน ผู้ใช้ในโดเมนหนึ่งสามารถแชร์บริการกับผู้ใช้ในโดเมนบัญชีอื่นๆ ได้ โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับผู้ใช้ในโดเมนหลายโดเมนที่หัวข้อข้อมูลหลายโดเมนของ API
• เนื่องจากอาจมีบัญชีที่ทับซ้อนกัน ตรวจสอบว่าบุคคลที่คุณต้องการเพิ่มมีบัญชี Google อยู่แล้วหรือไม่ จากนั้นทำตามขั้นตอนเพื่อหลีกเลี่ยงการทับซ้อนกับบัญชีเหล่านั้น โปรดดูหัวข้อค้นหาและแก้ไขบัญชีที่ทับซ้อนกัน
• อาจมีบัญชีผู้เข้าชม หากผู้ใช้เชิญบุคคลภายนอกองค์กรที่ไม่มีบัญชี Google มาทำงานร่วมกันในไดรฟ์ ผู้ใช้เหล่านั้นจะได้รับบัญชีผู้เข้าชมในรูปแบบ buyer'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 จะดึงข้อมูลภาพขนาดย่อของรูปภาพหนึ่งรูป ซึ่งเป็นรูปโปรไฟล์ล่าสุดของ 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" ซึ่งแปลว่า

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

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