بهبود کارایی

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

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

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

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

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

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

دو نوع درخواست جزئی وجود دارد:

• پاسخ جزئی : درخواستی که در آن مشخص می‌کنید کدام فیلدها در پاسخ گنجانده شوند (از پارامتر درخواست fields استفاده کنید).
• پچ : یک درخواست به‌روزرسانی که در آن فقط فیلدهایی را که می‌خواهید تغییر دهید ارسال می‌کنید (از فعل PATCH HTTP استفاده کنید).

جزئیات بیشتر در مورد درخواست‌های جزئی در بخش‌های بعدی ارائه شده است.

پاسخ جزئی

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

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

توجه داشته باشید که پارامتر fields فقط بر داده‌های پاسخ تأثیر می‌گذارد؛ بر داده‌هایی که باید ارسال کنید، در صورت وجود، تأثیری ندارد. برای کاهش میزان داده‌هایی که هنگام تغییر منابع ارسال می‌کنید، از درخواست patch استفاده کنید.

پچ (به‌روزرسانی جزئی)

همچنین می‌توانید هنگام تغییر منابع از ارسال داده‌های غیرضروری خودداری کنید. برای ارسال داده‌های به‌روزرسانی‌شده فقط برای فیلدهای خاصی که تغییر می‌دهید، از فعل HTTP PATCH استفاده کنید. معانی وصله شرح داده شده در این سند متفاوت (و ساده‌تر) از پیاده‌سازی قدیمی‌تر GData از به‌روزرسانی جزئی است.

مثال کوتاه زیر نشان می‌دهد که چگونه استفاده از patch داده‌هایی را که برای ایجاد یک به‌روزرسانی کوچک باید ارسال کنید، به حداقل می‌رساند.

مثال

مدیریت پاسخ به یک وصله

پس از پردازش یک درخواست وصله معتبر، API یک کد پاسخ HTTP با 200 OK به همراه نمایش کامل منبع اصلاح‌شده برمی‌گرداند. اگر ETagها توسط API استفاده شوند، سرور مقادیر ETag را پس از پردازش موفقیت‌آمیز یک درخواست وصله، به‌روزرسانی می‌کند، درست همانطور که با PUT انجام می‌دهد.

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

اگر درخواست وصله منجر به وضعیت منبع جدیدی شود که از نظر نحوی یا معنایی نامعتبر باشد، سرور کد وضعیت HTTP با کد 400 Bad Request یا 422 Unprocessable Entity را برمی‌گرداند و وضعیت منبع بدون تغییر باقی می‌ماند. برای مثال، اگر سعی کنید مقدار یک فیلد الزامی را حذف کنید، سرور خطایی را برمی‌گرداند.

نمادگذاری جایگزین زمانی که فعل PATCH HTTP پشتیبانی نمی‌شود

اگر فایروال شما درخواست‌های HTTP PATCH را مجاز نمی‌داند، یک درخواست HTTP POST ارسال کنید و هدر override را مطابق شکل زیر روی PATCH تنظیم کنید:

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

تفاوت بین پچ و آپدیت

در عمل، وقتی برای یک درخواست به‌روزرسانی که از فعل HTTP PUT استفاده می‌کند، داده‌ها را ارسال می‌کنید، فقط باید فیلدهایی را ارسال کنید که اجباری یا اختیاری هستند؛ اگر مقادیری را برای فیلدهایی که توسط سرور تنظیم شده‌اند ارسال کنید، آنها نادیده گرفته می‌شوند. اگرچه این ممکن است راه دیگری برای انجام یک به‌روزرسانی جزئی به نظر برسد، اما این رویکرد محدودیت‌هایی دارد. در به‌روزرسانی‌هایی که از فعل HTTP PUT استفاده می‌کنند، اگر پارامترهای اجباری را ارائه ندهید، درخواست با شکست مواجه می‌شود و اگر پارامترهای اختیاری را ارائه ندهید، داده‌های تنظیم‌شده قبلی پاک می‌شوند.

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

