این سند نشان میدهد که چگونه فراخوانیهای API را دسته بندی کنید تا تعداد اتصالات HTTP که کلاینت شما باید برقرار کند را کاهش دهید.
این سند به طور خاص در مورد ایجاد درخواست دستهای با ارسال درخواست HTTP است. اگر به جای آن، از یک کتابخانه کلاینت گوگل برای ایجاد درخواست دستهای استفاده میکنید، به مستندات کتابخانه کلاینت مراجعه کنید.
نمای کلی
هر اتصال HTTP که کلاینت شما برقرار میکند، منجر به مقدار مشخصی سربار میشود. API کلاس درس گوگل از دستهبندی پشتیبانی میکند تا به کلاینت شما اجازه دهد چندین فراخوانی API را در یک درخواست HTTP واحد قرار دهد.
نمونههایی از موقعیتهایی که ممکن است بخواهید از دستهبندی استفاده کنید:
- بازیابی فهرست اسامی تعداد زیادی از دورهها.
- ایجاد یا بهروزرسانی دورهها به صورت انبوه.
- اضافه شدن تعداد زیادی از فهرستهای دورههای آموزشی.
- بازیابی لیست دورهها برای تعداد زیادی از کاربران.
در هر مورد، به جای ارسال جداگانه هر فراخوانی، میتوانید آنها را در یک درخواست HTTP واحد گروهبندی کنید. همه درخواستهای داخلی باید به یک API گوگل یکسان بروند.
شما در یک درخواست دستهای محدود به ۵۰ تماس هستید. اگر مجبور به برقراری تماسهای بیشتر از این هستید، از درخواستهای دستهای چندگانه استفاده کنید.
نکته : سیستم دستهای برای 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- قرار میگیرد، همانطور که در مثال زیر نشان داده شده است.
توجه : سرور ممکن است فراخوانیهای شما را به هر ترتیبی انجام دهد. روی اجرای آنها به ترتیبی که شما مشخص کردهاید حساب نکنید. اگر میخواهید مطمئن شوید که دو فراخوانی به ترتیب مشخصی انجام میشوند، نمیتوانید آنها را در یک درخواست واحد ارسال کنید. در عوض، اولی را به تنهایی ارسال کنید، سپس قبل از ارسال دومی منتظر پاسخ اولی باشید.
مثال
مثال زیر استفاده از دستهبندی با رابط برنامهنویسی کاربردی Google Classroom را نشان میدهد.
مثال درخواست دستهای
POST https://classroom.googleapis.com/batch HTTP/1.1
Authorization: Bearer your_auth_token
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length
--batch_foobarbaz
Content-Type: application/http
Content-Transfer-Encoding: binary
MIME-Version: 1.0
Content-ID: <item1:12930812@classroom.example.com>
PATCH /v1/courses/134529639?updateMask=name HTTP/1.1
Content-Type: application/json; charset=UTF-8
Authorization: Bearer your_auth_token
{
"name": "Course 1"
}
--batch_foobarbaz
Content-Type: application/http
Content-Transfer-Encoding: binary
MIME-Version: 1.0
Content-ID: <item2:12930812@classroom.example.com>
PATCH /v1/courses/134529901?updateMask=section HTTP/1.1
Content-Type: application/json; charset=UTF-8
Authorization: Bearer your_auth_token
{
"section": "Section 2"
}
--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@classroom.example.com>
HTTP/1.1 200 OK
Content-Type application/json
Content-Length: response_part_1_content_length
{
"id": "134529639",
"name": "Course 1",
"section": "Section 1",
"ownerId": "116269102540619633451",
"creationTime": "2015-06-25T14:23:56.535Z",
"updateTime": "2015-06-25T14:33:06.583Z",
"enrollmentCode": "6paeflo",
"courseState": "PROVISIONED",
"alternateLink": "http://classroom.google.com/c/MTM0NTI5NjM5"
}
--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:12930812@classroom.example.com>
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: response_part_2_content_length
{
"id": "134529901",
"name": "Course 1",
"section": "Section 2",
"ownerId": "116269102540619633451",
"creationTime": "2015-06-25T14:23:08.761Z",
"updateTime": "2015-06-25T14:33:06.490Z",
"enrollmentCode": "so75ha5",
"courseState": "PROVISIONED",
"alternateLink": "http://classroom.google.com/c/MTM0NTI5OTAx"
}
--batch_foobarbaz--
استفاده از کتابخانههای کلاینت
نمونههای کد زیر نحوهی ایجاد درخواستهای دستهای با استفاده از کتابخانههای کلاینت Google APIs را نشان میدهند. برای اطلاعات بیشتر در مورد نحوهی نصب و راهاندازی کتابخانهها، به راهنماهای شروع سریع مربوطه مراجعه کنید.
دات نت
جاوا
پی اچ پی
پایتون
course_id = '123456' student_emails = ['alice@example.edu', 'bob@example.edu'] def callback(request_id, response, exception): if exception is not None: print 'Error adding user "{0}" to the course course: {1}'.format( request_id, exception) else: print 'User "{0}" added as a student to the course.'.format( response.get('profile').get('name').get('fullName')) batch = service.new_batch_http_request(callback=callback) for student_email in student_emails: student = { 'userId': student_email } request = service.courses().students().create(courseId=course_id, body=student) batch.add(request, request_id=student_email) batch.execute(http=http)