فیلترها

Ad Manager API از فیلتر کردن روش‌های List پشتیبانی می‌کند. نحو رشته فیلتر به طور رسمی در گرامر EBNF تعریف شده است.

برای شروع، در اینجا چند نمونه از موارد استفاده رایج آورده شده است.

مثال	معنی
`orders.updateTime > "2024-01-01T00:00:00-5:00"`	سفارش‌ها را با `updateTime` پس از ۱ ژانویه ۲۰۲۴ در منطقه زمانی استاندارد شرقی فهرست می‌کند
`lineItems.targeting.geoTargeting.targetedGeoIds:2840`	موارد خط را با هدف جغرافیایی که شامل ایالات متحده است (شناسه هدف جغرافیایی `2480` ) فهرست می کند.
`lineItems.displayName = "*_interstitial"`	موارد خطی را فهرست می کند که نام نمایشی دارند که با رشته `_interstitial` ختم می شود
`orders.displayName = "video"`	سفارش‌هایی را فهرست می‌کند که نام نمایشی حاوی `video` رشته‌ای دارند
`displayName:"video"`	سفارشاتی را فهرست می‌کند که نام نمایشی حاوی `video` رشته‌ای دارند (سینتکس جایگزین)

تحت اللفظی

مقدار واقعی کلمه (مثال: 42 ، Hugo ) مقداری است که باید با آن مطابقت داده شود. لفظ هایی که به تنهایی ظاهر می شوند با تمام فیلدهای پشتیبانی شده در یک منبع مطابقت فازی دارند. منابع مستند می کنند که کدام فیلدها برای تطبیق در روش list در نظر گرفته می شوند. این ویژگی با جستجوی جهانی در رابط کاربری Ad Manager قابل مقایسه است اما در محدوده یک نوع منبع واحد قرار دارد.

حروف رشته‌ای حاوی فاصله باید در گیومه‌های دوتایی پیچیده شوند (مثال: "Foo bar" ). نقل قول های تک را نمی توان برای بسته بندی حرف های رشته ای استفاده کرد.

عملگرهای منطقی

Ad Manager API از عملگرهای باینری AND و OR پشتیبانی می کند.

اپراتور	مثال	معنی
`AND`	`a AND b`	اگر `a` و `b` درست باشند درست است.
`OR`	`a OR b OR c`	اگر هر یک از `a` , `b` , `c` درست باشد درست است.

عملگرهای نفی

Ad Manager API عملگرهای unary NOT و - را ارائه می دهد. اینها را می توان به جای هم استفاده کرد.

اپراتور	مثال	معنی
`NOT`	`NOT a`	اگر `a` درست نباشد درست است.
`-`	`-a`	اگر `a` درست نباشد درست است.

عملگرهای مقایسه

Ad Manager از عملگرهای مقایسه باینری = , != , < , > , <= و >= برای رشته ها، عددی، مهر زمانی و مدت زمان پشتیبانی می کند.

اپراتور	مثال	معنی
`=`	`a = true`	درست است اگر `a` درست باشد.
`!=`	`a != 42`	درست است مگر اینکه `a` برابر 42 باشد.
`<`	`a < 42`	اگر `a` مقدار عددی کمتر از 42 باشد درست است.
`>`	`a > "foo"`	درست است اگر `a` از نظر لغوی بعد از "foo" مرتب شود.
`<=`	`a <= "foo"`	درست است اگر `a` «فو» یا از نظر لغوی قبل از آن باشد.
`>=`	`a >= 42`	درست است اگر `a` مقدار عددی 42 یا بالاتر باشد.

از آنجایی که فیلترها به عنوان رشته های پرس و جو پذیرفته می شوند، تبدیل نوع انجام می شود تا رشته به مقدار قوی تایپ شده مناسب ترجمه شود:

