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": "[email protected]", "name": { "givenName": "Elizabeth", "familyName": "Smith" }, "suspended": false, "password": "new user password", "hashFunction": "SHA-1", "changePasswordAtNextLogin": false, "ipWhitelisted": false, "ims": [ { "type": "work", "protocol": "gtalk", "im": "[email protected]", "primary": true } ], "emails": [ { "address": "[email protected]", "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": "[email protected]",
"type": "work",
"primary": true
}
}
คําขอด้านล่างจะอัปเดต givenName
จาก "Elizabeth" เป็น "Liz" และเพิ่มอีเมลบ้านด้วย โปรดทราบว่าคุณจะต้องระบุอีเมลทั้ง 2 รายการเนื่องจากช่องนี้เป็นอาร์เรย์
PUT https://admin.googleapis.com/admin/directory/v1/users/[email protected]
{
"name": {
"givenName": "Liz",
},
"emails": [
{
"address": "[email protected]",
"type": "work",
"primary": true
},
{
"address": "[email protected]",
"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
เป็น [email protected] ได้กลายเป็นผู้ดูแลระบบขั้นสูง
POST https://admin.googleapis.com/admin/directory/v1/users/[email protected]/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
ตัวอย่างนี้จะแสดงผลพร็อพเพอร์ตี้บัญชีผู้ใช้สำหรับผู้ใช้ที่มีอีเมลหลักหรืออีเมลแทนคือ [email protected]
GET https://admin.googleapis.com/admin/directory/v1/users/[email protected]
การตอบสนองของ JSON
การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 200 นอกเหนือจากรหัสสถานะแล้ว การตอบสนองจะแสดงพร็อพเพอร์ตี้สำหรับบัญชีผู้ใช้ด้วย
{ "kind": "directory#user", "id": "the unique user id", "primaryEmail": "[email protected]", "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": "[email protected]", "primary": true } ], "emails": [ { "address": "[email protected]", "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": [ "[email protected]", "[email protected]" ], "nonEditableAliases": [ "[email protected]" ], "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": "[email protected]", "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": "[email protected]", "primary": true } ], "emails": [ { "address": "[email protected]", "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": [ "[email protected]", "[email protected]" ], "nonEditableAliases": [ "[email protected]" ], "customerId": "C03az79cb", "orgUnitPath": "corp/engineering", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "user unique ID", "primaryEmail": "[email protected]", "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": "[email protected]", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "contractor license number", "type": "custom", "customType": "work" } ], "aliases": [ "[email protected]" ], "nonEditableAliases": [ "[email protected]" ], "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": "[email protected]", "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": "[email protected]", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "aliases": [ "[email protected]" ], "nonEditableAliases": [ "[email protected]" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "the unique user id", "username": "[email protected]", "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": "[email protected]", "type": "home", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "bank" } ], "relations": [ { "value": "liz", "type": "friend", "customType": "" } ], "aliases": [ "[email protected]", "[email protected]" ], "nonEditableAliases": [ "[email protected]" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "the unique user id", "username": "[email protected]", "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": "[email protected]", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "aliases": [ "[email protected]" ], "nonEditableAliases": [ "[email protected]" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "the unique user id", "username": "[email protected]", "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": "[email protected]", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "aliases": [ "[email protected]" ], "nonEditableAliases": [ "[email protected]" ], "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
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": "[email protected]" }, { "kind": "directory#user", "id": "the unique user id", "primaryEmail": "[email protected]" } ], "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
ในตัวอย่างนี้ ระบบจะแสดงรูปภาพล่าสุดของ [email protected]
GET https://admin.googleapis.com/admin/directory/v1/users/[email protected]/photos/thumbnail
การตอบกลับ JSON
การตอบกลับที่สำเร็จจะแสดงรหัสสถานะ HTTP 200
{ "kind": "directory#user#photo", "id": "the unique user id", "primaryEmail": "[email protected]", "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
ในตัวอย่างนี้ ระบบจะอัปเดตรูปภาพ [email protected] ดังนี้
PUT https://admin.googleapis.com/admin/directory/v1/users/[email protected]/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": "[email protected]", "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
ในตัวอย่างนี้ ระบบจะลบบัญชีผู้ใช้ [email protected]
DELETE https://admin.googleapis.com/admin/directory/v1/users/[email protected]
การตอบกลับที่สำเร็จจะแสดงเฉพาะรหัสสถานะ HTTP 200
สิ่งสำคัญที่ควรพิจารณาก่อนลบผู้ใช้
- ผู้ใช้ที่ถูกลบจะเข้าสู่ระบบไม่ได้อีกต่อไป
- ดูข้อมูลเพิ่มเติมเกี่ยวกับการลบบัญชีผู้ใช้ได้ที่ศูนย์ช่วยเหลือด้านการดําเนินการ
ยกเลิกการลบบัญชีผู้ใช้
ผู้ใช้ที่ถูกลบในช่วง 20 วันที่ผ่านมาต้องมีคุณสมบัติตรงตามเงื่อนไขบางอย่างก่อนจึงจะกู้คืนบัญชีของผู้ใช้ได้
หากต้องการยกเลิกการลบบัญชีผู้ใช้ ให้ใช้คำขอ POST
ต่อไปนี้และรวมการให้สิทธิ์ที่อธิบายไว้ในคำขอสิทธิ์ userKey
คือผู้ใช้ที่ไม่ซ้ำกัน id
ที่พบในการตอบกลับของการดำเนินการเรียกข้อมูลผู้ใช้ที่ถูกลบในช่วง 20 วันที่ผ่านมา ใช้อีเมลหลักของผู้ใช้หรืออีเมลแทนของผู้ใช้รายการใดรายการหนึ่งไม่ได้ใน userKey
สำหรับการดำเนินการนี้ ดูพร็อพเพอร์ตี้คำขอและการตอบกลับได้ในเอกสารอ้างอิง API
POST https://admin.googleapis.com/admin/directory/v1/users/userKey/undelete
ในตัวอย่างนี้ ระบบจะยกเลิกการลบผู้ใช้ [email protected] ระบบจะกู้คืนพร็อพเพอร์ตี้บัญชีทั้งหมดของผู้ใช้รายนี้
POST https://admin.googleapis.com/admin/directory/v1/users/12309329403209438205/undelete
การตอบกลับที่สำเร็จจะแสดงเฉพาะรหัสสถานะ HTTP 204 หากต้องการดูบัญชีของผู้ใช้ที่ไม่ได้ลบ ให้ใช้การดำเนินการเรียกข้อมูลผู้ใช้