ব্যাচ অনুরোধ

এই নথিটি দেখায় যে কীভাবে আপনার ক্লায়েন্টকে সংযোগ করতে হবে তা কমাতে API কলগুলিকে একসাথে ব্যাচ করতে হয়। ব্যাচিং নেটওয়ার্ক রাউন্ড ট্রিপ কমিয়ে এবং থ্রুপুট বাড়িয়ে একটি অ্যাপ্লিকেশনের দক্ষতা উন্নত করতে পারে।

ওভারভিউ

প্রতিটি সংযোগ আপনার ক্লায়েন্ট একটি নির্দিষ্ট পরিমাণ ওভারহেড ফলাফল করে। Google ডক্স এপিআই আপনার ক্লায়েন্টকে একাধিক অনুরোধ অবজেক্ট রাখতে দিতে ব্যাচিং সমর্থন করে, প্রতিটি একটি একক ব্যাচ অনুরোধে সঞ্চালনের জন্য একক ধরনের অনুরোধ নির্দিষ্ট করে। একটি ব্যাচ অনুরোধ সার্ভারে একটি একক কলে একাধিক সাব-রিকোয়েস্ট একত্রিত করে, একটি একক প্রতিক্রিয়া ফিরিয়ে এনে কর্মক্ষমতা বাড়াতে পারে।

আমরা ব্যবহারকারীদের সবসময় একসাথে একাধিক অনুরোধ ব্যাচ করতে উত্সাহিত করি। এখানে এমন কিছু উদাহরণ রয়েছে যেখানে আপনি ব্যাচিং ব্যবহার করতে পারেন:

  • আপনি সবেমাত্র API ব্যবহার শুরু করেছেন এবং আপলোড করার জন্য আপনার কাছে প্রচুর ডেটা আছে।
  • আপনাকে একাধিক অবজেক্টে মেটাডেটা বা বৈশিষ্ট্য আপডেট করতে হবে, যেমন ফর্ম্যাটিং।
  • আপনাকে অনেক বস্তু মুছে ফেলতে হবে।

সীমা, অনুমোদন, এবং নির্ভরতা বিবেচনা

ব্যাচ আপডেট করার সময় বিবেচনা করার জন্য এখানে অন্যান্য আইটেমগুলির একটি তালিকা রয়েছে:

  • প্রতিটি ব্যাচের অনুরোধ, সমস্ত সাবরিকোয়েস্ট সহ, আপনার ব্যবহারের সীমার দিকে একটি API অনুরোধ হিসাবে গণনা করা হয়।
  • একটি ব্যাচ অনুরোধ একবার প্রমাণীকৃত হয়. এই একক প্রমাণীকরণ অনুরোধের সমস্ত ব্যাচ আপডেট অবজেক্টের ক্ষেত্রে প্রযোজ্য।
  • সার্ভার সাবরিকোয়েস্টগুলিকে একই ক্রমে প্রক্রিয়া করে যেগুলি ব্যাচের অনুরোধে প্রদর্শিত হয়। পরবর্তী সাবরিকোয়েস্টগুলি পূর্ববর্তী সাবরিকোয়েস্টের সময় নেওয়া পদক্ষেপের উপর নির্ভর করতে পারে। উদাহরণস্বরূপ, একই ব্যাচের অনুরোধে, ব্যবহারকারীরা একটি বিদ্যমান নথিতে পাঠ্য সন্নিবেশ করতে পারে এবং তারপরে এটি স্টাইল করতে পারে।

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

একটি ব্যাচ অনুরোধে একাধিক সাব-রিকোয়েস্ট সহ একটি batchUpdate পদ্ধতি কল থাকে, উদাহরণস্বরূপ, একটি ডকুমেন্ট যোগ করুন এবং তারপরে ফর্ম্যাট করুন৷

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

