جستجو برای کاربران

شما می‌توانید با استفاده از متد users.list() از Directory API، کاربرانی را که با ویژگی‌های خاصی مطابقت دارند، جستجو کنید. این متد پارامتر query را می‌پذیرد که یک query جستجو است که یک یا چند عبارت جستجو را ترکیب می‌کند. هر عبارت جستجو از 3 بخش تشکیل شده است:

میدان

ویژگی کاربر که جستجو می‌شود. برای مثال، givenName .

اپراتور

آزمایشی که روی داده‌ها انجام می‌شود تا تطابقی پیدا شود. برای مثال، عملگر : بررسی می‌کند که آیا یک ویژگی متنی حاوی مقداری است یا خیر.

ارزش

محتوای ویژگی مورد آزمایش. برای مثال، Jane .

برای جستجوی چندین فیلد در یک پرس و جو، هر عبارت جستجو را با یک فاصله از هم جدا کنید. این عملیات یک AND ضمنی است.

توجه: اکثر داده‌های کاربر ظرف ۱ ساعت به‌روزرسانی می‌شوند، با این حال، ممکن است تا ۳۶ ساعت طول بکشد تا داده‌های جدید در تمام نتایج جستجو منعکس شوند.

فیلدها

میدان	نوع مقدار	اپراتورها	توضیحات
هیچ کدام مشخص نشده است	رشته		با مقدار موجود در givenName ، familyName یا email مقایسه کنید.
name	رشته	=, :	مقدار الحاقی givenName و familyName .
email	رشته	= ، : ، :{PREFIX}*	آدرس‌های ایمیل کاربر، شامل نام‌های مستعار.
givenName	رشته	= ، : ، :{PREFIX}*	نام یا نام کوچک کاربر.
familyName	رشته	= ، : ، :{PREFIX}*	نام خانوادگی یا فامیلی کاربر.
isAdmin	بولی	=	اینکه آیا یک کاربر دارای امتیازات فوق مدیر (super administrator) است یا خیر.
isDelegatedAdmin	بولی	=	اینکه آیا به کاربر اختیارات مدیریتی تفویض شده است یا خیر.
isSuspended	بولی	=	اینکه آیا حساب کاربری به حالت تعلیق درآمده است یا خیر.
isArchived	بولی	=	اینکه آیا حساب کاربری بایگانی شده است یا خیر.
im	رشته	=, :	شناسه شبکه IM.
externalId	رشته	=, :	مقدار شناسه خارجی.
manager	رشته	=	آدرس ایمیل مدیر کاربر، چه مستقیماً و چه از طریق زنجیره مدیریتی بالاتر.
managerId	رشته	=	شناسه مدیر یک کاربر، چه مستقیماً و چه از طریق زنجیره مدیریتی بالاتر.
directManager	رشته	=	آدرس ایمیل مدیر مستقیم کاربر.
directManagerId	رشته	=	شناسه مدیر مستقیم کاربر.
address	رشته	:	با همه فیلدهای آدرس مطابقت دارد.
addressPoBox	رشته	=, :	یک صندوق پستی.
addressExtended	رشته	=, :	یک آدرس توسعه‌یافته، مانند آدرسی که شامل یک زیرمنطقه باشد.
addressStreet	رشته	=, :	آدرس خیابان.
addressLocality	رشته	=, :	شهر یا شهرستان محل آدرس.
addressRegion	رشته	=, :	استان یا ایالت به اختصار.
addressPostalCode	رشته	=, :	کد پستی یا پستی.
addressCountry	رشته	=, :	یک کشور.
orgName	رشته	=, :	نام یک سازمان.
orgTitle	رشته	=, :	عنوان کاربر در سازمان.
orgDepartment	رشته	=, :	یک بخش در داخل سازمان.
orgDescription	رشته	=, :	توصیف یک سازمان.
orgCostCenter	رشته	=, :	مرکز هزینه یک سازمان.
phone	رشته	=	شماره تلفن یک کاربر.
orgUnitPath	رشته	=	مسیر کامل یک واحد سازمانی. این با تمام زنجیره‌های واحد سازمانی تحت هدف مطابقت دارد. برای مثال، 'orgUnitPath=/' تمام کاربران موجود در سازمان را برمی‌گرداند. این فیلد فقط زمانی قابل استفاده است که viewType=admin_view .
isEnrolledIn2Sv	بولی	=	اینکه آیا کاربر در تأیید هویت دو مرحله‌ای ثبت‌نام کرده است یا خیر.
isEnforcedIn2Sv	بولی	=	اینکه آیا تأیید هویت دو مرحله‌ای برای کاربر فعال شده است یا خیر.
schemaName.fieldName	?	?	یک ویژگی کاربر سفارشی ، که توسط طرحواره و نام فیلد آن ارجاع داده می‌شود. ویژگی indexed property) فیلد باید روی true تنظیم شود.

