بهبود کارایی

این سند برخی از تکنیک ها را پوشش می دهد که می توانید برای بهبود عملکرد برنامه خود از آنها استفاده کنید. در برخی موارد، نمونه هایی از سایر APIها یا APIهای عمومی برای نشان دادن ایده های ارائه شده استفاده می شود. با این حال، همان مفاهیم برای Google Drive API قابل اعمال است.

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

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

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

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

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

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

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

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

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

پاسخ نسبی

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

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

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

مثال

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

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

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

مثال

مدیریت پاسخ به یک پچ

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

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

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

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

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

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

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

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

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

درخواست های دسته ای

این سند نشان می‌دهد که چگونه می‌توانید تماس‌های API را با هم دسته‌بندی کنید تا تعداد اتصالات HTTP را که کلاینت‌تان باید برقرار کند، کاهش دهید.

این سند به طور خاص در مورد ایجاد یک درخواست دسته ای با ارسال یک درخواست HTTP است. اگر در عوض، از کتابخانه سرویس گیرنده Google برای درخواست دسته ای استفاده می کنید، به مستندات کتابخانه سرویس گیرنده مراجعه کنید.

نمای کلی

هر اتصال HTTP مشتری شما منجر به مقدار معینی سربار می شود. Google Drive API از دسته‌بندی پشتیبانی می‌کند تا به مشتری شما اجازه دهد چندین تماس API را در یک درخواست HTTP قرار دهد.

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

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

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

شما به 100 تماس در یک درخواست دسته‌ای محدود می‌شوید. اگر باید بیشتر از آن تماس بگیرید، از چندین درخواست دسته ای استفاده کنید.

توجه : سیستم دسته‌ای برای Google Drive API از نحوی مشابه با سیستم پردازش دسته‌ای OData استفاده می‌کند، اما معنایی متفاوت است.

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

  • درخواست های دسته ای با بیش از 100 تماس ممکن است باعث خطا شوند.
  • یک محدودیت 8000 کاراکتری در طول URL برای هر درخواست داخلی وجود دارد.
  • Google Drive از عملیات دسته‌ای برای رسانه، چه برای آپلود یا دانلود، یا برای صادر کردن فایل‌ها پشتیبانی نمی‌کند.

جزئیات دسته

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

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

فرمت درخواست دسته ای

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

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

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

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

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

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

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

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

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

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

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

مثال

مثال زیر استفاده از دسته‌بندی با Google Drive 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--

فیلدهای خاص را از درخواست برگردانید

اگر پارامتر fields را مشخص نکنید، سرور یک مجموعه پیش‌فرض از فیلدهای مخصوص روش را برمی‌گرداند. برای مثال، متد files.list فقط فیلدهای kind ، id ، name و mimeType را برمی‌گرداند.

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

برای همه روش‌های منابع about ، comments (به استثنای delete )، و replies (به استثنای delete ) باید پارامتر fields تنظیم کنید. این روش ها مجموعه ای از فیلدهای پیش فرض را بر نمی گرداند.

،

این سند برخی از تکنیک ها را پوشش می دهد که می توانید برای بهبود عملکرد برنامه خود از آنها استفاده کنید. در برخی موارد، نمونه هایی از سایر APIها یا APIهای عمومی برای نشان دادن ایده های ارائه شده استفاده می شود. با این حال، همان مفاهیم برای Google Drive API قابل اعمال است.

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

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

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

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

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

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

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

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

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

پاسخ نسبی

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

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

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

مثال

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

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

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

مثال

مدیریت پاسخ به یک پچ

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

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

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

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

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

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

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

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

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

درخواست های دسته ای

این سند نشان می‌دهد که چگونه می‌توانید تماس‌های API را با هم دسته‌بندی کنید تا تعداد اتصالات HTTP را که کلاینت‌تان باید برقرار کند، کاهش دهید.