কিছু অনুরোধ প্রয়োগ করা অনুরোধ সম্পর্কে তথ্য সহ প্রতিক্রিয়া প্রদান করে। উদাহরণ স্বরূপ, অবজেক্ট যোগ করার জন্য সমস্ত ব্যাচ আপডেট রিকুয়েস্ট রিটার্ন দেয় যাতে আপনি নতুন যোগ করা অবজেক্টের মেটাডেটা অ্যাক্সেস করতে পারেন, যেমন আইডি বা শিরোনাম।

এই পদ্ধতির সাহায্যে, আপনি একাধিক সাবরিকোয়েস্ট সহ একটি API ব্যাচ আপডেট অনুরোধ ব্যবহার করে একটি সম্পূর্ণ Google নথি তৈরি করতে পারেন।

একটি ব্যাচ অনুরোধের বিন্যাস

একটি অনুরোধ হল একটি একক JSON অনুরোধ যাতে একাধিক, একটি প্রয়োজনীয় সম্পত্তি সহ নেস্টেড সাব-রিকোয়েস্ট থাকে: requests । অনুরোধগুলি পৃথক অনুরোধের অ্যারেতে তৈরি করা হয়। প্রতিটি অনুরোধ অনুরোধ বস্তুর প্রতিনিধিত্ব করতে এবং এর বৈশিষ্ট্যগুলি ধারণ করতে JSON ব্যবহার করে।

একটি ব্যাচ প্রতিক্রিয়া বিন্যাস

একটি ব্যাচ অনুরোধের প্রতিক্রিয়া বিন্যাস অনুরোধ বিন্যাসের অনুরূপ। সার্ভারের প্রতিক্রিয়া একক প্রতিক্রিয়া বস্তুর একটি সম্পূর্ণ উত্তর ধারণ করে।

প্রধান JSON অবজেক্টের সম্পত্তির নাম দেওয়া হয় replies । প্রতিক্রিয়াগুলি একটি অ্যারেতে ফেরত দেওয়া হয়, প্রতিটি অনুরোধের প্রতিটি প্রতিক্রিয়া সংশ্লিষ্ট অনুরোধের মতো একই সূচক ক্রম দখল করে। কিছু অনুরোধের প্রতিক্রিয়া নেই এবং সেই অ্যারে সূচকে প্রতিক্রিয়া খালি।

উদাহরণ

নিম্নলিখিত কোড নমুনা ডক্স API এর সাথে ব্যাচিংয়ের ব্যবহার দেখায়।

অনুরোধ

এই উদাহরণ ব্যাচ অনুরোধটি দেখায় কিভাবে:

  • একটি বিদ্যমান নথির শুরুতে "হ্যালো ওয়ার্ল্ড" পাঠ্য সন্নিবেশ করান, 1 এর একটি সূচক location সহ, InsertTextRequest ব্যবহার করে।

  • UpdateTextStyleRequest ব্যবহার করে "হ্যালো" শব্দটি আপডেট করুন। startIndex এবং endIndex সেগমেন্টের মধ্যে ফর্ম্যাট করা পাঠ্যের range নির্ধারণ করে।

  • textStyle ব্যবহার করে, "হ্যালো" শব্দের জন্য ফন্ট স্টাইলটিকে বোল্ড এবং রঙটি নীলে সেট করুন।

  • 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 প্রতিস্থাপন করুন।

প্রতিক্রিয়া

এই উদাহরণ ব্যাচ প্রতিক্রিয়া ব্যাচ অনুরোধের মধ্যে প্রতিটি subrequest প্রয়োগ করা হয়েছে কিভাবে তথ্য প্রদর্শন করে. InsertTextRequest বা UpdateTextStyleRequest কোনোটিতেই কোনো প্রতিক্রিয়া নেই, তাই [0] এবং [1]-এ থাকা অ্যারের সূচকের মানগুলি খালি কোঁকড়া বন্ধনী নিয়ে গঠিত। ব্যাচ অনুরোধ WriteControl অবজেক্ট প্রদর্শন করে, যা দেখায় কিভাবে অনুরোধগুলি কার্যকর করা হয়েছিল।

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}