انواع مقادیر

نوع مقدار	نوع فیلد طرحواره معادل	یادداشت‌ها
رشته	STRING ، EMAIL ، PHONE	اگر عبارت جستجو شامل فضای خالی است، آن را با علامت نقل قول تکی ' احاطه کنید. در عبارات جستجو شده با علامت نقل قول تکی \' ، مثلاً 'Valentine\'s Day' از علامت نقل قول تکی 'Escape' استفاده کنید.
بولی	BOOL	باید مقدار true یا false داشته باشد. فقط از عملگر = پشتیبانی می‌کند.
شماره	INT64 ، DOUBLE	باید از نقطه به عنوان جداکننده اعشاری استفاده شود و از جداکننده هزارگان استفاده نشود، برای مثال 150430.25 .
تاریخ	DATE	با فرمت YYYY-MM-DD مشخص شده است، برای مثال 2001-02-15 .

اپراتورها

اپراتور	انواع مقادیر پشتیبانی شده	یادداشت‌ها
=	رشته، بولی، عدد، تاریخ	فیلد و مقدار دقیقاً با هم مطابقت دارند. برای مثال، givenName=Jane با همه کاربرانی که ویژگی givenName "Jane" است مطابقت دارد، اما با "Jane Ann" مطابقت ندارد. این ویژگی در اکثر فیلدهای رشته‌ای پشتیبانی می‌شود ( به بالا مراجعه کنید ).
:	رشته	این فیلد شامل تمام کلمات درون مقدار به ترتیب است. برای مثال، یک پرس‌وجو با givenName:Jane کاربرانی را که مقادیر givenName آنها "Jane" و "Jane Ann" است، اما "Janet" ندارند، تطبیق می‌دهد. یک پرس‌وجوی چند کلمه‌ای برای 'givenName:Mary Ann' مقادیر "Mary Ann Evans" و "Sarah Mary Ann" را تطبیق می‌دهد اما "Ann Mary" تطبیق نمی‌دهد. در اکثر فیلدهای رشته‌ای پشتیبانی می‌شود ( به بالا مراجعه کنید ).
:{PREFIX}*	رشته	فیلد با مقدار شروع می‌شود. برای مثال، یک پرس‌وجو با givenName:Jane* کاربرانی را که مقادیر givenName آنها "Jane" ، "Jane Ann" و "Janet" است، اما "Sarah Jane" را ندارند، با هم تطبیق می‌دهد. فقط در مجموعه محدودی از فیلدهای رشته‌ای پشتیبانی می‌شود ( به بالا مراجعه کنید ). در ویژگی‌های سفارشی پشتیبانی نمی‌شود.
:[{MIN},{MAX}]	شماره، تاریخ	فیلد در یک محدوده قرار دارد. برای تطبیق، مقدار فیلد باید بزرگتر یا مساوی {MIN} و کوچکتر از {MAX} باشد. ویژگی‌های عددی سفارشی باید یک numericIndexingSpec را مشخص کنند تا از این عملگر پشتیبانی کنند.
>	شماره، تاریخ	فیلد بزرگتر از مقدار است. ویژگی‌های عددی سفارشی باید یک numericIndexingSpec را مشخص کنند تا از این عملگر پشتیبانی کنند.
>=	شماره، تاریخ	فیلد بزرگتر یا مساوی مقدار است. ویژگی‌های عددی سفارشی باید یک numericIndexingSpec را مشخص کنند تا از این عملگر پشتیبانی کنند.
<	شماره، تاریخ	فیلد کوچکتر از مقدار است. ویژگی‌های عددی سفارشی باید یک numericIndexingSpec را مشخص کنند تا از این عملگر پشتیبانی کنند.
<=	شماره، تاریخ	فیلد کوچکتر یا مساوی مقدار است. ویژگی‌های عددی سفارشی باید یک numericIndexingSpec را مشخص کنند تا از این عملگر پشتیبانی کنند.

