পারফরম্যান্সের উন্নতি

এই নথিতে এমন কিছু কৌশল রয়েছে যা আপনি আপনার অ্যাপ্লিকেশনের কর্মক্ষমতা উন্নত করতে ব্যবহার করতে পারেন। কিছু ক্ষেত্রে, উপস্থাপিত ধারণাগুলিকে চিত্রিত করতে অন্যান্য API বা জেনেরিক API-এর উদাহরণ ব্যবহার করা হয়। যাইহোক, একই ধারণাগুলি Google ড্রাইভ API এর ক্ষেত্রে প্রযোজ্য।

জিজিপ ব্যবহার করে কম্প্রেশন

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

একটি gzip-এনকোড করা প্রতিক্রিয়া পাওয়ার জন্য আপনাকে দুটি জিনিস করতে হবে: একটি Accept-Encoding শিরোনাম সেট করুন এবং স্ট্রিং gzip ধারণ করতে আপনার ব্যবহারকারী এজেন্টকে পরিবর্তন করুন। এখানে gzip কম্প্রেশন সক্ষম করার জন্য সঠিকভাবে গঠিত HTTP হেডারগুলির একটি উদাহরণ রয়েছে: 

Accept-Encoding: gzip
User-Agent: my program (gzip)

আংশিক সম্পদ নিয়ে কাজ করা

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

দুই ধরনের আংশিক অনুরোধ আছে:

  • আংশিক প্রতিক্রিয়া : একটি অনুরোধ যেখানে আপনি প্রতিক্রিয়াতে কোন ক্ষেত্রগুলি অন্তর্ভুক্ত করতে হবে তা নির্দিষ্ট করেন ( fields অনুরোধের প্যারামিটার ব্যবহার করুন)।
  • প্যাচ : একটি আপডেট অনুরোধ যেখানে আপনি শুধুমাত্র যে ক্ষেত্রগুলি পরিবর্তন করতে চান তা পাঠান ( PATCH HTTP ক্রিয়া ব্যবহার করুন)।

আংশিক অনুরোধ করার বিষয়ে আরও বিশদ নিম্নলিখিত বিভাগে দেওয়া হয়েছে।

আংশিক প্রতিক্রিয়া

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

একটি আংশিক প্রতিক্রিয়া অনুরোধ করতে, আপনি যে ক্ষেত্রগুলি ফেরত দিতে চান তা নির্দিষ্ট করতে fields অনুরোধ প্যারামিটার ব্যবহার করুন৷ আপনি এই প্যারামিটারটি যেকোন অনুরোধের সাথে ব্যবহার করতে পারেন যা প্রতিক্রিয়া ডেটা প্রদান করে।

মনে রাখবেন যে fields প্যারামিটার শুধুমাত্র প্রতিক্রিয়া ডেটা প্রভাবিত করে; এটি আপনাকে যে ডেটা পাঠাতে হবে তা প্রভাবিত করে না, যদি থাকে। সম্পদ পরিবর্তন করার সময় আপনার পাঠানো ডেটার পরিমাণ কমাতে, একটি প্যাচ অনুরোধ ব্যবহার করুন।

উদাহরণ

নিম্নলিখিত উদাহরণটি একটি জেনেরিক (কাল্পনিক) "ডেমো" API সহ fields প্যারামিটারের ব্যবহার দেখায়৷

সহজ অনুরোধ: এই HTTP GET অনুরোধটি fields পরামিতি বাদ দেয় এবং সম্পূর্ণ সংস্থান প্রদান করে।

https://www.googleapis.com/demo/v1

সম্পূর্ণ রিসোর্স প্রতিক্রিয়া: সম্পূর্ণ রিসোর্স ডেটাতে নিম্নলিখিত ক্ষেত্রগুলি অন্তর্ভুক্ত রয়েছে, সাথে আরও অনেকগুলি যা সংক্ষিপ্ততার জন্য বাদ দেওয়া হয়েছে৷

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

একটি আংশিক প্রতিক্রিয়ার জন্য অনুরোধ: এই একই সংস্থানের জন্য নিম্নলিখিত অনুরোধটি ফিরে আসা ডেটার পরিমাণ উল্লেখযোগ্যভাবে হ্রাস করতে fields প্যারামিটার ব্যবহার করে।

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

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

