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

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

এই নথিতে এমন কিছু কৌশল রয়েছে যা আপনি আপনার অ্যাপ্লিকেশনের কর্মক্ষমতা উন্নত করতে ব্যবহার করতে পারেন। কিছু ক্ষেত্রে, উপস্থাপিত ধারণাগুলিকে চিত্রিত করতে অন্যান্য API বা জেনেরিক API-এর উদাহরণ ব্যবহার করা হয়। যাইহোক, একই ধারণা ডিরেক্টরি 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 ক্রিয়া ব্যবহার করে এমন আপডেটগুলির সাথে, আপনি প্রয়োজনীয় প্যারামিটার সরবরাহ না করলে অনুরোধটি ব্যর্থ হয় এবং আপনি যদি ঐচ্ছিক পরামিতি সরবরাহ না করেন তবে এটি পূর্বে সেট করা ডেটা সাফ করে।

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

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

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

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

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

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

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

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

উদাহরণ

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",
    ...
  },
  ...
  ]
}

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"
    }
  },
  ...
  ]
}

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

একাধিক ক্ষেত্র নির্বাচন করতে একটি কমা-বিচ্ছিন্ন তালিকা ব্যবহার করুন।
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/* একটি পেজম্যাপে সমস্ত বস্তু নির্বাচন করে।

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

উদাহরণ	প্রভাব
`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` মান প্রদান করে।

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

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"
    }
  },
  ...
  ]
}

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

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

উদাহরণ

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",
  ...
}

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

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

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

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"],
  }
}

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

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

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

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
  }
}

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

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

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

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

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

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

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

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

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

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

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

উদাহরণ

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",
    ...
  },
  ...
  ]
}

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"
    }
  },
  ...
  ]
}

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

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

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

উদাহরণ	প্রভাব
`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 ক্যোয়ারী প্যারামিটার অন্তর্ভুক্ত করে, এটি অনুরোধ করা ডেটা সহ এটি একটি এইচটিটিপি 200 OK স্থিতি কোড ফেরত পাঠায়। যদি fields ক্যোয়ারী প্যারামিটারের কোনও ত্রুটি থাকে বা অন্যথায় অবৈধ থাকে তবে সার্ভারটি একটি ত্রুটি বার্তা সহ একটি এইচটিটিপি 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"
    }
  },
  ...
  ]
}

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

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

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

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

উদাহরণ

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

অ্যারে সম্পর্কে দ্রষ্টব্য: অ্যারেযুক্ত প্যাচ অনুরোধগুলি আপনার সরবরাহিত একটির সাথে বিদ্যমান অ্যারে প্রতিস্থাপন করে। আপনি টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো টুকরো

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

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

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 ওকে এইচটিটিপি স্থিতি কোড এবং আপডেট হওয়া সংস্থানগুলির আংশিক উপস্থাপনা দিয়ে সাড়া দেয়:

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

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

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

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

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

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
  }
}

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

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

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

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

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

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

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

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

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

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

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