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

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

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

نمای کلی

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

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

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

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

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

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

توجه : اندازه‌های بزرگتر دسته احتمالاً باعث محدودیت سرعت می‌شوند. ارسال دسته‌های بزرگتر از ۵۰ درخواست توصیه نمی‌شود.

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

یک درخواست دسته‌ای شامل چندین فراخوانی 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 نمایشی عمومی (تخیلی) به نام Farm API نشان می‌دهد. با این حال، همین مفاهیم در مورد Gmail API نیز صدق می‌کنند.

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

POST /batch/farm/v1 HTTP/1.1
Authorization: Bearer your_auth_token
Host: www.googleapis.com
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item1:12930812@barnyard.example.com>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:12930812@barnyard.example.com>

PUT /farm/v1/animals/sheep
Content-Type: application/json
Content-Length: part_content_length
If-Match: "etag/sheep"

{
  "animalName": "sheep",
  "animalAge": "5"
  "peltColor": "green",
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item3:12930812@barnyard.example.com>

GET /farm/v1/animals
If-None-Match: "etag/animals"

--batch_foobarbaz--

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

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

HTTP/1.1 200
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:12930812@barnyard.example.com>

HTTP/1.1 200 OK
Content-Type application/json
Content-Length: response_part_1_content_length
ETag: "etag/pony"

{
  "kind": "farm#animal",
  "etag": "etag/pony",
  "selfLink": "/farm/v1/animals/pony",
  "animalName": "pony",
  "animalAge": 34,
  "peltColor": "white"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:12930812@barnyard.example.com>

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: response_part_2_content_length
ETag: "etag/sheep"

{
  "kind": "farm#animal",
  "etag": "etag/sheep",
  "selfLink": "/farm/v1/animals/sheep",
  "animalName": "sheep",
  "animalAge": 5,
  "peltColor": "green"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item3:12930812@barnyard.example.com>

HTTP/1.1 304 Not Modified
ETag: "etag/animals"

--batch_foobarbaz--