200 OK
{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

মনে রাখবেন যে প্রতিক্রিয়াটি একটি JSON অবজেক্ট যা শুধুমাত্র নির্বাচিত ক্ষেত্র এবং তাদের আবদ্ধ অভিভাবক বস্তুগুলিকে অন্তর্ভুক্ত করে।

fields পরামিতি কীভাবে ফর্ম্যাট করবেন তার বিশদ বিবরণ পরবর্তীতে কভার করা হয়েছে, তারপরে প্রতিক্রিয়াতে ঠিক কী ফেরত দেওয়া হয় সে সম্পর্কে আরও বিশদ অনুসরণ করা হয়েছে।

ফিল্ড প্যারামিটার সিনট্যাক্স সারাংশ

fields অনুরোধ প্যারামিটার মান বিন্যাস শিথিলভাবে XPath সিনট্যাক্সের উপর ভিত্তি করে। সমর্থিত সিনট্যাক্স নীচে সংক্ষিপ্ত করা হয়েছে, এবং অতিরিক্ত উদাহরণ নিম্নলিখিত বিভাগে প্রদান করা হয়েছে.

  • একাধিক ক্ষেত্র নির্বাচন করতে একটি কমা-বিচ্ছিন্ন তালিকা ব্যবহার করুন।
  • a ক্ষেত্রের মধ্যে নেস্ট করা একটি ক্ষেত্র b নির্বাচন করতে a/b ব্যবহার করুন; b এর মধ্যে c নেস্টেড একটি ক্ষেত্র নির্বাচন করতে a/b/c ব্যবহার করুন।

    ব্যতিক্রম: API প্রতিক্রিয়াগুলির জন্য যেগুলি "ডেটা" র্যাপার ব্যবহার করে, যেখানে প্রতিক্রিয়াটি data অবজেক্টের মধ্যে নেস্ট করা হয় যা data: { ... } , fields স্পেসিফিকেশনে " data " অন্তর্ভুক্ত করবেন না৷ data/a/b এর মতো ফিল্ড স্পেসিফিকেশন সহ ডেটা অবজেক্ট অন্তর্ভুক্ত করলে একটি ত্রুটি ঘটে। পরিবর্তে, শুধু a/b এর মত একটি fields স্পেসিফিকেশন ব্যবহার করুন।

  • " ( ) " বন্ধনীতে অভিব্যক্তি স্থাপন করে অ্যারে বা বস্তুর নির্দিষ্ট উপ-ক্ষেত্রগুলির একটি সেট অনুরোধ করতে একটি উপ-নির্বাচক ব্যবহার করুন।

    উদাহরণস্বরূপ: fields=items(id,author/email) আইটেম অ্যারের প্রতিটি উপাদানের জন্য শুধুমাত্র আইটেম আইডি এবং লেখকের ইমেল প্রদান করে। আপনি একটি একক উপ-ক্ষেত্রও নির্দিষ্ট করতে পারেন, যেখানে fields=items(id) fields=items/id এর সমতুল্য।

  • প্রয়োজনে ক্ষেত্র নির্বাচনে ওয়াইল্ডকার্ড ব্যবহার করুন।

    উদাহরণস্বরূপ: fields=items/pagemap/* একটি পেজম্যাপে সমস্ত বস্তু নির্বাচন করে।

ক্ষেত্র প্যারামিটার ব্যবহার করার আরও উদাহরণ

নীচের উদাহরণগুলিতে fields প্যারামিটার মান প্রতিক্রিয়াকে কীভাবে প্রভাবিত করে তার বর্ণনা অন্তর্ভুক্ত করে।

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

আপনি যে ক্ষেত্রগুলি ফেরত দিতে চান তা চিহ্নিত করুন বা ক্ষেত্র নির্বাচন করুন।
fields অনুরোধ পরামিতি মান হল একটি কমা দ্বারা পৃথক করা ক্ষেত্রগুলির তালিকা, এবং প্রতিটি ক্ষেত্র প্রতিক্রিয়ার মূলের সাপেক্ষে নির্দিষ্ট করা হয়। এইভাবে, যদি আপনি একটি তালিকা অপারেশন সম্পাদন করছেন, প্রতিক্রিয়া একটি সংগ্রহ, এবং এটি সাধারণত সম্পদের একটি অ্যারে অন্তর্ভুক্ত করে। আপনি যদি একটি অপারেশন করছেন যা একটি একক সংস্থান প্রদান করে, ক্ষেত্রগুলি সেই সংস্থানের সাথে সম্পর্কিত নির্দিষ্ট করা হয়। যদি আপনি যে ক্ষেত্রটি নির্বাচন করেন সেটি একটি অ্যারের (বা অংশ) হয়, সার্ভারটি অ্যারের সমস্ত উপাদানের নির্বাচিত অংশ প্রদান করে।

এখানে কিছু সংগ্রহ-স্তরের উদাহরণ রয়েছে:
উদাহরণ প্রভাব
items প্রতিটি উপাদানের সমস্ত ক্ষেত্র সহ আইটেম অ্যারের সমস্ত উপাদান প্রদান করে, কিন্তু অন্য কোনো ক্ষেত্র নেই।
etag,items etag ক্ষেত্র এবং আইটেম অ্যারের সমস্ত উপাদান উভয়ই প্রদান করে।
items/title আইটেম অ্যারের সমস্ত উপাদানের জন্য শুধুমাত্র title ক্ষেত্র প্রদান করে।

যখনই একটি নেস্টেড ক্ষেত্র ফেরত দেওয়া হয়, তখন প্রতিক্রিয়ার মধ্যে বদ্ধ মূল বস্তু অন্তর্ভুক্ত থাকে। অভিভাবক ক্ষেত্রগুলি অন্য কোনও শিশু ক্ষেত্র অন্তর্ভুক্ত করে না যদি না সেগুলিও স্পষ্টভাবে নির্বাচিত হয়৷
context/facets/label facets অ্যারের সমস্ত সদস্যের জন্য শুধুমাত্র label ক্ষেত্রটি ফেরত দেয়, যা নিজেই context অবজেক্টের অধীনে নেস্টেড।
items/pagemap/*/title আইটেম অ্যারের প্রতিটি উপাদানের জন্য, pagemap শিশু সমস্ত বস্তুর শুধুমাত্র title ক্ষেত্র (যদি উপস্থিত থাকে) প্রদান করে।

এখানে কিছু সম্পদ-স্তরের উদাহরণ রয়েছে:
উদাহরণ প্রভাব
title অনুরোধ করা সম্পদের title ক্ষেত্র ফেরত দেয়।
author/uri অনুরোধ করা সম্পদে author অবজেক্টের uri সাব-ফিল্ড ফেরত দেয়।
links/*/href
 links সন্তান যে সমস্ত বস্তুর href ক্ষেত্র দেখায়।
উপ-নির্বাচন ব্যবহার করে শুধুমাত্র নির্দিষ্ট ক্ষেত্রের অংশগুলির জন্য অনুরোধ করুন।
ডিফল্টরূপে, যদি আপনার অনুরোধ নির্দিষ্ট ক্ষেত্র নির্দিষ্ট করে, সার্ভার তাদের সম্পূর্ণরূপে বস্তু বা অ্যারে উপাদান ফেরত দেয়। আপনি একটি প্রতিক্রিয়া নির্দিষ্ট করতে পারেন যাতে শুধুমাত্র কিছু উপ-ক্ষেত্র অন্তর্ভুক্ত থাকে। আপনি " ( ) " উপ-নির্বাচন সিনট্যাক্স ব্যবহার করে এটি করেন, যেমন নীচের উদাহরণে।
উদাহরণ প্রভাব
items(title,author/uri) আইটেম অ্যারের প্রতিটি উপাদানের জন্য শুধুমাত্র title এবং লেখকের uri মান প্রদান করে।

আংশিক প্রতিক্রিয়া পরিচালনা করা

একটি সার্ভার একটি বৈধ অনুরোধ প্রক্রিয়া করার পরে যাতে fields ক্যোয়ারী প্যারামিটার অন্তর্ভুক্ত থাকে, এটি অনুরোধ করা ডেটা সহ একটি HTTP 200 OK স্ট্যাটাস কোড ফেরত পাঠায়। যদি fields ক্যোয়ারী প্যারামিটারে একটি ত্রুটি থাকে বা অন্যথায় অবৈধ হয়, সার্ভারটি একটি HTTP 400 Bad Request স্ট্যাটাস কোড প্রদান করে, সাথে একটি ত্রুটি বার্তা ব্যবহারকারীকে বলে যে তাদের ক্ষেত্র নির্বাচনের সাথে কী ভুল ছিল (উদাহরণস্বরূপ, "Invalid field selection a/b" )

উপরের পরিচায়ক বিভাগে দেখানো আংশিক প্রতিক্রিয়া উদাহরণ এখানে। কোন ক্ষেত্রগুলি ফেরত দিতে হবে তা নির্দিষ্ট করতে অনুরোধটি fields প্যারামিটার ব্যবহার করে।

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

আংশিক প্রতিক্রিয়া এই মত দেখায়: 

200 OK
{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

দ্রষ্টব্য: ডাটা পেজিনেশনের জন্য ক্যোয়ারী প্যারামিটার সমর্থন করে এমন APIগুলির জন্য ( maxResults এবং nextPageToken , উদাহরণস্বরূপ), প্রতিটি কোয়েরির ফলাফলগুলিকে একটি পরিচালনাযোগ্য আকারে কমাতে সেই প্যারামিটারগুলি ব্যবহার করুন৷ অন্যথায়, আংশিক প্রতিক্রিয়ার সাথে পারফরম্যান্সের লাভগুলি উপলব্ধি করা যাবে না।

প্যাচ (আংশিক আপডেট)

সম্পদ পরিবর্তন করার সময় আপনি অপ্রয়োজনীয় ডেটা পাঠানো এড়াতে পারেন। আপনি যে নির্দিষ্ট ক্ষেত্রে পরিবর্তন করছেন তার জন্য শুধুমাত্র আপডেট করা ডেটা পাঠাতে, HTTP PATCH ক্রিয়া ব্যবহার করুন। এই নথিতে বর্ণিত প্যাচ শব্দার্থবিদ্যা আংশিক আপডেটের পুরোনো, GData বাস্তবায়নের চেয়ে ভিন্ন (এবং সহজ)।

নীচের সংক্ষিপ্ত উদাহরণটি দেখায় কিভাবে প্যাচ ব্যবহার করে একটি ছোট আপডেট করার জন্য আপনাকে যে ডেটা পাঠাতে হবে তা কমিয়ে দেয়।

উদাহরণ

এই উদাহরণটি শুধুমাত্র একটি জেনেরিক (কাল্পনিক) "ডেমো" API সম্পদের শিরোনাম আপডেট করার জন্য একটি সাধারণ প্যাচ অনুরোধ দেখায়। সম্পদটিতে একটি মন্তব্য, বৈশিষ্ট্যের একটি সেট, স্থিতি এবং অন্যান্য অনেক ক্ষেত্র রয়েছে, কিন্তু এই অনুরোধটি শুধুমাত্র title ক্ষেত্রটি পাঠায়, যেহেতু এটিই একমাত্র ক্ষেত্র সংশোধন করা হচ্ছে:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

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

200 OK
{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

আপডেট করা সম্পদের সম্পূর্ণ উপস্থাপনা সহ সার্ভার একটি 200 OK স্ট্যাটাস কোড প্রদান করে। যেহেতু প্যাচ অনুরোধে শুধুমাত্র title ক্ষেত্রটি অন্তর্ভুক্ত ছিল, এটিই একমাত্র মান যা আগের থেকে আলাদা।

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

একটি প্যাচ অনুরোধের শব্দার্থবিদ্যা

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

  • যোগ করুন: ইতিমধ্যে বিদ্যমান নেই এমন একটি ক্ষেত্র যোগ করতে, নতুন ক্ষেত্র এবং এর মান উল্লেখ করুন।
  • পরিবর্তন: একটি বিদ্যমান ক্ষেত্রের মান পরিবর্তন করতে, ক্ষেত্রটি নির্দিষ্ট করুন এবং এটিকে নতুন মান নির্ধারণ করুন।
  • মুছুন: একটি ক্ষেত্র মুছে ফেলতে, ক্ষেত্রটি নির্দিষ্ট করুন এবং এটিকে null সেট করুন। উদাহরণস্বরূপ, "comment": null । আপনি null এ সেট করে একটি সম্পূর্ণ বস্তু (যদি এটি পরিবর্তনযোগ্য হয়) মুছে ফেলতে পারেন। আপনি যদি Java API ক্লায়েন্ট লাইব্রেরি ব্যবহার করেন, তাহলে Data.NULL_STRING এর পরিবর্তে ব্যবহার করুন; বিস্তারিত জানার জন্য, JSON null দেখুন।

অ্যারে সম্পর্কে দ্রষ্টব্য: অ্যারে ধারণ করা প্যাচ অনুরোধগুলি আপনার দেওয়া একটি দিয়ে বিদ্যমান অ্যারে প্রতিস্থাপন করে। আপনি টুকরো টুকরো ফ্যাশনে একটি অ্যারেতে আইটেমগুলিকে সংশোধন, যোগ করতে বা মুছতে পারবেন না।

পঠন-সংশোধন-লেখা চক্রে প্যাচ ব্যবহার করা

আপনি যে ডেটা পরিবর্তন করতে চান তার সাথে একটি আংশিক প্রতিক্রিয়া পুনরুদ্ধার করে শুরু করা একটি দরকারী অনুশীলন হতে পারে। ETags ব্যবহার করে এমন রিসোর্সের জন্য এটি বিশেষভাবে গুরুত্বপূর্ণ, যেহেতু রিসোর্স সফলভাবে আপডেট করার জন্য আপনাকে অবশ্যই If-Match HTTP হেডারে বর্তমান ETag মান প্রদান করতে হবে। আপনি ডেটা পাওয়ার পরে, আপনি যে মানগুলি পরিবর্তন করতে চান তা পরিবর্তন করতে পারেন এবং একটি প্যাচ অনুরোধের সাথে পরিবর্তিত আংশিক উপস্থাপনা ফেরত পাঠাতে পারেন৷ এখানে একটি উদাহরণ যা অনুমান করে যে ডেমো সংস্থানটি ETags ব্যবহার করে:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

এটি আংশিক প্রতিক্রিয়া: 

200 OK
{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

নিম্নলিখিত প্যাচ অনুরোধ যে প্রতিক্রিয়া উপর ভিত্তি করে. নীচে দেখানো হিসাবে, এটি প্যাচ প্রতিক্রিয়ায় ফিরে আসা ডেটা সীমাবদ্ধ করতে fields প্যারামিটার ব্যবহার করে: 

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

সার্ভারটি একটি 200 ওকে HTTP স্ট্যাটাস কোড এবং আপডেট করা সম্পদের আংশিক উপস্থাপনা সহ সাড়া দেয়: 

200 OK
{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

সরাসরি একটি প্যাচ অনুরোধ নির্মাণ

কিছু প্যাচ অনুরোধের জন্য, আপনাকে সেগুলিকে পূর্বে পুনরুদ্ধার করা ডেটার উপর ভিত্তি করে রাখতে হবে। উদাহরণস্বরূপ, যদি আপনি একটি অ্যারেতে একটি আইটেম যোগ করতে চান এবং বিদ্যমান অ্যারের উপাদানগুলির কোনোটি হারাতে না চান, তাহলে আপনাকে অবশ্যই বিদ্যমান ডেটা পেতে হবে। একইভাবে, যদি একটি API ETags ব্যবহার করে, তাহলে রিসোর্সটি সফলভাবে আপডেট করার জন্য আপনাকে আপনার অনুরোধের সাথে পূর্ববর্তী ETag মান পাঠাতে হবে।

দ্রষ্টব্য: আপনি একটি "If-Match: *" HTTP শিরোনাম ব্যবহার করতে পারেন যখন ETags ব্যবহার করা হয় তখন একটি প্যাচের মধ্য দিয়ে যেতে বাধ্য করতে। আপনি যদি এটি করেন তবে আপনাকে লেখার আগে পড়ার দরকার নেই।

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

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

এই অনুরোধের সাথে, যদি মন্তব্য ক্ষেত্রের একটি বিদ্যমান মান থাকে, নতুন মান এটিকে ওভাররাইট করে; অন্যথায় এটি নতুন মান সেট করা হয়। একইভাবে, যদি একটি ভলিউম বৈশিষ্ট্য ছিল, তার মান ওভাররাইট করা হয়; যদি না হয়, এটি তৈরি করা হয়। নির্ভুলতা ক্ষেত্র, সেট করা হলে, সরানো হয়।

একটি প্যাচ প্রতিক্রিয়া হ্যান্ডলিং

একটি বৈধ প্যাচ অনুরোধ প্রক্রিয়া করার পরে, API পরিবর্তিত সম্পদের সম্পূর্ণ উপস্থাপনা সহ একটি 200 OK HTTP প্রতিক্রিয়া কোড প্রদান করে। যদি ETagsগুলি API দ্বারা ব্যবহার করা হয়, সার্ভারটি ETag মানগুলি আপডেট করে যখন এটি একটি প্যাচ অনুরোধ সফলভাবে প্রক্রিয়া করে, ঠিক যেমন এটি PUT এর সাথে করে।

প্যাচ রিকোয়েস্ট সম্পূর্ণ রিসোর্স রিপ্রেজেন্টেশন রিটার্ন করে যদি না আপনি fields প্যারামিটার ব্যবহার করে ডেটার পরিমাণ কমাতে ব্যবহার করেন।

যদি একটি প্যাচ অনুরোধ একটি নতুন রিসোর্স স্থিতিতে পরিণত হয় যা সিনট্যাক্টিক্যাল বা শব্দার্থগতভাবে অবৈধ, সার্ভারটি একটি 400 Bad Request বা 422 Unprocessable Entity HTTP স্ট্যাটাস কোড ফেরত দেয় এবং রিসোর্স অবস্থা অপরিবর্তিত থাকে। উদাহরণস্বরূপ, যদি আপনি একটি প্রয়োজনীয় ক্ষেত্রের জন্য মান মুছে ফেলার চেষ্টা করেন, সার্ভার একটি ত্রুটি প্রদান করে।

প্যাচ HTTP ক্রিয়া সমর্থিত না হলে বিকল্প স্বরলিপি

যদি আপনার ফায়ারওয়াল HTTP PATCH অনুরোধের অনুমতি না দেয়, তাহলে একটি HTTP POST অনুরোধ করুন এবং ওভাররাইড হেডারটিকে PATCH এ সেট করুন, যেমনটি নীচে দেখানো হয়েছে: 

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

প্যাচ এবং আপডেটের মধ্যে পার্থক্য

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

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

ব্যাচ অনুরোধ

এই নথিটি দেখায় যে কীভাবে আপনার ক্লায়েন্টকে HTTP সংযোগগুলি তৈরি করতে হবে তা কমাতে API কলগুলিকে একসাথে ব্যাচ করতে হয়৷

এই নথিটি বিশেষভাবে একটি HTTP অনুরোধ পাঠিয়ে একটি ব্যাচ অনুরোধ করার বিষয়ে। যদি, পরিবর্তে, আপনি একটি ব্যাচ অনুরোধ করতে একটি Google ক্লায়েন্ট লাইব্রেরি ব্যবহার করেন, ক্লায়েন্ট লাইব্রেরির ডকুমেন্টেশন দেখুন।

ওভারভিউ

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

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

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

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

আপনি একটি একক ব্যাচ অনুরোধে 100টি কলের মধ্যে সীমাবদ্ধ। আপনি যদি এর চেয়ে বেশি কল করতে চান তবে একাধিক ব্যাচ অনুরোধ ব্যবহার করুন।

দ্রষ্টব্য : Google Drive API-এর ব্যাচ সিস্টেম OData ব্যাচ প্রসেসিং সিস্টেমের মতো একই সিনট্যাক্স ব্যবহার করে, কিন্তু শব্দার্থবিদ্যা আলাদা।

অতিরিক্ত সীমাবদ্ধতা অন্তর্ভুক্ত:

  • 100 টির বেশি কল সহ ব্যাচের অনুরোধগুলি একটি ত্রুটির কারণ হতে পারে৷
  • প্রতিটি অভ্যন্তরীণ অনুরোধের জন্য URL-এর দৈর্ঘ্যে একটি 8,000 অক্ষরের সীমা রয়েছে৷
  • Google ড্রাইভ মিডিয়ার জন্য ব্যাচ অপারেশন সমর্থন করে না, হয় আপলোড বা ডাউনলোডের জন্য বা ফাইল রপ্তানির জন্য।

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

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

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

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

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

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

প্রতিটি অংশের মূল অংশটি একটি সম্পূর্ণ HTTP অনুরোধ, যার নিজস্ব ক্রিয়া, URL, শিরোনাম এবং বডি রয়েছে। HTTP অনুরোধে শুধুমাত্র URL এর পাথ অংশ থাকতে হবে; ব্যাচ অনুরোধে সম্পূর্ণ URL গুলি অনুমোদিত নয়৷

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

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

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

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

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

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

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

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

উদাহরণ

নিচের উদাহরণটি Google Drive API-এর সাথে ব্যাচিংয়ের ব্যবহার দেখায়।

উদাহরণ ব্যাচ অনুরোধ 

POST https://www.googleapis.com/batch/drive/v3
Accept-Encoding: gzip
User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip)
Content-Type: multipart/mixed; boundary=END_OF_PART
Content-Length: 963



--END_OF_PART
Content-Length: 337
Content-Type: application/http
content-id: 1
content-transfer-encoding: binary



POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id
Authorization: Bearer authorization_token
Content-Length: 70
Content-Type: application/json; charset=UTF-8



{
  "emailAddress":"example@appsrocks.com",
  "role":"writer",
  "type":"user"
}
--END_OF_PART
Content-Length: 353
Content-Type: application/http
content-id: 2
content-transfer-encoding: binary



POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false
Authorization: Bearer authorization_token
Content-Length: 58
Content-Type: application/json; charset=UTF-8



{
   "domain":"appsrocks.com",
   "role":"reader",
   "type":"domain"
}
--END_OF_PART--

উদাহরণ ব্যাচ প্রতিক্রিয়া

এটি পূর্ববর্তী বিভাগে উদাহরণ অনুরোধের প্রতিক্রিয়া। 

HTTP/1.1 200 OK
Alt-Svc: quic=":443"; p="1"; ma=604800
Server: GSE
Alternate-Protocol: 443:quic,p=1
X-Frame-Options: SAMEORIGIN
Content-Encoding: gzip
X-XSS-Protection: 1; mode=block
Content-Type: multipart/mixed; boundary=batch_6VIxXCQbJoQ_AATxy_GgFUk
Transfer-Encoding: chunked
X-Content-Type-Options: nosniff
Date: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Vary: X-Origin
Vary: Origin
Expires: Fri, 13 Nov 2015 19:28:59 GMT



--batch_6VIxXCQbJoQ_AATxy_GgFUk
Content-Type: application/http
Content-ID: response-1



HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Date: Fri, 13 Nov 2015 19:28:59 GMT
Expires: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Content-Length: 35



{
 "id": "12218244892818058021i"
}



--batch_6VIxXCQbJoQ_AATxy_GgFUk
Content-Type: application/http
Content-ID: response-2



HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Date: Fri, 13 Nov 2015 19:28:59 GMT
Expires: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Content-Length: 35



{
 "id": "04109509152946699072k"
}



--batch_6VIxXCQbJoQ_AATxy_GgFUk--

অনুরোধ থেকে নির্দিষ্ট ক্ষেত্র ফেরত দিন

ডিফল্টরূপে, সার্ভার ব্যবহৃত পদ্ধতির জন্য নির্দিষ্ট রিসোর্স ক্ষেত্রগুলির একটি ডিফল্ট সেট প্রদান করে। উদাহরণস্বরূপ, files.list পদ্ধতি শুধুমাত্র id , name , এবং mimeType প্রদান করতে পারে। এই ক্ষেত্রগুলি আপনার প্রয়োজনীয় সঠিক ক্ষেত্র নাও হতে পারে৷ আপনি যদি অন্য ক্ষেত্রগুলি ফেরত দিতে চান তবে একটি ফাইলের জন্য নির্দিষ্ট ক্ষেত্রগুলি ফেরত দেখুন।