این سند برخیاز تکنیکهایی را که میتوانید برای بهبود عملکرد برنامهتان استفاده کنید پوشش میدهد. در برخی موارد، از نمونههای میاناهای برنامهسازی کاربردی دیگر یا میاناهای برنامهسازی کاربردی عمومی برای توضیح ایدههای ارائهشده استفاده میشود. بااینحال، همین مفاهیم برای 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)، از این پارامترها برای کاهش نتایج هر پُرسمان به اندازه قابلمدیریت استفاده کنید. درغیراینصورت، ممکن است بهبود عملکردی که با پاسخ جزئی امکانپذیر است محقق نشود.