بهبود عملکرد

این سند برخی‌از تکنیک‌هایی را که می‌توانید برای بهبود عملکرد برنامه‌تان استفاده کنید پوشش می‌دهد. در برخی موارد، از نمونه‌های میاناهای برنامه‌سازی کاربردی دیگر یا میاناهای برنامه‌سازی کاربردی عمومی برای توضیح ایده‌های ارائه‌شده استفاده می‌شود. بااین‌حال، همین مفاهیم برای Google Forms API نیز قابل‌اجرا است.

فشرده‌سازی بااستفاده از gzip

یک راه آسان و راحت برای کاهش پهنای باند موردنیاز برای هر درخواست، فعال کردن فشرده‌سازی gzip است. اگرچه این کار به زمان واحد پردازش مرکزی بیشتری برای ازحالت فشرده خارج کردن نتایج نیاز دارد، اما معمولاً در مقایسه با هزینه‌های شبکه بسیار ارزشمند است.

برای دریافت پاسخ کدگذاری‌شده gzip، باید دو کار انجام دهید: یک سرصفحه Accept-Encoding تنظیم کنید و نماینده کاربر خود را تغییر دهید تا رشته gzip را دربرگیرد. در اینجا نمونه‌ای از سرایندهای HTTP با قالب‌بندی مناسب برای فعال کردن فشرده‌سازی gzip آورده شده است:

Accept-Encoding: gzip
User-Agent: my program (gzip)

کار کردن با منابع جزئی

راه دیگر برای بهبود عملکرد فراخوانی‌های API شما این است که فقط بخشی از داده‌هایی را که به آن علاقه دارید درخواست کنید. این کار به برنامه شما اجازه می‌دهد از انتقال، تجزیه، و ذخیره کردن فیلدهای غیرضروری اجتناب کند تا بتواند از منابعی مثل شبکه، CPU، و حافظه به‌طور کارآمدتری استفاده کند.

پاسخ جزئی

به‌طور پیش‌فرض، سرور پس‌از پردازش درخواست‌ها، نمایش کامل منبع را برمی‌گرداند. برای عملکرد بهتر، می‌توانید از سرور بخواهید فقط فیلدهایی را که واقعاً نیاز دارید ارسال کند و درعوض پاسخ جزئی دریافت کنید.

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

مثال

مثال زیر استفاده از پارامتر fields را با یک API عمومی (ساختگی) «نسخه نمایشی» نشان می‌دهد.

درخواست ساده: این درخواست GET اچ‌تی‌تی‌پی پارامتر fields را حذف می‌کند و منبع کامل را برمی‌گرداند.

https://www.googleapis.com/demo/v1

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

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

درخواست برای پاسخ جزئی: درخواست زیر برای همین منبع از پارامتر fields برای کاهش قابل‌توجه مقدار داده‌های برگردانده‌شده استفاده می‌کند.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

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