رشته ها انتظار مظهر مضاعف دارند. مثال: "Foo bar" .
Enum ها انتظار دارند نمایش رشته enum (حساس به حروف کوچک و بزرگ) باشد.
Booleans انتظار مقادیر واقعی true و false را دارند.
اعداد انتظار دارند نمایش عدد صحیح یا شناور استاندارد باشند. برای شناورها، توان ها پشتیبانی می شوند. مثال: 2.997e9 .
مدت زمان ها انتظار دارند یک نمایش عددی به دنبال پسوند s (برای چند ثانیه) وجود داشته باشد. مثال‌ها: "20s" ، "1.2s" .
مُهر زمان انتظار یک رشته فرمت RFC-3339 را دارد. مثال: "2012-04-21T11:30:00-04:00" . افست های UTC پشتیبانی می شوند.

عجایب

هنگام مقایسه رشته‌ها برای برابری، Ad Manager API از حروف عام با استفاده از کاراکتر * پشتیبانی می‌کند.

مثال	معنی
`a = "*.foo"`	درست است اگر `a` با ".foo" ختم شود .

اپراتور پیمایش

Ad Manager API از . عملگر، که پیمایش را از طریق یک پیام، نقشه یا ساختار نشان می دهد.

مثال	معنی
`ab = true`	اگر `a` دارای یک فیلد `b` باشد درست است.
`ab > 42`	درست است اگر `a` دارای یک فیلد عددی `b` بزرگتر از 42 باشد.
`abc = "foo"`	درست است اگر `ab` دارای یک فیلد رشته `c` باشد که "foo" است.

پیمایش با استفاده از نام فیلدهای منبع نوشته می شود. سرویس‌های فردی می‌توانند زیر مجموعه‌ای از فیلدها را مشخص کنند که برای پیمایش پشتیبانی می‌شوند.

دارای اپراتور

Ad Manager API از عملگر : پشتیبانی می کند که به معنای "داراست". با مجموعه ها (فیلدها یا نقشه های تکراری)، پیام ها و رشته ها قابل استفاده است و در هر مورد کمی متفاوت رفتار می کند.

فیلدهای رشته را پرس و جو می کند تا ببیند آیا رشته دارای زیررشته منطبق است یا خیر:

مثال	معنی
`r.displayName:"_250x250"`	درست است اگر فیلد String `r.displayName` حاوی زیررشته `_250x250` باشد.

فیلدهای تکراری پرس و جو کنید تا ببینید آیا ساختار تکرار شده حاوی عنصر منطبق است یا خیر:

مثال	معنی
`r:42`	درست است اگر `r` حاوی 42 باشد.
`r.foo:42`	اگر `r` حاوی عنصر `e` باشد درست است که `e.foo = 42` باشد.

نقشه‌ها، ساختارها و پیام‌ها می‌توانند وجود یک فیلد در نقشه یا یک مقدار خاص را پرس و جو کنند:

مثال	معنی
`m:foo`	درست است اگر `m` حاوی کلید "foo" باشد.
`m.foo:*`	درست است اگر `m` حاوی کلید "foo" باشد.
`m.foo:42`	درست است اگر `m.foo` 42 باشد.

هنگام عبور از پیام ها، یک فیلد تنها در صورتی وجود دارد که دارای مقدار غیر پیش فرض باشد.

محدودیت ها

سرویس‌های فردی می‌توانند ساختار یا محدودیت‌های بیشتری را برای درخواست‌های فیلتر علاوه بر آنچه در اینجا تعریف شده است، مشخص کنند.

سفارش دهید

Ad Manager API از روش‌های سفارش در List پشتیبانی می‌کند. نحو فیلدهای orderBy فهرستی از نام فیلدها است که با کاما از هم جدا شده اند. به عنوان مثال: "foo,bar" .

ترتیب مرتب سازی پیش فرض صعودی است. برای تعیین ترتیب نزولی برای یک فیلد، پسوند " desc" را اضافه کنید. به عنوان مثال: "foo desc, bar" .

کاراکترهای فضای اضافی در نحو نادیده گرفته می شوند. مقادیر "foo, bar desc" ، " foo , bar desc " و "foo,bar desc" همگی معادل هستند.

زیر فیلدها با عملگر پیمایش مشخص می شوند. به عنوان مثال: foo.bar یا address.street .