صفحه بندی

رابط برنامه‌نویسی کاربردی مدیریت تبلیغات (Ad Manager API) مجموعه‌ای از داده‌ها را ارائه می‌دهد که معمولاً در قالب متدهای List ارائه می‌شوند. این مجموعه‌ها می‌توانند به صورت دلخواه اندازه داشته باشند و در پاسخ‌های API صفحه‌بندی شوند.

مبانی

پیام‌های درخواست برای مجموعه‌ها، یک فیلد pageSize عدد صحیح اختیاری را تعریف می‌کنند تا حداکثر تعداد نتایج قابل بازگشت را مشخص کنند.

پارامتر pageSize را روی یک عدد مثبت، کمتر از 1000 ، تنظیم کنید. اگر هیچ مقداری تنظیم نکنید یا پارامتر را روی صفر تنظیم کنید، API از مقدار پیش‌فرض 50 استفاده می‌کند. اگر پارامتر را روی یک مقدار منفی تنظیم کنید، API خطای INVALID_ARGUMENT را برمی‌گرداند.

برای مقدار pageSize مربوط به یک منبع خاص، به مستندات مرجع منابع، مثلاً AdBreaks ، مراجعه کنید.

ممکن است API نتایج کمتری نسبت به تعداد درخواستی (از جمله صفر نتیجه) برگرداند، حتی اگر در انتهای مجموعه نباشد. از وجود فیلد nextPageToken برای تعیین اینکه آیا نتایج اضافی در مجموعه وجود دارد یا خیر، استفاده کنید.

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

پیام‌های درخواست برای مجموعه‌ها، یک فیلد رشته‌ای اختیاری pageToken برای رفتن به صفحه بعدی در مجموعه تعریف می‌کنند. تغییرات در pageSize در درخواست برای صفحات بعدی مجاز است. همه آرگومان‌های دیگر باید یکسان باشند؛ اگر آرگومان‌ها متفاوت باشند، API خطای INVALID_ARGUMENT را برمی‌گرداند.

مثال

حلقه

درخواست اولیه

curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500

{
  "adUnits": [ ... ],
  "nextPageToken": "eCGwAcs6hUerggzd2DGv"
}

درخواست صفحه بعد

curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500&pageToken=eCGwAcs6hUerggzd2DGv

{
  "adUnits": [ ... ]
}

اندازه کل

پیام‌های پاسخ برای مجموعه‌ها یک عدد صحیح totalSize ارائه می‌دهند که تعداد کل موجودیت‌ها را پس از اعمال فیلتر نشان می‌دهد. این فیلد فقط در صورت درخواست در فیلد mask پر می‌شود.

GET https://admanager.googleapis.com/v1/networks/123456/adUnits?$fields=adUnits,nextPageToken,totalSize

نتایج سفارش

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

مقادیر باید با استفاده از کاما از هم جدا شوند. برای مثال: foo,bar . ترتیب مرتب‌سازی پیش‌فرض صعودی است. برای تعیین ترتیب نزولی برای یک فیلد، پسوند desc را اضافه کنید؛ برای مثال: foo desc, bar . کاراکترهای فاصله اضافی در سینتکس نادیده گرفته می‌شوند. مقادیر orderBy foo, bar desc ، foo , bar desc و foo,bar desc همگی معادل هستند. زیرفیلدها با کاراکتر . مشخص می‌شوند، مانند foo.bar یا address.street .

مرتب‌سازی فقط در فیلدهای اولیه پشتیبانی می‌شود.

رد شدن از نتایج

متدهای مربوط به عملیات صفحه‌بندی شده، یک فیلد skip از نوع عدد صحیح برای رد شدن از نتایج تعریف می‌کنند. مقدار رد شدن به تعداد منابع منفردی که باید رد شوند اشاره دارد، نه تعداد صفحات.

برای مثال:

درخواستی بدون نشانه صفحه و با مقدار skip برابر با 30، یک صفحه از نتایج را که از نتیجه سی و یکم شروع می‌شود، برمی‌گرداند.

یک درخواست با یک نشانه صفحه مربوط به نتیجه ۵۱ (زیرا ۵۰ نتیجه اول در صفحه اول برگردانده شده‌اند) و مقدار skip برابر با ۳۰، یک صفحه از نتایج را که از نتیجه ۸۱ شروع می‌شود، برمی‌گرداند.

اگر مقداری برای رد شدن ارائه شود که باعث شود مکان‌نما از انتهای مجموعه نتایج عبور کند، پاسخ 200 OK با یک مجموعه نتیجه خالی و بدون nextPageToken خواهد بود.