200 OK
{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

توجه داشته باشید که پاسخ یک شیء JSON است که فقط شامل فیلدهای انتخاب‌شده و اشیاء والد دربرگیرنده آن‌ها است.

جزئیات مربوط به نحوه قالب‌بندی پارامتر fields در ادامه پوشش داده شده است و سپس جزئیات بیشتری درباره آنچه دقیقاً در پاسخ برگردانده می‌شود ارائه شده است.

خلاصه نحو پارامتر فیلدها

قالب مقدار پارامتر درخواست fields تا حدودی براساس نحو XPath است. نحو پشتیبانی‌شده در زیر خلاصه شده است و مثال‌های بیشتر در بخش زیر ارائه شده است.

  • برای انتخاب چند فیلد، از فهرست جداشده با کاما استفاده کنید.
  • از a/b برای انتخاب فیلد b که در فیلد a تودرتو شده است استفاده کنید؛ از a/b/c برای انتخاب فیلد c که در b تودرتو شده است استفاده کنید.

    استثنا: برای پاسخ‌های میانای برنامه‌سازی کاربردی که از پوشاننده‌های «داده» استفاده می‌کنند، جایی که پاسخ در شیء data تودرتو است که شبیه data: { ... } است، «data» را در مشخصات fields لحاظ نکنید. گنجاندن شیء داده با مشخصات فیلدهایی مثل data/a/b باعث بروز خطا می‌شود. درعوض، فقط از مشخصات fields مثل a/b استفاده کنید.

  • با قرار دادن عبارت‌ها در پرانتز «( )»، از زیرانتخابگر برای درخواست مجموعه‌ای از زیرفیلدهای خاص آرایه‌ها یا اشیاء استفاده کنید.

    برای مثال: fields=items(id,author/email) فقط شناسه مورد و ایمیل نویسنده را برای هر عنصر در آرایه موارد برمی‌گرداند. همچنین می‌توانید یک زیرفیلد تکی را مشخص کنید، که در آن fields=items(id) معادل fields=items/id است.

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

    برای مثال: fields=items/pagemap/* همه اشیاء را در pagemap انتخاب می‌کند.

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

نمونه‌های زیر شامل توضیحاتی درباره نحوه تأثیر مقدار پارامتر fields بر پاسخ است.

توجه: مانند همه مقادیر پارامتر پُرسمان، مقدار پارامتر fields باید کدگذاری نشانی وب باشد. برای خوانایی بهتر، مثال‌های این سند فاقد کدبندی است.

فیلدهایی را که می‌خواهید برگردانده شود شناسایی کنید یا انتخاب‌های فیلد را انجام دهید.
مقدار پارامتر درخواست fields فهرستی از فیلدها است که با کاما از هم جدا شده‌اند و هر فیلد نسبت به ریشه پاسخ مشخص شده است. بنابراین، اگر عملیات فهرست را انجام می‌دهید، پاسخ یک مجموعه است و معمولاً شامل آرایه‌ای از منابع است. اگر عملیاتی را انجام می‌دهید که یک منبع را برمی‌گرداند، فیلدها نسبت به آن منبع مشخص می‌شوند. اگر فیلدی که انتخاب می‌کنید یک آرایه (یا بخشی از آن) باشد، سرور بخش انتخاب‌شده از همه عناصر موجود در آرایه را برمی‌گرداند.

در اینجا چند نمونه در سطح مجموعه آورده شده است:
مثال‌ها جلوه
items همه عناصر موجود در آرایه موارد، ازجمله همه فیلدهای موجود در هر عنصر، اما هیچ فیلد دیگری را برمی‌گرداند.
etag,items هم فیلد etag و هم همه عناصر موجود در آرایه موارد را برمی‌گرداند.
items/title فقط فیلد title را برای همه عناصر در آرایه موارد برمی‌گرداند.

هرگاه فیلد تودرتویی برگردانده شود، پاسخ شامل شیءهای والد دربرگیرنده است. فیلدهای والد هیچ فیلد فرزند دیگری را دربرنمی‌گیرد، مگراینکه آن‌ها نیز به‌طور صریح انتخاب شده باشند.
context/facets/label فقط فیلد label را برای همه اعضای آرایه facets برمی‌گرداند که خودش در زیر شیء context تودرتو شده است.
items/pagemap/*/title برای هر عنصر در آرایه موارد، فقط فیلد title (درصورت وجود) همه اشیایی را که فرزند pagemap هستند برمی‌گرداند.

در اینجا چند نمونه در سطح منبع آورده شده است:
مثال‌ها جلوه
title فیلد title منبع درخواست‌شده را برمی‌گرداند.
author/uri زیرفیلد uri از شیء author را در منبع درخواست‌شده برمی‌گرداند.
links/*/href
فیلد href همه اشیایی را که فرزند links هستند برمی‌گرداند.
بااستفاده از انتخاب‌های فرعی، فقط بخش‌هایی از فیلدهای خاص را درخواست کنید.
به‌طور پیش‌فرض، اگر درخواست شما فیلدهای خاصی را مشخص کند، سرور اشیاء یا عناصر آرایه را به‌طور کامل برمی‌گرداند. می‌توانید پاسخی را مشخص کنید که فقط شامل زیرفیلدهای خاصی باشد. این کار را بااستفاده از نحو زیرانتخاب «( )» انجام می‌دهید، مانند مثال زیر.
مثال جلوه
items(title,author/uri) فقط مقادیر title و uri نویسنده را برای هر عنصر در آرایه موارد برمی‌گرداند.

رسیدگی به پاسخ‌های جزئی

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

در اینجا نمونه پاسخ جزئی نشان‌داده‌شده در بخش مقدماتی بالا آورده شده است. درخواست از پارامتر fields برای مشخص کردن فیلدهای برگشتی استفاده می‌کند.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

پاسخ ناتمام به این شکل است:

200 OK
{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

توجه: برای میاناهای برنامه‌سازی کاربردی که از پارامترهای پُرسمان برای صفحه‌بندی داده‌ها پشتیبانی می‌کنند (برای مثال، maxResults و nextPageToken)، از این پارامترها برای کاهش نتایج هر پُرسمان به اندازه قابل‌مدیریت استفاده کنید. درغیراین‌صورت، ممکن است بهبود عملکردی که با پاسخ جزئی امکان‌پذیر است محقق نشود.