این سند به طور خاص در مورد ایجاد یک درخواست دسته ای با ارسال یک درخواست HTTP است. اگر در عوض، از کتابخانه سرویس گیرنده Google برای درخواست دسته ای استفاده می کنید، به مستندات کتابخانه سرویس گیرنده مراجعه کنید.

نمای کلی

هر اتصال HTTP مشتری شما منجر به مقدار معینی سربار می شود. Google Drive API از دسته‌بندی پشتیبانی می‌کند تا به مشتری شما اجازه دهد چندین تماس API را در یک درخواست HTTP قرار دهد.

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

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

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

شما به 100 تماس در یک درخواست دسته‌ای محدود می‌شوید. اگر باید بیشتر از آن تماس بگیرید، از چندین درخواست دسته ای استفاده کنید.

توجه : سیستم دسته‌ای برای Google Drive API از نحوی مشابه با سیستم پردازش دسته‌ای OData استفاده می‌کند، اما معنایی متفاوت است.

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

  • درخواست های دسته ای با بیش از 100 تماس ممکن است باعث خطا شوند.
  • یک محدودیت 8000 کاراکتری در طول URL برای هر درخواست داخلی وجود دارد.
  • Google Drive از عملیات دسته‌ای برای رسانه، چه برای آپلود یا دانلود، یا برای صادر کردن فایل‌ها پشتیبانی نمی‌کند.

جزئیات دسته

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

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

فرمت درخواست دسته ای

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

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

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

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

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

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

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

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

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

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

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

مثال

مثال زیر استفاده از دسته‌بندی با Google Drive 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--

فیلدهای خاص را از درخواست برگردانید

اگر پارامتر fields را مشخص نکنید، سرور یک مجموعه پیش‌فرض از فیلدهای مخصوص روش را برمی‌گرداند. برای مثال، متد files.list فقط فیلدهای kind ، id ، name و mimeType را برمی‌گرداند.

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

برای همه روش‌های منابع about ، comments (به استثنای delete )، و replies (به استثنای delete ) باید پارامتر fields تنظیم کنید. این روش ها مجموعه ای از فیلدهای پیش فرض را بر نمی گرداند.

،

این سند برخی از تکنیک ها را پوشش می دهد که می توانید برای بهبود عملکرد برنامه خود از آنها استفاده کنید. در برخی موارد، نمونه هایی از سایر APIها یا APIهای عمومی برای نشان دادن ایده های ارائه شده استفاده می شود. با این حال، همان مفاهیم برای Google Drive API قابل اعمال است.

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

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

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

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

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

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

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

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

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

پاسخ نسبی

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

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

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

مثال

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

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

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

مثال

مدیریت پاسخ به یک پچ

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

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

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

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

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

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

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

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

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

درخواست های دسته ای

این سند نشان می‌دهد که چگونه می‌توانید تماس‌های API را با هم دسته‌بندی کنید تا تعداد اتصالات HTTP را که کلاینت‌تان باید برقرار کند، کاهش دهید.

این سند به طور خاص در مورد ایجاد یک درخواست دسته ای با ارسال یک درخواست HTTP است. اگر در عوض، از کتابخانه سرویس گیرنده Google برای درخواست دسته ای استفاده می کنید، به مستندات کتابخانه سرویس گیرنده مراجعه کنید.

نمای کلی

هر اتصال HTTP مشتری شما منجر به مقدار معینی سربار می شود. Google Drive API از دسته‌بندی پشتیبانی می‌کند تا به مشتری شما اجازه دهد چندین تماس API را در یک درخواست HTTP قرار دهد.

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

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

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

شما به 100 تماس در یک درخواست دسته‌ای محدود می‌شوید. اگر باید بیشتر از آن تماس بگیرید، از چندین درخواست دسته ای استفاده کنید.