نمای کلی

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

نمونه‌هایی از موقعیت‌هایی که ممکن است بخواهید از دسته‌بندی استفاده کنید:

• بازیابی فراداده برای تعداد زیادی فایل.
• به‌روزرسانی انبوه فراداده‌ها یا ویژگی‌ها.
• تغییر مجوزها برای تعداد زیادی فایل، مانند اضافه کردن یک کاربر یا گروه جدید.
• همگام‌سازی داده‌های کلاینت محلی برای اولین بار یا پس از آفلاین بودن برای مدت طولانی.

در هر مورد، به جای ارسال جداگانه هر فراخوانی، می‌توانید آنها را در یک درخواست HTTP واحد گروه‌بندی کنید. همه درخواست‌های داخلی باید به یک API گوگل یکسان بروند.

شما در یک درخواست دسته‌ای محدود به ۱۰۰ تماس هستید. اگر مجبور به برقراری تماس‌های بیشتر از این هستید، از درخواست‌های دسته‌ای چندگانه استفاده کنید.

نکته : سیستم دسته‌ای برای API گوگل درایو از همان سینتکس سیستم پردازش دسته‌ای OData استفاده می‌کند، اما معانی آنها متفاوت است.

محدودیت‌های اضافی عبارتند از:

• درخواست‌های دسته‌ای با بیش از ۱۰۰ فراخوانی ممکن است باعث خطا شوند.
• برای هر درخواست داخلی، محدودیت ۸۰۰۰ کاراکتری برای طول URL وجود دارد.
• گوگل درایو از عملیات دسته‌ای برای رسانه‌ها، چه برای آپلود و چه برای دانلود، و چه برای خروجی گرفتن از فایل‌ها، پشتیبانی نمی‌کند.

جزئیات دسته‌ای

یک درخواست دسته‌ای شامل چندین فراخوانی API است که در قالب یک درخواست HTTP ترکیب شده‌اند و می‌توانند به batchPath مشخص شده در سند کشف API ارسال شوند. مسیر پیش‌فرض /batch/ api_name / api_version است. این بخش سینتکس دسته‌ای را با جزئیات شرح می‌دهد؛ بعداً، یک مثال وجود دارد.

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

قالب درخواست دسته‌ای

یک درخواست دسته‌ای، یک درخواست HTTP استاندارد واحد است که شامل چندین فراخوانی API گوگل درایو است و از نوع محتوای multipart/mixed استفاده می‌کند. در داخل آن درخواست HTTP اصلی، هر یک از بخش‌ها شامل یک درخواست HTTP تو در تو هستند.

هر بخش با هدر Content-Type: application/http HTTP مخصوص به خود شروع می‌شود. همچنین می‌تواند یک هدر Content-ID اختیاری داشته باشد. با این حال، هدرهای بخش فقط برای مشخص کردن شروع بخش وجود دارند؛ آنها از درخواست تو در تو جدا هستند. پس از اینکه سرور درخواست دسته‌ای را به درخواست‌های جداگانه تجزیه می‌کند، هدرهای بخش نادیده گرفته می‌شوند.

بدنه هر بخش، یک درخواست HTTP کامل است که فعل، URL، هدرها و بدنه مخصوص به خود را دارد. درخواست HTTP فقط باید شامل بخش مسیر URL باشد؛ URL های کامل در درخواست های دسته ای مجاز نیستند.

هدرهای HTTP برای درخواست دسته‌ای بیرونی، به جز هدرهای Content- مانند Content-Type ، برای هر درخواست در دسته اعمال می‌شوند. اگر یک هدر HTTP مشخص را هم در درخواست بیرونی و هم در یک فراخوانی جداگانه مشخص کنید، مقدار هدر فراخوانی جداگانه، مقدار هدر درخواست دسته‌ای بیرونی را لغو می‌کند. هدرهای یک فراخوانی جداگانه فقط برای آن فراخوانی اعمال می‌شوند.

