ข้ามไปยังเนื้อหาหลัก

การค้นหาผู้ใช้ขั้นสูง

ใช้ Management API โดยตรงเพื่อใช้เงื่อนไขการค้นหาผู้ใช้ขั้นสูง

ดำเนินการค้นหา​

ใช้ GET /api/users สำหรับการค้นหาผู้ใช้ โปรดทราบว่านี่คือ Management API ที่ต้องการการยืนยันตัวตนเช่นเดียวกับ API อื่น ๆ ดู การโต้ตอบกับ Management API สำหรับตัวอย่างการใช้งาน

ตัวอย่าง​

Request

curl \
  --location \
  --request GET \
  'http://<your-logto-endpoint>/api/users?search=%25alice%25'

Response

ผลลัพธ์เป็นอาเรย์ของเอนทิตี User

[
  {
    "id": "MgUzzDsyX0iB",
    "username": "alice_123",
    "primaryEmail": "alice@some.email.domain",
    "primaryPhone": null,
    "name": null,
    "avatar": null
    // ...
  }
]

พารามิเตอร์​

คำขอค้นหาประกอบด้วยคีย์พารามิเตอร์ดังนี้:

  • คำค้นหา: search, search.*
  • โหมดการค้นหาสำหรับแต่ละฟิลด์: mode, mode.* (ค่าเริ่มต้น 'like', ตัวเลือกที่ใช้ได้ ['exact', 'like', 'similar_to', 'posix'])
  • โหมดการเชื่อมโยง: joint หรือ jointMode (ค่าเริ่มต้น 'or', ตัวเลือกที่ใช้ได้ ['or', 'and'])
  • การแยกแยะตัวพิมพ์เล็ก/ใหญ่: isCaseSensitive (ค่าเริ่มต้น false)

API นี้รองรับ การแบ่งหน้า (pagination)

เราจะอธิบายแต่ละพารามิเตอร์ผ่านตัวอย่าง โดยพารามิเตอร์การค้นหาทั้งหมดจะถูกจัดรูปแบบเป็น constructor ของ URLSearchParams

คำเตือน:

โหมดการค้นหาเริ่มต้นคือ like ซึ่งใช้ Approximate string matching (“การค้นหาแบบคลุมเครือ” หรือ fuzzy search)

บันทึก:

โหมดการค้นหาแบบ fuzzy ทั้งหมดรองรับการจับคู่ค่าเดียวต่อฟิลด์เท่านั้น หากต้องการจับคู่หลายค่าต่อฟิลด์เดียว ให้ใช้โหมด "exact" ดูรายละเอียดที่ การจับคู่แบบ exact และการแยกแยะตัวพิมพ์เล็ก/ใหญ่

หากต้องการค้นหาแบบ fuzzy ในทุกฟิลด์ที่รองรับ เพียงระบุค่าให้กับคีย์ search จะใช้ ตัวดำเนินการ like เบื้องหลัง:

new URLSearchParams([['search', '%foo%']]);

การค้นหานี้จะวนลูปทุกฟิลด์ที่รองรับในการค้นหาผู้ใช้ ได้แก่ id, primaryEmail, primaryPhone, username, name

ระบุฟิลด์ที่ต้องการค้นหา​

หากต้องการจำกัดการค้นหาเฉพาะใน name เท่านั้น เช่น ต้องการค้นหาผู้ใช้ที่มี foo อยู่ในชื่อ ให้ใช้สัญลักษณ์ . เพื่อระบุฟิลด์:

new URLSearchParams([['search.name', '%foo%']]);

โปรดทราบว่าไม่รองรับฟิลด์ซ้อน เช่น search.name.first จะเกิดข้อผิดพลาด

คุณสามารถระบุหลายฟิลด์พร้อมกันได้เช่นกัน:

new URLSearchParams([
  ['search.name', '%foo%'],
  ['search.primaryEmail', '%@gmail.com'],
]);

หมายถึงค้นหาผู้ใช้ที่มี foo ในชื่อ หรือ อีเมลลงท้ายด้วย @gmail.com

เปลี่ยนโหมดการเชื่อมโยง (joint mode)​

หากต้องการให้ API ส่งคืนเฉพาะผลลัพธ์ที่ตรงกับเงื่อนไข ทุกข้อ ให้ตั้งค่า joint mode เป็น and:

new URLSearchParams([
  ['search.name', '%foo%'],
  ['search.primaryEmail', '%@gmail.com'],
  ['joint', 'and'],
]);

หมายถึงค้นหาผู้ใช้ที่มี foo ในชื่อ และ อีเมลลงท้ายด้วย @gmail.com

การจับคู่แบบ exact และการแยกแยะตัวพิมพ์เล็ก/ใหญ่​

