ব্যাচ অনুরোধ

সংক্ষিপ্ত বিবরণ

আপনার ক্লায়েন্টের প্রতিটি HTTP সংযোগের ফলে একটি নির্দিষ্ট পরিমাণ ওভারহেড তৈরি হয়। Gmail API ব্যাচিং সমর্থন করে, যা আপনার ক্লায়েন্টকে একাধিক API কলকে একটি একক HTTP অনুরোধে অন্তর্ভুক্ত করার সুযোগ দেয়।

যেসব পরিস্থিতিতে আপনি ব্যাচিং ব্যবহার করতে চাইতে পারেন তার কিছু উদাহরণ:

• আপনি এইমাত্র এপিআই ব্যবহার করা শুরু করেছেন এবং আপনার কাছে আপলোড করার জন্য প্রচুর ডেটা রয়েছে।
• আপনার অ্যাপ্লিকেশনটি অফলাইনে (ইন্টারনেট সংযোগ বিচ্ছিন্ন) থাকাকালীন একজন ব্যবহারকারী ডেটাতে পরিবর্তন করেছেন, তাই আপনার অ্যাপ্লিকেশনটিকে প্রচুর আপডেট এবং ডিলিট পাঠানোর মাধ্যমে সার্ভারের সাথে তার স্থানীয় ডেটা সিঙ্ক্রোনাইজ করতে হবে।

প্রতিটি ক্ষেত্রে, প্রতিটি কল আলাদাভাবে পাঠানোর পরিবর্তে, আপনি সেগুলোকে একত্রিত করে একটি একক HTTP অনুরোধ পাঠাতে পারেন। ভেতরের সমস্ত অনুরোধ অবশ্যই একই গুগল এপিআই-তে পাঠাতে হবে।

একটি একক ব্যাচ অনুরোধে আপনি সর্বোচ্চ ১০০টি কল করতে পারবেন। যদি এর চেয়ে বেশি কল করার প্রয়োজন হয়, তবে একাধিক ব্যাচ অনুরোধ ব্যবহার করুন।

দ্রষ্টব্য : Gmail API-এর ব্যাচ সিস্টেমটি OData ব্যাচ প্রসেসিং সিস্টেমের মতোই সিনট্যাক্স ব্যবহার করে, কিন্তু এর অর্থগত তাৎপর্য ভিন্ন।

দ্রষ্টব্য : বড় ব্যাচ সাইজের কারণে রেট লিমিটিং চালু হওয়ার সম্ভাবনা রয়েছে। ৫০টির বেশি অনুরোধের ব্যাচ পাঠানো বাঞ্ছনীয় নয়।

ব্যাচের বিবরণ

একটি ব্যাচ রিকোয়েস্ট হলো একাধিক এপিআই কলকে একত্রিত করে একটিমাত্র HTTP রিকোয়েস্ট, যা এপিআই ডিসকভারি ডকুমেন্টে নির্দিষ্ট করা batchPath এ পাঠানো যায়। ডিফল্ট পাথ হলো /batch/ api_name / api_version । এই অংশে ব্যাচ সিনট্যাক্স বিস্তারিতভাবে বর্ণনা করা হয়েছে; পরে একটি উদাহরণ রয়েছে।

দ্রষ্টব্য : একসাথে ব্যাচ করা n সংখ্যক অনুরোধ আপনার ব্যবহারের সীমার মধ্যে n অনুরোধ হিসাবে গণনা করা হয়, একটি অনুরোধ হিসাবে নয়। প্রক্রিয়াকরণের আগে ব্যাচ অনুরোধটি একাধিক অনুরোধে বিভক্ত করা হয়।

ব্যাচ অনুরোধের ফরম্যাট

ব্যাচ রিকোয়েস্ট হলো একটি একক স্ট্যান্ডার্ড HTTP রিকোয়েস্ট, যাতে multipart/mixed কন্টেন্ট টাইপ ব্যবহার করে একাধিক জিমেইল এপিআই কল থাকে। সেই মূল HTTP রিকোয়েস্টের প্রতিটি অংশের মধ্যে একটি নেস্টেড HTTP রিকোয়েস্ট থাকে।

প্রতিটি পার্ট তার নিজস্ব Content-Type: application/http HTTP হেডার দিয়ে শুরু হয়। এতে একটি ঐচ্ছিক Content-ID হেডারও থাকতে পারে। তবে, পার্ট হেডারগুলো শুধুমাত্র পার্টটির শুরু চিহ্নিত করার জন্য থাকে; এগুলো নেস্টেড রিকোয়েস্ট থেকে আলাদা। সার্ভার যখন ব্যাচ রিকোয়েস্টটিকে আলাদা আলাদা রিকোয়েস্টে বিভক্ত করে ফেলে, তখন পার্ট হেডারগুলো উপেক্ষা করা হয়।