برای مثال، اگر برای یک فراخوانی خاص، یک هدر مجوز (Authorization header) ارائه دهید، آن هدر فقط برای همان فراخوانی اعمال می‌شود. اگر برای درخواست بیرونی، یک هدر مجوز (Authorization header) ارائه دهید، آن هدر برای تمام فراخوانی‌های منفرد اعمال می‌شود، مگر اینکه آنها با هدرهای مجوز (Authorization header) خودشان، آن را لغو کنند.

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

پاسخ به درخواست دسته‌ای

پاسخ سرور، یک پاسخ استاندارد HTTP با نوع محتوای multipart/mixed است؛ هر بخش، پاسخ به یکی از درخواست‌های موجود در درخواست دسته‌ای، به همان ترتیب درخواست‌ها، می‌باشد.

مانند بخش‌های درخواست، هر بخش پاسخ شامل یک پاسخ کامل HTTP، شامل کد وضعیت، هدرها و بدنه است. و مانند بخش‌های درخواست، قبل از هر بخش پاسخ، یک هدر Content-Type قرار دارد که ابتدای بخش را مشخص می‌کند.

اگر بخش مشخصی از درخواست دارای سرآیند Content-ID باشد، بخش متناظر پاسخ نیز دارای سرآیند Content-ID منطبق با آن است که مقدار اصلی آن قبل از رشته response- قرار می‌گیرد، همانطور که در مثال زیر نشان داده شده است.

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

مثال

مثال زیر استفاده از دسته‌بندی با API گوگل درایو را نشان می‌دهد.

مثال درخواست دسته‌ای

POST https://www.googleapis.com/batch/drive/v3
Accept-Encoding: gzip
User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip)
Content-Type: multipart/mixed; boundary=END_OF_PART
Content-Length: 963


--END_OF_PART
Content-Length: 337
Content-Type: application/http
content-id: 1
content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id
Authorization: Bearer authorization_token
Content-Length: 70
Content-Type: application/json; charset=UTF-8

{
  "emailAddress":"example@appsrocks.com",
  "role":"writer",
  "type":"user"
}
--END_OF_PART
Content-Length: 353
Content-Type: application/http
content-id: 2
content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false
Authorization: Bearer authorization_token
Content-Length: 58
Content-Type: application/json; charset=UTF-8

{
   "domain":"appsrocks.com",
   "role":"reader",
   "type":"domain"
}
--END_OF_PART--

مثال پاسخ دسته‌ای

این پاسخ به درخواست نمونه در بخش قبلی است.

HTTP/1.1 200 OK
Alt-Svc: quic=":443"; p="1"; ma=604800
Server: GSE
Alternate-Protocol: 443:quic,p=1
X-Frame-Options: SAMEORIGIN
Content-Encoding: gzip
X-XSS-Protection: 1; mode=block
Content-Type: multipart/mixed; boundary=batch_6VIxXCQbJoQ_AATxy_GgFUk
Transfer-Encoding: chunked
X-Content-Type-Options: nosniff
Date: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Vary: X-Origin
Vary: Origin
Expires: Fri, 13 Nov 2015 19:28:59 GMT


--batch_6VIxXCQbJoQ_AATxy_GgFUk
Content-Type: application/http
Content-ID: response-1

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Date: Fri, 13 Nov 2015 19:28:59 GMT
Expires: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Content-Length: 35

{
 "id": "12218244892818058021i"
}

--batch_6VIxXCQbJoQ_AATxy_GgFUk
Content-Type: application/http
Content-ID: response-2

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Date: Fri, 13 Nov 2015 19:28:59 GMT
Expires: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Content-Length: 35

{
 "id": "04109509152946699072k"
}

--batch_6VIxXCQbJoQ_AATxy_GgFUk--