نکته: استفاده از عملگر محدوده :[min,max] با اتصال >=min AND <max برای فیلدهای چند مقداری متفاوت است. برای مثال، اگر یک فیلد چند مقداری با دو مقدار 10 و 20 وجود داشته باشد، با field>12 field<15 مطابقت دارد زیرا حداقل یک مقدار با هر عبارت مطابقت دارد اما field:[12,15] ندارد زیرا هیچ مقدار واحدی در این محدوده وجود ندارد.

مثال‌ها

همه پرس و جوها از متد users.list استفاده می‌کنند که درخواست HTTP مشابه زیر دارد (برای خوانایی بیشتر، از خطوط جدید استفاده می‌شود):

GET https://admin.googleapis.com/admin/directory/v1/users?domain=DOMAIN_NAME&query=QUERY_PARAMETERS

توجه: پارامترهای query باید به صورت URL-encode شده باشند. برای مثال، query=givenName:Jane* به صورت query=givenName%3AJane* به صورت URL-encode شده است. تمام مثال‌های این صفحه پارامترهای query بدون کد را نشان می‌دهند. کتابخانه‌های کلاینت به طور خودکار این کدگذاری URL را مدیریت می‌کنند.

جستجوی کاربر بر اساس نام

فیلد پرس‌وجوی name ، مقدار به هم پیوسته‌ی givenName و familyName را بررسی می‌کند. پرس‌وجوی name='Jane' برای کاربری با givenName='Jane' و familyName='Smith' هیچ نتیجه‌ای برنمی‌گرداند.

name='Jane Smith'

جستجوی کاربران با givenName یا familyName که حاوی یک مقدار است

name:'Jane'

جستجوی کاربرانی که با پیشوند ایمیل مطابقت دارند

email:admin*

جستجوی همه مدیران ارشد

isAdmin=true

جستجوی کاربرانی با orgTitles حاوی «مدیر»

orgTitle:Manager

جستجوی کاربرانی که در زنجیره گزارش‌دهی خود یک مدیر مشترک دارند

manager='[e-mail]'

جستجوی کاربرانی با مدیر مستقیم یکسان

directManager='[e-mail]'

جستجوی کاربران در یک کشور خاص

addressCountry='Sweden'

جستجوی کاربران در یک سازمان خاص

orgName='Human Resources'

جستجوی مدیران در یک سازمان خاص

orgName=Engineering orgTitle:Manager

جستجوی ویژگی‌های سفارشی کاربر

نکته: مثال‌های زیر یک طرحواره کاربری به نام EmploymentData با فیلدهای projects ، location و jobLevel را فرض می‌کنند.

جستجوی تمام کارمندانی که روی یک پروژه خاص کار می‌کنند

EmploymentData.projects:'GeneGnomes'

جستجوی همه کارمندان در یک مکان خاص

EmploymentData.location='Atlanta'

جستجوی همه کارمندان بالاتر از سطح شغلی ۷

EmploymentData.jobLevel>=7

جستجوی تمام کارمندانی که سطح شغلی آنها >= 5 و < 8 است

EmploymentData.jobLevel:[5,8]

جستجوی تمام کارمندانی که در تأیید هویت دو مرحله‌ای (2-Step vVerification) ثبت‌نام کرده‌اند

isEnrolledIn2Sv=true

جستجوی تمام کارمندانی که تأیید هویت دو مرحله‌ای برایشان اجباری شده است

isEnforcedIn2Sv=true