این سند برخی از تکنیک ها را پوشش می دهد که می توانید برای بهبود عملکرد برنامه خود از آنها استفاده کنید. در برخی موارد، از نمونه هایی از دیگر APIهای پیاده سازی شده برای نشان دادن ایده های ارائه شده استفاده می شود. با این حال، همان مفاهیم برای Display & Video 360 API قابل اعمال است.
کار با منابع جزئی
یکی دیگر از راههای بهبود عملکرد تماسهای API این است که فقط بخشی از دادههایی را درخواست کنید که به آن علاقه دارید. این به برنامه شما امکان میدهد از انتقال، تجزیه و ذخیره فیلدهای غیر ضروری جلوگیری کند، بنابراین میتواند از منابعی مانند شبکه، CPU استفاده کند. و حافظه کارآمدتر است.
پاسخ نسبی
به طور پیش فرض، سرور پس از پردازش درخواست ها، نمایش کامل یک منبع را پس می فرستد. برای عملکرد بهتر، میتوانید از سرور بخواهید فقط فیلدهایی را که واقعاً به آن نیاز دارید ارسال کند و در عوض پاسخی جزئی دریافت کنید.
برای درخواست پاسخ جزئی، از پارامتر درخواست fields
استفاده کنید تا فیلدهایی را که می خواهید برگردانید مشخص کنید. می توانید از این پارامتر با هر درخواستی که داده های پاسخ را برمی گرداند استفاده کنید.
مثال
مثال زیر استفاده از پارامتر fields
را با Display & Video 360 API نشان می دهد.
درخواست ساده: این درخواست HTTP GET
پارامتر fields
را حذف می کند و منبع کامل را برمی گرداند.
GET https://displayvideo.googleapis.com/v3/advertisers?partnerId=1
پاسخ منبع کامل: دادههای کامل منبع شامل فیلدهای زیر است، همراه با بسیاری دیگر که برای اختصار حذف شدهاند.
200 OK
{
"advertisers": [
{
"name": "advertisers/1",
"advertiserId": "1",
"partnerId": "1",
"displayName": "Example Advertiser 1",
"entityStatus": "ENTITY_STATUS_ACTIVE",
"updateTime": "2019-01-01T00:00:00.000000Z",
"generalConfig": {
"domainUrl": "http://example.com",
"timeZone": "America/New_York",
"currencyCode": "USD",
"address": {
}
},
"adServerConfig": {
"thirdPartyOnlyConfig": {
}
},
"creativeConfig": {
},
"dataAccessConfig": {
"sdfConfig": {
"sdfConfig": {
"version": "VERSION_3_1"
}
}
},
"integrationDetails": {
}
},
{
"name": "advertisers/2",
"advertiserId": "2",
"partnerId": "1",
"displayName": "Example Advertiser 2",
"entityStatus": "ENTITY_STATUS_ACTIVE",
"updateTime": "2019-01-01T00:00:00.000000Z",
"generalConfig": {
"domainUrl": "http://example.com",
"timeZone": "America/New_York",
"currencyCode": "USD",
"address": {
}
},
"adServerConfig": {
"thirdPartyOnlyConfig": {
}
},
"creativeConfig": {
},
"dataAccessConfig": {
"sdfConfig": {
"sdfConfig": {
"version": "VERSION_3_1"
}
}
},
"integrationDetails": {
}
},
...
],
"nextPageToken": "..."
}
درخواست پاسخ جزئی: درخواست زیر برای همین منبع از پارامتر fields
استفاده میکند تا میزان دادههای برگشتی را به میزان قابل توجهی کاهش دهد.
GET https://displayvideo.googleapis.com/v3/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)
پاسخ جزئی: در پاسخ به درخواست بالا، سرور پاسخی را ارسال میکند که حاوی یک آرایه تبلیغکننده کاهشیافته است که فقط شامل شناسه تبلیغکننده، نام نمایشی و ویژگی شناسه شریک هر تبلیغکننده، در صورت وجود، است.
200 OK
{
"advertisers": [
{
"advertiserId": "1",
"partnerId": "1",
"displayName": "Example Advertiser 1"
},
{
"advertiserId": "2",
"partnerId": "1",
"displayName": "Example Advertiser 2"
},
...
]
}
توجه داشته باشید که پاسخ یک شی JSON است که فقط شامل فیلدهای انتخاب شده و اشیاء والد محصور آنها می شود.
جزئیات در مورد نحوه قالب بندی پارامتر fields
در ادامه پوشش داده می شود و به دنبال آن جزئیات بیشتری در مورد آنچه دقیقاً در پاسخ برگردانده می شود، ارائه می شود.
خلاصه نحو پارامتر فیلدها
فرمت مقدار پارامتر درخواست fields
بر اساس نحو XPath است. نحو پشتیبانی شده در زیر خلاصه شده است و نمونه های اضافی در بخش زیر ارائه شده است.
از یک لیست جدا شده با کاما برای انتخاب چندین فیلد استفاده کنید.
از
a/b
برای انتخاب فیلدb
که در فیلدa
تودرتو است استفاده کنید. ازa/b/c
برای انتخاب یک فیلدc
تو در تو درb
استفاده کنید.از یک انتخابگر فرعی برای درخواست مجموعه ای از فیلدهای فرعی خاص از آرایه ها یا اشیاء با قرار دادن عبارات در پرانتز "
( )
" استفاده کنید.برای مثال:
fields=advertisers(advertiserId,generalConfig/domainUrl)
فقط شناسه تبلیغکننده و URL دامنه را برای هر عنصر در آرایه تبلیغکنندگان برمیگرداند. شما همچنین می توانید یک زیر فیلد را مشخص کنید که در آنfields=advertisers(advertiserId)
معادلfields=advertisers/advertiserId
باشد.
نمونه های بیشتری از استفاده از پارامتر فیلدها
مثالهای زیر شامل توضیحاتی در مورد چگونگی تأثیر مقدار پارامتر fields
بر پاسخ است.
- فیلدهایی را که می خواهید برگردانید شناسایی کنید یا فیلدهایی را انتخاب کنید.
مقدار پارامتر درخواست
fields
لیستی از فیلدها است که با کاما از هم جدا شده اند و هر فیلد نسبت به ریشه پاسخ مشخص می شود. بنابراین، اگر شما یک عملیاتlist
را انجام می دهید، پاسخ یک مجموعه است و به طور کلی شامل مجموعه ای از منابع است. اگر عملیاتی را انجام می دهید که یک منبع را برمی گرداند، فیلدهایی نسبت به آن منبع مشخص می شوند. اگر فیلدی که انتخاب میکنید یک آرایه باشد (یا بخشی از آن باشد)، سرور بخش انتخاب شده از تمام عناصر آرایه را برمیگرداند.در اینجا چند نمونه در سطح مجموعه آورده شده است:
مثال اثر advertisers
همه عناصر موجود در آرایه advertisers
، از جمله تمام فیلدهای هر عنصر، اما هیچ فیلد دیگری را برمیگرداند.advertisers,nextPageToken
هم فیلد nextPageToken
و هم تمام عناصر موجود در آرایهadvertisers
را برمیگرداند.advertisers/advertiserId
فقط advertiserId
برای همه عناصر موجود در آرایهadvertisers
برمیگرداند.
هر زمان که یک فیلد تودرتو برگردانده می شود، پاسخ شامل اشیاء والد محصور می شود. فیلدهای والد هیچ فیلد فرزند دیگری را شامل نمی شود مگر اینکه آنها نیز صریحاً انتخاب شده باشند.advertisers/generalConfig/domainUrl
فیلد domainUrl
را برای شیgeneralConfig
برمیگرداند که خود در زیر آرایهadvertisers
قرار دارد.در اینجا چند نمونه در سطح منبع آورده شده است:
مثال اثر advertiserId
قسمت advertiserId
منبع درخواستی را برمی گرداند.generalConfig/domainUrl
فیلد domainUrl
را برای شیgeneralConfig
در منبع درخواستی برمی گرداند.- فقط بخشهایی از فیلدهای خاص را با استفاده از انتخابهای فرعی درخواست کنید.
به طور پیش فرض، اگر درخواست شما فیلدهای خاصی را مشخص کند، سرور اشیاء یا عناصر آرایه را به طور کامل برمی گرداند. می توانید پاسخی را مشخص کنید که فقط شامل قسمت های فرعی خاصی باشد. شما این کار را با استفاده از نحو انتخاب فرعی "
( )
" مانند مثال زیر انجام می دهید.مثال اثر advertisers(advertiserId,generalConfig/domainUrl)
فقط مقادیر advertiserId
و generalConfigdomainUrl
را برای هر عنصر در آرایهadvertisers
برمیگرداند.
رسیدگی به پاسخ های جزئی
پس از اینکه سرور یک درخواست معتبر که شامل پارامتر پرس و جو fields
را پردازش کرد، یک کد وضعیت HTTP 200 OK
را به همراه داده های درخواستی ارسال می کند. اگر پارامتر پرس و جو fields
دارای خطا باشد یا در غیر این صورت نامعتبر باشد، سرور یک کد وضعیت HTTP 400 Bad Request
را به همراه یک پیام خطایی که به شما میگوید چه مشکلی در انتخاب فیلدها وجود دارد را برمیگرداند (به عنوان مثال، "Invalid field selection a/b"
).