এই পৃষ্ঠাটি Cloud Translation API অনুবাদ করেছে।

কর্মক্ষমতা টিপস

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

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

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

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

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

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

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

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

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

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

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

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

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

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

উদাহরণ

নিম্নলিখিত উদাহরণটি একটি জেনেরিক (কাল্পনিক) "ডেমো" এপিআই-এর সাথে 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)

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

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: { ... } মতো দেখতে একটি data অবজেক্টের মধ্যে নেস্টেড থাকে, সেগুলোর fields স্পেসিফিকেশনে " data " অন্তর্ভুক্ত করবেন না। data/a/b মতো fields স্পেসিফিকেশন সহ data অবজেক্টটি অন্তর্ভুক্ত করলে একটি এরর দেখা দেয়। এর পরিবর্তে, শুধু a/b মতো একটি fields স্পেসিফিকেশন ব্যবহার করুন।
অ্যারে বা অবজেক্টের নির্দিষ্ট কিছু সাব-ফিল্ডের সেট অনুরোধ করতে, এক্সপ্রেশনগুলিকে বন্ধনীতে " ( ) " রেখে একটি সাব-সিলেক্টর ব্যবহার করুন।
উদাহরণস্বরূপ: fields=items(id,author/email) items` অ্যারের প্রতিটি উপাদানের জন্য শুধুমাত্র আইটেম আইডি এবং লেখকের ইমেল ফেরত দেয়। আপনি একটি একক সাব-ফিল্ডও নির্দিষ্ট করতে পারেন, যেখানে fields=items(id) হলো fields=items/id এর সমতুল্য।
প্রয়োজনে ফিল্ড নির্বাচনে ওয়াইল্ডকার্ড ব্যবহার করুন।
উদাহরণস্বরূপ: fields=items/pagemap/* একটি পেজম্যাপের সমস্ত অবজেক্ট নির্বাচন করে।

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

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

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

যে ফিল্ডগুলো ফেরত পেতে চান, সেগুলো চিহ্নিত করুন, অথবা ফিল্ড নির্বাচন করুন।

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

এখানে সংগ্রহ-স্তরের কিছু উদাহরণ দেওয়া হলো:

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

এখানে সম্পদ-স্তরের কিছু উদাহরণ দেওয়া হলো:

উদাহরণ	প্রভাব
`title`	অনুরোধকৃত রিসোর্সের `title` ক্ষেত্রটি ফেরত দেয়।
`author/uri`	অনুরোধকৃত রিসোর্সের `author` অবজেক্টের `uri` সাব-ফিল্ডটি ফেরত দেয়।
`links/*/href`	`links` এর চাইল্ড হিসেবে থাকা সমস্ত অবজেক্টের `href` ফিল্ডটি রিটার্ন করে।

উপ-নির্বাচন ব্যবহার করে নির্দিষ্ট ফিল্ডের শুধু অংশবিশেষের জন্য অনুরোধ করুন।

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

উদাহরণ	প্রভাব
`items(title,author/uri)`	items অ্যারের প্রতিটি উপাদানের জন্য শুধুমাত্র `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 ইমপ্লিমেন্টেশনের চেয়ে ভিন্ন (এবং সহজতর)।

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

উদাহরণ

এই উদাহরণটি একটি জেনেরিক (কাল্পনিক) "ডেমো" এপিআই রিসোর্সের শুধুমাত্র শিরোনাম আপডেট করার জন্য একটি সাধারণ প্যাচ অনুরোধ দেখাচ্ছে। রিসোর্সটিতে একটি মন্তব্য, কিছু বৈশিষ্ট্য, স্ট্যাটাস এবং আরও অনেক ফিল্ড রয়েছে, কিন্তু এই অনুরোধটি শুধুমাত্র 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 সেট করে মুছে ফেলতে পারেন। আপনি যদি জাভা এপিআই ক্লায়েন্ট লাইব্রেরি ব্যবহার করেন, তাহলে এর পরিবর্তে Data.NULL_STRING ব্যবহার করুন; বিস্তারিত জানতে, JSON null দেখুন।

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

রিড-মডিফাই-রাইট চক্রে প্যাচ ব্যবহার করা

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

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 OK 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. */
  }
}

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

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

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

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

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 প্রতিক্রিয়া কোড ফেরত দেয়। যদি API-টি ETag ব্যবহার করে, তাহলে সার্ভার একটি প্যাচ অনুরোধ সফলভাবে প্রক্রিয়া করার পর ETag-এর মান আপডেট করে, ঠিক যেমনটি এটি PUT ক্ষেত্রে করে থাকে।

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

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

PATCH HTTP ভার্ব সমর্থিত না হলে বিকল্প সংকেত

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

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

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

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

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