এই ডকুমেন্টটিতে দেখানো হয়েছে কীভাবে এপিআই কলগুলোকে একসাথে ব্যাচ করে আপনার ক্লায়েন্টকে কম সংখ্যক কানেকশন করতে হয়। ব্যাচিং নেটওয়ার্ক রাউন্ড ট্রিপ কমিয়ে এবং থ্রুপুট বাড়িয়ে একটি অ্যাপ্লিকেশনের কর্মদক্ষতা উন্নত করতে পারে।
সংক্ষিপ্ত বিবরণ
আপনার ক্লায়েন্টের প্রতিটি সংযোগের ফলে একটি নির্দিষ্ট পরিমাণ ওভারহেড তৈরি হয়। গুগল ডক্স এপিআই ব্যাচিং সমর্থন করে, যা আপনার ক্লায়েন্টকে একাধিক রিকোয়েস্ট অবজেক্টকে একটি একক ব্যাচ রিকোয়েস্টে রাখার সুযোগ দেয়, যেখানে প্রতিটি অবজেক্ট একটি নির্দিষ্ট ধরনের অনুরোধ সম্পাদনের জন্য নির্দেশ করে। একটি ব্যাচ রিকোয়েস্ট একাধিক সাব-রিকোয়েস্টকে একত্রিত করে সার্ভারে একটি একক কলে পরিণত করে এবং একটিমাত্র প্রতিক্রিয়া ফিরিয়ে এনে পারফরম্যান্স বাড়াতে পারে।
আমরা ব্যবহারকারীদের সর্বদা একাধিক অনুরোধ একসাথে ব্যাচ করতে উৎসাহিত করি। এখানে এমন কিছু পরিস্থিতির উদাহরণ দেওয়া হলো যেখানে আপনি ব্যাচিং ব্যবহার করতে পারেন:
- আপনি এইমাত্র এপিআই ব্যবহার করা শুরু করেছেন এবং আপনার কাছে আপলোড করার জন্য প্রচুর ডেটা রয়েছে।
- আপনাকে একাধিক অবজেক্টের মেটাডেটা বা ফরম্যাটিং-এর মতো প্রোপার্টি আপডেট করতে হবে।
- আপনাকে অনেকগুলো অবজেক্ট মুছে ফেলতে হবে।
সীমাবদ্ধতা, অনুমোদন, এবং নির্ভরশীলতার বিবেচ্য বিষয়
ব্যাচ আপডেটিং প্রয়োগ করার সময় বিবেচনা করার মতো অন্যান্য বিষয়গুলির একটি তালিকা নিচে দেওয়া হলো:
- সমস্ত উপ-অনুরোধ সহ প্রতিটি ব্যাচ অনুরোধ আপনার ব্যবহারের সীমার ক্ষেত্রে একটি এপিআই অনুরোধ হিসাবে গণনা করা হয়।
- একটি ব্যাচ অনুরোধ একবার প্রমাণীকরণ করা হয়। এই একক প্রমাণীকরণটি অনুরোধের সমস্ত ব্যাচ আপডেট অবজেক্টের ক্ষেত্রে প্রযোজ্য।
- সার্ভার সাব-রিকোয়েস্টগুলোকে ব্যাচ রিকোয়েস্টে যে ক্রমে থাকে, ঠিক সেই ক্রমেই প্রসেস করে। পরবর্তী সাব-রিকোয়েস্টগুলো পূর্ববর্তী সাব-রিকোয়েস্টগুলোর সময় নেওয়া পদক্ষেপের উপর নির্ভর করতে পারে। উদাহরণস্বরূপ, একই ব্যাচ রিকোয়েস্টে, ব্যবহারকারীরা একটি বিদ্যমান ডকুমেন্টে টেক্সট যোগ করতে এবং তারপর সেটিকে স্টাইল করতে পারেন।
ব্যাচের বিবরণ
একটি ব্যাচ রিকোয়েস্টে একটি batchUpdate মেথড কল থাকে, যার অধীনে একাধিক সাব-রিকোয়েস্ট থাকে, যেমন—একটি ডকুমেন্ট যোগ করা এবং তারপর সেটিকে ফরম্যাট করার জন্য।
প্রয়োগ করার আগে প্রতিটি অনুরোধ যাচাই করা হয়। ব্যাচ আপডেটের সমস্ত উপ-অনুরোধ অ্যাটমিকভাবে প্রয়োগ করা হয়। অর্থাৎ, যদি কোনো অনুরোধ বৈধ না হয়, তাহলে সম্পূর্ণ আপডেটটি অসফল হয় এবং (সম্ভাব্য নির্ভরশীল) কোনো পরিবর্তনই প্রয়োগ করা হয় না।
কিছু অনুরোধের প্রতিক্রিয়ায় প্রয়োগকৃত অনুরোধগুলো সম্পর্কে তথ্য পাওয়া যায়। উদাহরণস্বরূপ, অবজেক্ট যোগ করার সমস্ত ব্যাচ আপডেট অনুরোধ এমন প্রতিক্রিয়া ফেরত দেয়, যার মাধ্যমে আপনি নতুন যোগ করা অবজেক্টের মেটাডেটা, যেমন আইডি বা শিরোনাম, অ্যাক্সেস করতে পারেন।
এই পদ্ধতির মাধ্যমে, আপনি একাধিক উপ-অনুরোধ সহ একটিমাত্র এপিআই ব্যাচ আপডেট অনুরোধ ব্যবহার করে একটি সম্পূর্ণ গুগল ডকুমেন্ট তৈরি করতে পারেন।
ব্যাচ অনুরোধের ফরম্যাট
একটি রিকোয়েস্ট হলো একটি একক JSON রিকোয়েস্ট, যার মধ্যে একাধিক নেস্টেড সাব-রিকোয়েস্ট থাকে এবং এতে requests নামক একটি আবশ্যিক প্রপার্টি থাকে। রিকোয়েস্টগুলো স্বতন্ত্র রিকোয়েস্টের একটি অ্যারে হিসেবে গঠিত হয়। প্রতিটি রিকোয়েস্ট, রিকোয়েস্ট অবজেক্টকে উপস্থাপন করতে এবং এর প্রপার্টিগুলো ধারণ করতে JSON ব্যবহার করে।
ব্যাচ প্রতিক্রিয়ার বিন্যাস
ব্যাচ রিকোয়েস্টের রেসপন্স ফরম্যাটটি রিকোয়েস্ট ফরম্যাটের মতোই। সার্ভারের রেসপন্সে একটিমাত্র রেসপন্স অবজেক্টের সম্পূর্ণ উত্তর থাকে।
মূল JSON অবজেক্টের প্রপার্টির নাম হলো replies । রেসপন্সগুলো একটি অ্যারেতে ফেরত দেওয়া হয়, যেখানে প্রতিটি রিকোয়েস্টের রেসপন্স সংশ্লিষ্ট রিকোয়েস্টের ইন্ডেক্স ক্রমেই থাকে। কিছু রিকোয়েস্টের কোনো রেসপন্স থাকে না এবং সেই অ্যারে ইন্ডেক্সের রেসপন্সটি খালি থাকে।
উদাহরণ
নিম্নলিখিত কোড নমুনাটি Docs API-এর সাথে ব্যাচিং-এর ব্যবহার দেখায়।
অনুরোধ
এই উদাহরণ ব্যাচ অনুরোধটি দেখায় কিভাবে:
InsertTextRequestব্যবহার করে, বিদ্যমান ডকুমেন্টের শুরুতে1ইনডেক্সlocation"Hello World" লেখাটি সন্নিবেশ করুন।UpdateTextStyleRequestব্যবহার করে 'Hello' শব্দটি আপডেট করুন।startIndexএবংendIndexসেগমেন্টের মধ্যে ফরম্যাট করা টেক্সটেরrangeনির্ধারণ করে।textStyleব্যবহার করে, শুধুমাত্র 'Hello' শব্দটির জন্য ফন্ট স্টাইল বোল্ড এবং রঙ নীল সেট করুন।WriteControlফিল্ড ব্যবহার করে, আপনি রাইট রিকোয়েস্টগুলো কীভাবে এক্সিকিউট করা হবে তা নিয়ন্ত্রণ করতে পারেন। আরও তথ্যের জন্য, WriteControl-এর মাধ্যমে স্টেট কনসিস্টেন্সি প্রতিষ্ঠা দেখুন।
{ "requests":[ { "insertText":{ "location":{ "index":1, "tabId":TAB_ID }, "text":"Hello World" } }, { "updateTextStyle":{ "range":{ "startIndex":1, "endIndex":6 }, "textStyle":{ "bold":true, "foregroundColor":{ "color":{ "rgbColor":{ "blue":1 } } } }, "fields":"bold,foreground_color" } } ], "writeControl": { "requiredRevisionId": "REQUIRED_REVISION_ID" } }
যে ডকুমেন্টের উপর লেখার অনুরোধটি প্রয়োগ করা হয়েছে, তার ট্যাব আইডি এবং রিভিশন আইডি দিয়ে যথাক্রমে TAB_ID এবং REQUIRED_REVISION_ID প্রতিস্থাপন করুন।
প্রতিক্রিয়া
এই উদাহরণ ব্যাচ রেসপন্সটি দেখায় যে ব্যাচ রিকোয়েস্টের ভেতরের প্রতিটি সাব-রিকোয়েস্ট কীভাবে প্রয়োগ করা হয়েছিল। InsertTextRequest বা UpdateTextStyleRequest কোনোটিতেই কোনো রেসপন্স নেই, তাই অ্যারের [0] এবং [1] ইনডেক্স মানগুলো খালি কার্লি ব্র্যাকেট দিয়ে গঠিত। ব্যাচ রিকোয়েস্টটি WriteControl অবজেক্টটি প্রদর্শন করে, যা দেখায় রিকোয়েস্টগুলো কীভাবে এক্সিকিউট করা হয়েছিল।
{ "replies":[ {}, {} ], "writeControl":{ "requiredRevisionId":`REQUIRED_REVISION_ID` }, "documentId":`DOCUMENT_ID` }
সম্পর্কিত বিষয়
,এই ডকুমেন্টটিতে দেখানো হয়েছে কীভাবে এপিআই কলগুলোকে একসাথে ব্যাচ করে আপনার ক্লায়েন্টকে কম সংখ্যক কানেকশন করতে হয়। ব্যাচিং নেটওয়ার্ক রাউন্ড ট্রিপ কমিয়ে এবং থ্রুপুট বাড়িয়ে একটি অ্যাপ্লিকেশনের কর্মদক্ষতা উন্নত করতে পারে।
সংক্ষিপ্ত বিবরণ
আপনার ক্লায়েন্টের প্রতিটি সংযোগের ফলে একটি নির্দিষ্ট পরিমাণ ওভারহেড তৈরি হয়। গুগল ডক্স এপিআই ব্যাচিং সমর্থন করে, যা আপনার ক্লায়েন্টকে একাধিক রিকোয়েস্ট অবজেক্টকে একটি একক ব্যাচ রিকোয়েস্টে রাখার সুযোগ দেয়, যেখানে প্রতিটি অবজেক্ট একটি নির্দিষ্ট ধরনের অনুরোধ সম্পাদনের জন্য নির্দেশ করে। একটি ব্যাচ রিকোয়েস্ট একাধিক সাব-রিকোয়েস্টকে একত্রিত করে সার্ভারে একটি একক কলে পরিণত করে এবং একটিমাত্র প্রতিক্রিয়া ফিরিয়ে এনে পারফরম্যান্স বাড়াতে পারে।
আমরা ব্যবহারকারীদের সর্বদা একাধিক অনুরোধ একসাথে ব্যাচ করতে উৎসাহিত করি। এখানে এমন কিছু পরিস্থিতির উদাহরণ দেওয়া হলো যেখানে আপনি ব্যাচিং ব্যবহার করতে পারেন:
- আপনি এইমাত্র এপিআই ব্যবহার করা শুরু করেছেন এবং আপনার কাছে আপলোড করার জন্য প্রচুর ডেটা রয়েছে।
- আপনাকে একাধিক অবজেক্টের মেটাডেটা বা ফরম্যাটিং-এর মতো প্রোপার্টি আপডেট করতে হবে।
- আপনাকে অনেকগুলো অবজেক্ট মুছে ফেলতে হবে।
সীমাবদ্ধতা, অনুমোদন, এবং নির্ভরশীলতার বিবেচ্য বিষয়
ব্যাচ আপডেটিং প্রয়োগ করার সময় বিবেচনা করার মতো অন্যান্য বিষয়গুলির একটি তালিকা নিচে দেওয়া হলো:
- সমস্ত উপ-অনুরোধ সহ প্রতিটি ব্যাচ অনুরোধ আপনার ব্যবহারের সীমার ক্ষেত্রে একটি এপিআই অনুরোধ হিসাবে গণনা করা হয়।
- একটি ব্যাচ অনুরোধ একবার প্রমাণীকরণ করা হয়। এই একক প্রমাণীকরণটি অনুরোধের সমস্ত ব্যাচ আপডেট অবজেক্টের ক্ষেত্রে প্রযোজ্য।
- সার্ভার সাব-রিকোয়েস্টগুলোকে ব্যাচ রিকোয়েস্টে যে ক্রমে থাকে, ঠিক সেই ক্রমেই প্রসেস করে। পরবর্তী সাব-রিকোয়েস্টগুলো পূর্ববর্তী সাব-রিকোয়েস্টগুলোর সময় নেওয়া পদক্ষেপের উপর নির্ভর করতে পারে। উদাহরণস্বরূপ, একই ব্যাচ রিকোয়েস্টে, ব্যবহারকারীরা একটি বিদ্যমান ডকুমেন্টে টেক্সট যোগ করতে এবং তারপর সেটিকে স্টাইল করতে পারেন।
ব্যাচের বিবরণ
একটি ব্যাচ রিকোয়েস্টে একটি batchUpdate মেথড কল থাকে, যার অধীনে একাধিক সাব-রিকোয়েস্ট থাকে, যেমন—একটি ডকুমেন্ট যোগ করা এবং তারপর সেটিকে ফরম্যাট করার জন্য।
প্রয়োগ করার আগে প্রতিটি অনুরোধ যাচাই করা হয়। ব্যাচ আপডেটের সমস্ত উপ-অনুরোধ অ্যাটমিকভাবে প্রয়োগ করা হয়। অর্থাৎ, যদি কোনো অনুরোধ বৈধ না হয়, তাহলে সম্পূর্ণ আপডেটটি অসফল হয় এবং (সম্ভাব্য নির্ভরশীল) কোনো পরিবর্তনই প্রয়োগ করা হয় না।
কিছু অনুরোধের প্রতিক্রিয়ায় প্রয়োগকৃত অনুরোধগুলো সম্পর্কে তথ্য পাওয়া যায়। উদাহরণস্বরূপ, অবজেক্ট যোগ করার সমস্ত ব্যাচ আপডেট অনুরোধ এমন প্রতিক্রিয়া ফেরত দেয়, যার মাধ্যমে আপনি নতুন যোগ করা অবজেক্টের মেটাডেটা, যেমন আইডি বা শিরোনাম, অ্যাক্সেস করতে পারেন।
এই পদ্ধতির মাধ্যমে, আপনি একাধিক উপ-অনুরোধ সহ একটিমাত্র এপিআই ব্যাচ আপডেট অনুরোধ ব্যবহার করে একটি সম্পূর্ণ গুগল ডকুমেন্ট তৈরি করতে পারেন।
ব্যাচ অনুরোধের ফরম্যাট
একটি রিকোয়েস্ট হলো একটি একক JSON রিকোয়েস্ট, যার মধ্যে একাধিক নেস্টেড সাব-রিকোয়েস্ট থাকে এবং এতে requests নামক একটি আবশ্যিক প্রপার্টি থাকে। রিকোয়েস্টগুলো স্বতন্ত্র রিকোয়েস্টের একটি অ্যারে হিসেবে গঠিত হয়। প্রতিটি রিকোয়েস্ট, রিকোয়েস্ট অবজেক্টকে উপস্থাপন করতে এবং এর প্রপার্টিগুলো ধারণ করতে JSON ব্যবহার করে।
ব্যাচ প্রতিক্রিয়ার বিন্যাস
ব্যাচ রিকোয়েস্টের রেসপন্স ফরম্যাটটি রিকোয়েস্ট ফরম্যাটের মতোই। সার্ভারের রেসপন্সে একটিমাত্র রেসপন্স অবজেক্টের সম্পূর্ণ উত্তর থাকে।
মূল JSON অবজেক্টের প্রপার্টির নাম হলো replies । রেসপন্সগুলো একটি অ্যারেতে ফেরত দেওয়া হয়, যেখানে প্রতিটি রিকোয়েস্টের রেসপন্স সংশ্লিষ্ট রিকোয়েস্টের ইন্ডেক্স ক্রমেই থাকে। কিছু রিকোয়েস্টের কোনো রেসপন্স থাকে না এবং সেই অ্যারে ইন্ডেক্সের রেসপন্সটি খালি থাকে।
উদাহরণ
নিম্নলিখিত কোড নমুনাটি Docs API-এর সাথে ব্যাচিং-এর ব্যবহার দেখায়।
অনুরোধ
এই উদাহরণ ব্যাচ অনুরোধটি দেখায় কিভাবে:
InsertTextRequestব্যবহার করে, বিদ্যমান ডকুমেন্টের শুরুতে1ইনডেক্সlocation"Hello World" লেখাটি সন্নিবেশ করুন।UpdateTextStyleRequestব্যবহার করে 'Hello' শব্দটি আপডেট করুন।startIndexএবংendIndexসেগমেন্টের মধ্যে ফরম্যাট করা টেক্সটেরrangeনির্ধারণ করে।textStyleব্যবহার করে, শুধুমাত্র 'Hello' শব্দটির জন্য ফন্ট স্টাইল বোল্ড এবং রঙ নীল সেট করুন।WriteControlফিল্ড ব্যবহার করে, আপনি রাইট রিকোয়েস্টগুলো কীভাবে এক্সিকিউট করা হবে তা নিয়ন্ত্রণ করতে পারেন। আরও তথ্যের জন্য, WriteControl-এর মাধ্যমে স্টেট কনসিস্টেন্সি প্রতিষ্ঠা দেখুন।
{ "requests":[ { "insertText":{ "location":{ "index":1, "tabId":TAB_ID }, "text":"Hello World" } }, { "updateTextStyle":{ "range":{ "startIndex":1, "endIndex":6 }, "textStyle":{ "bold":true, "foregroundColor":{ "color":{ "rgbColor":{ "blue":1 } } } }, "fields":"bold,foreground_color" } } ], "writeControl": { "requiredRevisionId": "REQUIRED_REVISION_ID" } }
যে ডকুমেন্টের উপর লেখার অনুরোধটি প্রয়োগ করা হয়েছে, তার ট্যাব আইডি এবং রিভিশন আইডি দিয়ে যথাক্রমে TAB_ID এবং REQUIRED_REVISION_ID প্রতিস্থাপন করুন।
প্রতিক্রিয়া
এই উদাহরণ ব্যাচ রেসপন্সটি দেখায় যে ব্যাচ রিকোয়েস্টের ভেতরের প্রতিটি সাব-রিকোয়েস্ট কীভাবে প্রয়োগ করা হয়েছিল। InsertTextRequest বা UpdateTextStyleRequest কোনোটিতেই কোনো রেসপন্স নেই, তাই অ্যারের [0] এবং [1] ইনডেক্স মানগুলো খালি কার্লি ব্র্যাকেট দিয়ে গঠিত। ব্যাচ রিকোয়েস্টটি WriteControl অবজেক্টটি প্রদর্শন করে, যা দেখায় রিকোয়েস্টগুলো কীভাবে এক্সিকিউট করা হয়েছিল।
{ "replies":[ {}, {} ], "writeControl":{ "requiredRevisionId":`REQUIRED_REVISION_ID` }, "documentId":`DOCUMENT_ID` }