Directory API มีวิธีการแบบเป็นโปรแกรมสำหรับการสร้าง อัปเดต และ ลบผู้ใช้ นอกจากนี้ คุณยังดูข้อมูลเกี่ยวกับผู้ใช้แต่ละรายหรือรายชื่อผู้ใช้ที่ตรงตามเกณฑ์ที่ระบุได้ด้วย ตัวอย่างการดำเนินการพื้นฐานบางอย่างของผู้ใช้มีดังนี้
สร้างบัญชีผู้ใช้
คุณเพิ่มบัญชีผู้ใช้ลงในโดเมนของบัญชี Google Workspace ได้ ก่อนเพิ่มบัญชีผู้ใช้ ให้ยืนยันการเป็นเจ้าของโดเมน
หากอัปเกรดบัญชี Gmail ส่วนตัวเป็นบัญชีอีเมลธุรกิจ โดยใช้ชื่อโดเมนของคุณเอง คุณจะสร้างบัญชีผู้ใช้ใหม่ไม่ได้จนกว่าจะปลดล็อก การตั้งค่า Google Workspace เพิ่มเติม โปรดดูรายละเอียดที่หัวข้อ อัปเดตบัญชีอีเมลธุรกิจของ Google Workspace
หากต้องการสร้างบัญชีผู้ใช้โดยใช้โดเมนใดโดเมนหนึ่ง ให้ใช้คำขอ 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
ผู้ใช้ต้องมีอยู่ก่อนจึงจะกำหนดให้เป็นผู้ดูแลระบบขั้นสูงได้ การดำเนินการนี้ทำได้โดยผู้ดูแลระบบขั้นสูงของบัญชีเท่านั้น ผู้ดูแลระบบที่ได้รับมอบสิทธิ์จะเลื่อนระดับผู้ใช้ให้มีบทบาทเป็นผู้ดูแลระบบไม่ได้ ดูข้อมูล เกี่ยวกับการใช้คอนโซลผู้ดูแลระบบของ Google เพื่อเปลี่ยนบทบาทของผู้ดูแลระบบได้ที่ศูนย์ช่วยเหลือด้านการดูแลระบบ
คำขอ 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" ซึ่งหมายความว่า
- ระบบจะแทนที่อักขระทับ (/) ด้วยอักขระขีดล่าง (_)
- ระบบจะแทนที่อักขระเครื่องหมายบวก (+) ด้วยอักขระขีดกลาง (-)
- อักขระเครื่องหมายเท่ากับ (=) จะถูกแทนที่ด้วยเครื่องหมายดอกจัน (*)
- สำหรับการเว้นวรรค จะใช้เครื่องหมายจุด (.) แทนคำจำกัดความ RFC-4648 baseURL ซึ่งใช้เครื่องหมายเท่ากับ (=) สำหรับการเว้นวรรค การดำเนินการนี้มีขึ้นเพื่อ ลดความซับซ้อนในการแยกวิเคราะห์ 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 หากต้องการดูบัญชีของผู้ใช้ที่ยกเลิกการลบ ให้ใช้การดำเนินการเรียกข้อมูลผู้ใช้