สมมติว่าต้องการค้นหาผู้ใช้ที่ชื่อ "Alice" แบบตรงตัว ให้ตั้งค่า mode.name เป็น exact:

new URLSearchParams([
  ['search.name', 'Alice'],
  ['mode.name', 'exact'],
]);

คุณอาจพบว่าผลลัพธ์เหมือนกับการใช้โหมด like (ค่าเริ่มต้น) เทียบกับ exact ความแตกต่างคือโหมด exact ใช้ = ในการเปรียบเทียบ ขณะที่ like ใช้ like หรือ ilike โดยทฤษฎีแล้ว = จะมีประสิทธิภาพดีกว่า

นอกจากนี้ ในโหมด exact คุณสามารถส่งค่าหลายค่าเพื่อจับคู่ และค่าต่าง ๆ จะถูกเชื่อมด้วย or:

new URLSearchParams([
  ['search.name', 'Alice'],
  ['search.name', 'Bob'],
  ['mode.name', 'exact'],
]);

จะจับคู่ผู้ใช้ที่ชื่อ "Alice" หรือ "Bob"

โดยปกติการค้นหาจะไม่แยกแยะตัวพิมพ์เล็ก/ใหญ่ หากต้องการให้แยกแยะตัวพิมพ์ ให้ตั้งค่า isCaseSensitive เป็น true:

new URLSearchParams([
  ['search.name', 'Alice'],
  ['search.name', 'Bob'],
  ['mode.name', 'exact'],
  ['isCaseSensitive', 'true'],
]);

โปรดทราบว่า isCaseSensitive เป็นการตั้งค่าระดับ global ดังนั้น ทุกฟิลด์ จะถูกบังคับใช้ตามนี้

การใช้ Regular expression (RegEx)​

PostgreSQL รองรับ regular expression สองแบบ คือ similar to และ posix ตั้งค่า mode เป็น similar_to หรือ posix เพื่อค้นหาด้วย regular expression:

new URLSearchParams([
  ['search', '^T.?m Scot+$'],
  ['mode', 'posix'],
]);

หมายเหตุ โหมด similar_to ใช้ได้เฉพาะกับการค้นหาที่แยกแยะตัวพิมพ์เล็ก/ใหญ่เท่านั้น

การ override โหมดการจับคู่​

โดยปกติ คำค้นหาทั้งหมดจะสืบทอดโหมดการจับคู่จากการค้นหาหลัก:

new URLSearchParams([
  ['search', '^T.?m Scot+$'],
  ['mode', 'posix'],
  ['search.primaryEmail', 'tom%'], // โหมด Posix
  ['joint', 'and'],
]);

หากต้องการ override เฉพาะฟิลด์:

new URLSearchParams([
  ['search', '^T.?m Scot+$'],
  ['mode', 'posix'],
  ['search.primaryEmail', 'tom%'], // โหมด Like
  ['mode.primaryEmail', 'like'],
  ['search.phone', '0{3,}'], // โหมด Posix
  ['joint', 'and'],
]);

ค้นหาด้วย external identity​

หากต้องการค้นหาผู้ใช้ที่เชื่อมโยงกับ social หรือ enterprise SSO identity ให้ส่ง query parameter สามตัวนี้พร้อมกันเพื่อค้นหาแบบ exact:

  • identityType: social สำหรับตัวตนจากตัวเชื่อมต่อโซเชียล หรือ sso สำหรับ enterprise SSO identity
  • identityProvider: ตัวเชื่อมต่อเป้าหมายสำหรับ social identity (เช่น dingtalk) หรือผู้ออก (issuer) สำหรับ enterprise SSO identity
  • identityId: ตัวระบุผู้ใช้ที่ออกโดยผู้ให้บริการข้อมูลระบุตัวตนภายนอก
// ค้นหาผู้ใช้ที่เชื่อมโยงกับ social identity ของ DingTalk
new URLSearchParams([
  ['identityType', 'social'],
  ['identityProvider', 'dingtalk'],
  ['identityId', 'dingtalk-open-id'],
]);
// ค้นหาผู้ใช้ที่เชื่อมโยงกับ enterprise SSO identity
new URLSearchParams([
  ['identityType', 'sso'],
  ['identityProvider', 'https://example.com/issuer'],
  ['identityId', 'enterprise-user-id'],
]);

ตัวกรอง identity จะถูกนำไปใช้ร่วมกับตัวกรองการค้นหาอื่น ๆ ด้วยตรรกะ AND เช่น หากต้องการค้นหา identity พร้อมกับคำค้นหาเพิ่มเติม:

new URLSearchParams([
  ['identityType', 'social'],
  ['identityProvider', 'dingtalk'],
  ['identityId', 'dingtalk-open-id'],
  ['search', '%foo%'],
]);