بهبود کارایی

این سند برخی از تکنیک ها را پوشش می دهد که می توانید برای بهبود عملکرد برنامه خود از آنها استفاده کنید. در برخی موارد، از نمونه هایی از دیگر 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 و generalConfig domainUrl را برای هر عنصر در آرایه advertisers برمی‌گرداند.
رسیدگی به پاسخ های جزئی

پس از اینکه سرور یک درخواست معتبر که شامل پارامتر پرس و جو fields را پردازش کرد، یک کد وضعیت HTTP 200 OK را به همراه داده های درخواستی ارسال می کند. اگر پارامتر پرس و جو fields دارای خطا باشد یا در غیر این صورت نامعتبر باشد، سرور یک کد وضعیت HTTP 400 Bad Request را به همراه یک پیام خطایی که به شما می‌گوید چه مشکلی در انتخاب فیلدها وجود دارد را برمی‌گرداند (به عنوان مثال، "Invalid field selection a/b" ).