প্রতিটি অংশের বডি হলো একটি সম্পূর্ণ HTTP রিকোয়েস্ট, যার নিজস্ব ভার্ব, ইউআরএল, হেডার এবং বডি থাকে। HTTP রিকোয়েস্টটিতে অবশ্যই ইউআরএল-এর শুধুমাত্র পাথ অংশটি থাকতে হবে; ব্যাচ রিকোয়েস্টে সম্পূর্ণ ইউআরএল অনুমোদিত নয়।

বাইরের ব্যাচ রিকোয়েস্টের HTTP হেডারগুলো, Content-Type মতো Content- হেডারগুলো ছাড়া, ব্যাচের প্রতিটি রিকোয়েস্টের জন্য প্রযোজ্য হয়। যদি আপনি বাইরের রিকোয়েস্ট এবং একটি স্বতন্ত্র কল উভয় ক্ষেত্রেই একটি নির্দিষ্ট HTTP হেডার উল্লেখ করেন, তাহলে স্বতন্ত্র কলের হেডারের মান বাইরের ব্যাচ রিকোয়েস্টের হেডারের মানকে ওভাররাইড করবে। একটি স্বতন্ত্র কলের হেডারগুলো শুধুমাত্র সেই কলের জন্যই প্রযোজ্য হয়।

উদাহরণস্বরূপ, যদি আপনি কোনো নির্দিষ্ট কলের জন্য একটি Authorization হেডার প্রদান করেন, তাহলে সেই হেডারটি শুধুমাত্র সেই কলের ক্ষেত্রেই প্রযোজ্য হবে। যদি আপনি বাইরের অনুরোধের জন্য একটি Authorization হেডার প্রদান করেন, তাহলে সেই হেডারটি সমস্ত স্বতন্ত্র কলের ক্ষেত্রেই প্রযোজ্য হবে, যদি না তারা তাদের নিজস্ব Authorization হেডার দিয়ে সেটিকে ওভাররাইড করে।

সার্ভার যখন ব্যাচ করা অনুরোধটি গ্রহণ করে, তখন এটি বাইরের অনুরোধের কোয়েরি প্যারামিটার এবং হেডারগুলো (প্রয়োজন অনুযায়ী) প্রতিটি অংশে প্রয়োগ করে এবং তারপর প্রতিটি অংশকে একটি পৃথক HTTP অনুরোধ হিসেবে বিবেচনা করে।

ব্যাচ অনুরোধের প্রতিক্রিয়া

সার্ভারের প্রতিক্রিয়াটি হলো multipart/mixed কন্টেন্ট টাইপের একটি একক স্ট্যান্ডার্ড HTTP প্রতিক্রিয়া; এর প্রতিটি অংশ হলো ব্যাচ করা অনুরোধগুলোর যেকোনো একটির প্রতিক্রিয়া, যা অনুরোধগুলোর ক্রমানুসারেই সাজানো থাকে।

রিকোয়েস্টের অংশগুলোর মতোই, প্রতিটি রেসপন্স পার্টে একটি সম্পূর্ণ HTTP রেসপন্স থাকে, যার মধ্যে স্ট্যাটাস কোড, হেডার এবং বডি অন্তর্ভুক্ত। এবং রিকোয়েস্টের অংশগুলোর মতোই, প্রতিটি রেসপন্স পার্টের আগে একটি Content-Type হেডার থাকে যা পার্টটির শুরু নির্দেশ করে।

যদি অনুরোধের কোনো নির্দিষ্ট অংশে একটি Content-ID হেডার থাকে, তাহলে প্রতিক্রিয়ার সংশ্লিষ্ট অংশেও একটি অনুরূপ Content-ID হেডার থাকে, যার মূল মানের আগে response- স্ট্রিংটি যুক্ত থাকে, যেমনটি নিম্নলিখিত উদাহরণে দেখানো হয়েছে।

দ্রষ্টব্য : সার্ভার আপনার কলগুলো যেকোনো ক্রমে সম্পাদন করতে পারে। আপনি যে ক্রমে কলগুলো নির্দিষ্ট করেছেন, সেই ক্রমেই যে সেগুলো সম্পাদিত হবে, তার উপর নির্ভর করবেন না। যদি আপনি নিশ্চিত করতে চান যে দুটি কল একটি নির্দিষ্ট ক্রমে সম্পন্ন হবে, তবে আপনি সেগুলোকে একটিমাত্র অনুরোধে পাঠাতে পারবেন না; এর পরিবর্তে, প্রথমে শুধু প্রথমটি পাঠান, এবং দ্বিতীয়টি পাঠানোর আগে সেটির প্রতিক্রিয়ার জন্য অপেক্ষা করুন।

উদাহরণ

নিম্নলিখিত উদাহরণটি ফার্ম এপিআই (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--