توجه : سیستم دسته‌ای برای Google Drive API از نحوی مشابه با سیستم پردازش دسته‌ای OData استفاده می‌کند، اما معنایی متفاوت است.

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

  • درخواست های دسته ای با بیش از 100 تماس ممکن است باعث خطا شوند.
  • یک محدودیت 8000 کاراکتری در طول URL برای هر درخواست داخلی وجود دارد.
  • Google Drive از عملیات دسته‌ای برای رسانه، چه برای آپلود یا دانلود، یا برای صادر کردن فایل‌ها پشتیبانی نمی‌کند.

جزئیات دسته

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

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

فرمت درخواست دسته ای

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

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

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

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

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

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

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

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

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

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

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

مثال

مثال زیر استفاده از دسته‌بندی با Google Drive 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--

فیلدهای خاص را از درخواست برگردانید

اگر پارامتر fields را مشخص نکنید، سرور یک مجموعه پیش‌فرض از فیلدهای مخصوص روش را برمی‌گرداند. برای مثال، متد files.list فقط فیلدهای kind ، id ، name و mimeType را برمی‌گرداند.

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

برای همه روش‌های منابع about ، comments (به استثنای delete )، و replies (به استثنای delete ) باید پارامتر fields تنظیم کنید. این روش ها مجموعه ای از فیلدهای پیش فرض را بر نمی گرداند.

،

این سند برخی از تکنیک ها را پوشش می دهد که می توانید برای بهبود عملکرد برنامه خود از آنها استفاده کنید. در برخی موارد، نمونه هایی از سایر APIها یا APIهای عمومی برای نشان دادن ایده های ارائه شده استفاده می شود. با این حال، همان مفاهیم برای Google Drive API قابل اعمال است.

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

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

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

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

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

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

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

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

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

پاسخ نسبی

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

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

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

مثال

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

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

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

مثال

رسیدگی به پاسخ به پچ

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

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

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

نماد جایگزین هنگامی که فعل patch http پشتیبانی نمی شود

اگر فایروال شما اجازه درخواست HTTP PATCH را نمی دهد ، پس از درخواست HTTP POST را انجام دهید و همانطور که در زیر آمده است ، هدر Override را روی PATCH تنظیم کنید:

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

تفاوت بین پچ و به روزرسانی

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

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

درخواست های دسته ای

این سند نشان می دهد که چگونه می توان API را با هم جمع کرد تا تعداد اتصالات HTTP را که مشتری شما باید ایجاد کند ، کاهش دهد.

این سند به طور خاص در مورد ایجاد درخواست دسته ای با ارسال درخواست HTTP است. اگر در عوض ، از یک کتابخانه Google Client برای ایجاد درخواست دسته ای استفاده می کنید ، به مستندات کتابخانه مشتری مراجعه کنید.

نمای کلی

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

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

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

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

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

توجه : سیستم دسته ای برای Google Drive API از همان نحو سیستم پردازش دسته ای ODATA استفاده می کند ، اما معناشناسی متفاوت است.

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

  • درخواست های دسته ای با بیش از 100 تماس ممکن است خطایی ایجاد کند.
  • برای هر درخواست داخلی ، 8000 کاراکتر در طول URL وجود دارد.
  • Google Drive از عملیات دسته ای برای رسانه ، چه برای بارگذاری یا بارگیری ، یا برای صادرات پرونده ها پشتیبانی نمی کند.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مثال

مثال زیر استفاده از دسته بندی با Google Drive 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--

قسمتهای خاص را از درخواست برگردانید

اگر پارامتر fields را مشخص نکنید ، سرور مجموعه ای پیش فرض از فیلدهای خاص برای روش را برمی گرداند. به عنوان مثال ، روش files.list فقط زمینه های kind ، id ، name و mimeType را برمی گرداند.

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

برای کلیه روشهای about به ، comments (به استثنای delete ) ، و replies (به استثنای delete ) منابع شما باید پارامتر fields تنظیم کنید. این روشها مجموعه ای از زمینه های پیش فرض را برمی گردانند.