সতর্কতা : এই পৃষ্ঠাটি Google-এর পুরানো API, Google Data APIs সম্পর্কে; এটি শুধুমাত্র Google Data APIs ডিরেক্টরিতে তালিকাভুক্ত APIগুলির সাথে প্রাসঙ্গিক, যার মধ্যে অনেকগুলি নতুন API দিয়ে প্রতিস্থাপিত হয়েছে৷ একটি নির্দিষ্ট নতুন API সম্পর্কে তথ্যের জন্য, নতুন API এর ডকুমেন্টেশন দেখুন। একটি নতুন API-এর সাহায্যে অনুরোধ অনুমোদনের বিষয়ে তথ্যের জন্য, Google অ্যাকাউন্ট প্রমাণীকরণ এবং অনুমোদন দেখুন।
এই দস্তাবেজটি অনেক Google API দ্বারা ব্যবহৃত Google ডেটা প্রোটোকল বর্ণনা করে, যার মধ্যে একটি কোয়েরি কেমন দেখায়, ফলাফলগুলি কেমন দেখায় ইত্যাদির তথ্য সহ।
Google ডেটা প্রোটোকল সম্পর্কে আরও তথ্যের জন্য, বিকাশকারীর গাইড ওভারভিউ পৃষ্ঠা এবং প্রোটোকল বেসিক ডকুমেন্ট দেখুন।
শ্রোতা
এই দস্তাবেজটি এমন যেকোনও ব্যক্তির জন্য যারা XML ফর্ম্যাট এবং এপিআই দ্বারা ব্যবহৃত প্রোটোকলের বিশদ বিবরণ বুঝতে চান যা Google ডেটা প্রোটোকল বাস্তবায়ন করে।
আপনি যদি এই APIগুলির একটি ব্যবহার করে এমন কোড লিখতে চান তবে আপনাকে এই বিবরণগুলি জানার দরকার নেই; পরিবর্তে, আপনি ভাষা-নির্দিষ্ট ক্লায়েন্ট লাইব্রেরি ব্যবহার করতে পারেন।
কিন্তু আপনি যদি প্রোটোকল বুঝতে চান তবে এই নথিটি পড়ুন। উদাহরণ স্বরূপ, আপনি এই নথিটি পড়তে চাইতে পারেন যা আপনাকে নিম্নলিখিত কাজগুলির মধ্যে যেকোনো একটিতে সাহায্য করতে পারে:
- Google ডেটা প্রোটোকল আর্কিটেকচারের মূল্যায়ন করা হচ্ছে
- প্রদত্ত ক্লায়েন্ট লাইব্রেরি ব্যবহার না করে প্রোটোকল ব্যবহার করে কোডিং
- একটি নতুন ভাষায় একটি ক্লায়েন্ট লাইব্রেরি লেখা
এই দস্তাবেজটি অনুমান করে যে আপনি XML, নেমস্পেস, সিন্ডিকেটেড ফিড এবং HTTP-তে GET , POST , PUT , এবং DELETE অনুরোধগুলি, সেইসাথে HTTP-এর একটি "রিসোর্স" ধারণার বুনিয়াদি বোঝেন৷ এই জিনিসগুলি সম্পর্কে আরও তথ্যের জন্য, এই নথির অতিরিক্ত সংস্থান বিভাগটি দেখুন।
এই নথিটি কোনো নির্দিষ্ট প্রোগ্রামিং ভাষার উপর নির্ভর করে না; আপনি যে কোনও প্রোগ্রামিং ভাষা ব্যবহার করে Google ডেটা প্রোটোকল বার্তা পাঠাতে এবং গ্রহণ করতে পারেন যা আপনাকে HTTP অনুরোধগুলি ইস্যু করতে এবং XML-ভিত্তিক প্রতিক্রিয়াগুলিকে পার্স করতে দেয়৷
প্রোটোকলের বিবরণ
এই বিভাগটি Google ডেটা প্রোটোকল নথি বিন্যাস এবং ক্যোয়ারী সিনট্যাক্স বর্ণনা করে।
নথি বিন্যাস
Google ডেটা প্রোটোকল এবং এটম একই মৌলিক ডেটা মডেল ভাগ করে: একটি ধারক যা কিছু বৈশ্বিক ডেটা এবং যেকোনো সংখ্যক এন্ট্রি উভয়ই ধারণ করে। প্রতিটি প্রোটোকলের জন্য, বিন্যাস একটি বেস স্কিমা দ্বারা সংজ্ঞায়িত করা হয়, কিন্তু এটি বিদেশী নামস্থান ব্যবহার করে প্রসারিত করা যেতে পারে।
অ্যাটম হল Google ডেটা প্রোটোকলের জন্য ডিফল্ট ফর্ম্যাট। অন্য বিন্যাসে একটি প্রতিক্রিয়া অনুরোধ করতে, alt ক্যোয়ারী প্যারামিটার ব্যবহার করুন; আরও তথ্যের জন্য, ক্যোয়ারী অনুরোধ দেখুন।
দ্রষ্টব্য : অ্যাটম ফর্ম্যাটে বেশিরভাগ Google ডেটা প্রোটোকল ফিডগুলি ফিড উপাদানে একটি xmlns অ্যাট্রিবিউট নির্দিষ্ট করে ডিফল্ট নেমস্পেস হিসাবে অ্যাটম নেমস্পেস ব্যবহার করে, যেমনটি প্রোটোকল বেসিক্সে দেওয়া উদাহরণগুলিতে দেখা যায়। সুতরাং, এই নথির উদাহরণগুলি স্পষ্টভাবে atom: একটি এটম-ফরম্যাট ফিডের উপাদানগুলির জন্য৷
নিম্নলিখিত টেবিলগুলি স্কিমার উপাদানগুলির পরমাণুর উপস্থাপনা দেখায়। এই টেবিলে উল্লেখ করা হয়নি এমন সমস্ত ডেটা প্লেইন এক্সএমএল হিসাবে বিবেচিত হয়। অন্যথায় নির্দেশিত না হলে, একটি প্রদত্ত কলামের XML উপাদানগুলি পরমাণুর নামস্থানে রয়েছে৷
দ্রষ্টব্য: এই সারাংশটি স্ট্যান্ডার্ড XPath স্বরলিপি ব্যবহার করে: বিশেষত, স্ল্যাশগুলি উপাদানের শ্রেণিবিন্যাস দেখায় এবং একটি @ চিহ্ন একটি উপাদানের একটি বৈশিষ্ট্য নির্দেশ করে।
নিম্নলিখিত টেবিলের প্রতিটিতে, হাইলাইট করা আইটেমগুলি প্রয়োজন।
নিম্নলিখিত টেবিলটি একটি Google ডেটা প্রোটোকল ফিডের উপাদানগুলি দেখায়:
| ফিড স্কিমা আইটেম | পরমাণু প্রতিনিধিত্ব |
|---|---|
| ফিড শিরোনাম | /feed/title |
| ফিড আইডি | /feed/id |
| ফিড এইচটিএমএল লিঙ্ক | /feed/link[@rel="alternate"] \[@type="text/html"]/@href |
| ফিড বিবরণ | /feed/subtitle |
| ফিড ভাষা | /feed/@xml:lang |
| ফিড কপিরাইট | /feed/rights |
| লেখক ফিড | (কিছু ক্ষেত্রে প্রয়োজনীয়; পরমাণুর স্পেসিফিকেশন দেখুন।) |
| ফিড শেষ আপডেট তারিখ | /feed/updated(RFC 3339 ফর্ম্যাট) |
| ফিড বিভাগ | /feed/category/@term |
| ফিড ক্যাটাগরি স্কিম | /feed/category/@scheme |
| ফিড জেনারেটর | /feed/generator/feed/generator/@uri |
| ফিড আইকন | /feed/icon |
| ফিড লোগো | /feed/logo |
নিম্নলিখিত টেবিলটি একটি Google ডেটা প্রোটোকল অনুসন্ধান-ফলাফল ফিডের উপাদানগুলি দেখায়৷ নোট করুন যে প্রোটোকলটি অনুসন্ধান-ফলাফল ফিডে OpenSearch 1.1 প্রতিক্রিয়া উপাদানগুলির কিছু প্রকাশ করে।
| অনুসন্ধান ফলাফল ফিড স্কিমা আইটেম | পরমাণুর প্রতিনিধিত্ব |
|---|---|
| অনুসন্ধান ফলাফলের সংখ্যা | /feed/openSearch:totalResults |
| অনুসন্ধান ফলাফল শুরু সূচক | /feed/openSearch:startIndex |
| প্রতি পৃষ্ঠায় অনুসন্ধান ফলাফলের সংখ্যা | /feed/openSearch:itemsPerPage |
নিম্নলিখিত টেবিলটি একটি Google ডেটা প্রোটোকল এন্ট্রির উপাদানগুলি দেখায়:
| এন্ট্রি স্কিমা আইটেম | পরমাণুর প্রতিনিধিত্ব |
|---|---|
| এন্ট্রি আইডি | /feed/entry/id |
| এন্ট্রি শিরোনাম | /feed/entry/title |
| এন্ট্রি লিঙ্ক | /feed/entry/link |
| এন্ট্রি সারাংশ | (কিছু ক্ষেত্রে প্রয়োজনীয়; পরমাণুর স্পেসিফিকেশন দেখুন।) |
| এন্ট্রি বিষয়বস্তু | (যদি কোন বিষয়বস্তুর উপাদান না থাকে, তাহলে এন্ট্রিতে অন্তত একটি |
| এন্ট্রি লেখক | (কিছু ক্ষেত্রে প্রয়োজনীয়; পরমাণুর স্পেসিফিকেশন দেখুন।) |
| এন্ট্রি বিভাগ | /feed/entry/category/@term |
| এন্ট্রি ক্যাটাগরি স্কিম | /feed/entry/category/@scheme |
| এন্ট্রি প্রকাশের তারিখ | /feed/entry/published(RFC 3339) |
| এন্ট্রি আপডেট তারিখ | /feed/entry/updated(RFC 3339) |
প্রশ্ন
এই বিভাগটি বর্ণনা করে কিভাবে ক্যোয়ারী সিস্টেম ব্যবহার করতে হয়।
মডেল ডিজাইনের নীতিগুলি জিজ্ঞাসা করুন
ক্যোয়ারী মডেল ইচ্ছাকৃতভাবে খুব সহজ. মৌলিক নীতিগুলি হল:
- ক্যোয়ারীগুলিকে HTTP হেডার বা পেলোডের অংশ হিসাবে না করে HTTP URI হিসাবে প্রকাশ করা হয়। এই পদ্ধতির একটি সুবিধা হল যে আপনি একটি প্রশ্নের সাথে লিঙ্ক করতে পারেন।
- পূর্বাভাস একটি একক আইটেম স্কোপ করা হয়. সুতরাং, "আজকে আমাকে কমপক্ষে 10টি ইমেল পাঠিয়েছে এমন লোকদের থেকে সমস্ত ইমেল খুঁজুন" এর মতো একটি সম্পর্কযুক্ত প্রশ্ন পাঠানোর কোনও উপায় নেই৷
- প্রোপার্টিগুলির সেট যা প্রশ্নগুলি সম্পর্কে পূর্বাভাস দিতে পারে খুব সীমিত; বেশীরভাগ কোয়েরি হল সম্পূর্ণ টেক্সট সার্চ কোয়েরি।
- ফলাফল ক্রম বাস্তবায়ন পর্যন্ত.
- প্রোটোকল স্বাভাবিকভাবেই এক্সটেনসিবল। আপনি যদি আপনার পরিষেবাতে অতিরিক্ত ভবিষ্যদ্বাণী বা বাছাই প্রকাশ করতে চান তবে আপনি নতুন পরামিতিগুলির প্রবর্তনের মাধ্যমে এটি সহজেই করতে পারেন।
ক্যোয়ারী অনুরোধ
একটি ক্লায়েন্ট একটি HTTP GET অনুরোধ জারি করে একটি Google পরিষেবার জন্য জিজ্ঞাসা করে৷ ক্যোয়ারী ইউআরআই রিসোর্সের ইউআরআই (এটম-এ FeedURI বলা হয়) এর পরে কোয়েরি প্যারামিটার থাকে। বেশিরভাগ ক্যোয়ারী প্যারামিটার ঐতিহ্যগত ?name=value[&...] URL প্যারামিটার হিসাবে উপস্থাপিত হয়। বিভাগ পরামিতি ভিন্নভাবে পরিচালনা করা হয়; নিচে দেখ.
উদাহরণস্বরূপ, যদি FeedURI হয় http://www.example.com/feeds/jo , তাহলে আপনি নিম্নলিখিত URI সহ একটি প্রশ্ন পাঠাতে পারেন:
http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z
Google ডেটা প্রোটোকল HTTP শর্তাধীন GET সমর্থন করে। যে APIগুলি প্রোটোকল বাস্তবায়ন করে তারা ফেরত দেওয়া ফিড বা এন্ট্রিতে <atom:updated> উপাদানের মানের উপর ভিত্তি করে সর্বশেষ-সংশোধিত প্রতিক্রিয়া শিরোনাম সেট করে। একজন ক্লায়েন্ট যদি পরিবর্তিত না হয়ে থাকে তাহলে বিষয়বস্তু পুনরায় পুনরুদ্ধার করা এড়াতে যদি-পরিবর্তিত-Since অনুরোধ শিরোনামের মান হিসাবে এই মানটিকে ফেরত পাঠাতে পারে। If-Modified-এর পর থেকে যদি বিষয়বস্তু পরিবর্তিত না হয়, তাহলে পরিষেবাটি একটি 304 (সংশোধিত নয়) HTTP প্রতিক্রিয়া প্রদান করে।
এপিআই যেগুলি Google ডেটা প্রোটোকল প্রয়োগ করে তাদের অবশ্যই alt প্রশ্নগুলি সমর্থন করতে হবে; অন্যান্য পরামিতিগুলির জন্য সমর্থন ঐচ্ছিক। একটি প্রদত্ত পরিষেবা দ্বারা বোঝা যায় না এমন একটি স্ট্যান্ডার্ড প্যারামিটার পাস করার ফলে একটি 403 Forbidden প্রতিক্রিয়া হয়৷ একটি অসমর্থিত ননস্ট্যান্ডার্ড প্যারামিটার পাস করার ফলে একটি 400 Bad Request প্রতিক্রিয়া দেখা যায়। অন্যান্য স্ট্যাটাস কোডের তথ্যের জন্য, এই ডকুমেন্টের HTTP স্ট্যাটাস কোড বিভাগ দেখুন।
স্ট্যান্ডার্ড ক্যোয়ারী প্যারামিটারগুলি নিম্নলিখিত টেবিলে সংক্ষিপ্ত করা হয়েছে। সমস্ত প্যারামিটার মান URL এনকোড করা প্রয়োজন.
| প্যারামিটার | অর্থ | মন্তব্য |
|---|---|---|
alt | বিকল্প প্রতিনিধিত্বের ধরন |
|
author | এন্ট্রি লেখক |
|
category | বিভাগ ক্যোয়ারী ফিল্টার |
|
/-/ category | বিভাগ ক্যোয়ারী ফিল্টার |
|
| এন্ট্রিআইডি | একটি নির্দিষ্ট এন্ট্রির আইডি পুনরুদ্ধার করতে হবে |
|
fields | প্রতিক্রিয়া ফিল্টার |
|
max-results | সর্বাধিক সংখ্যক ফলাফল পুনরুদ্ধার করা হবে | ডিফল্ট max-results মান আছে এমন যেকোনো পরিষেবার জন্য (ডিফল্ট ফিডের আকার সীমিত করার জন্য), আপনি সম্পূর্ণ ফিড পেতে চাইলে আপনি একটি খুব বড় সংখ্যা নির্দিষ্ট করতে পারেন। |
prettyprint | পরিচয় এবং লাইন বিরতি সহ একটি XML প্রতিক্রিয়া প্রদান করে |
|
published-min , published-max | এন্ট্রি প্রকাশনার তারিখে সীমানা |
|
q | ফুল-টেক্সট ক্যোয়ারী স্ট্রিং |
|
start-index | প্রথম ফলাফলের 1-ভিত্তিক সূচক পুনরুদ্ধার করা হবে |
|
strict | কঠোর ক্যোয়ারী পরামিতি চেকিং |
|
updated-min , updated-max | এন্ট্রি আপডেট তারিখে সীমানা |
|
বিষয়শ্রেণীর প্রশ্ন
আমরা বিভাগ প্রশ্নের জন্য একটি সামান্য অস্বাভাবিক বিন্যাস প্রদান করার সিদ্ধান্ত নিয়েছে. পরিবর্তে নিম্নলিখিত মত একটি ক্যোয়ারী প্রয়োজন:
http://example.com/jo?category=Fritz&category=2006
আমরা এটি ব্যবহার করা সম্ভব করেছি:
http://example.com/jo/-/Fritz/2006
এই পদ্ধতিটি ক্যোয়ারী প্যারামিটার ব্যবহার না করে একটি সংস্থান সনাক্ত করে এবং এটি ক্লিনার ইউআরআই তৈরি করে। আমরা বিভাগগুলির জন্য এই পদ্ধতিটি বেছে নিয়েছি কারণ আমরা মনে করি যে বিভাগ প্রশ্নগুলি সবচেয়ে সাধারণ প্রশ্নের মধ্যে থাকবে৷
এই পদ্ধতির অসুবিধা হল যে আমরা আপনাকে এই ধরনের ক্যাটাগরির প্রশ্নগুলিতে /-/ ব্যবহার করতে চাই, যাতে পরিষেবাগুলি অন্যান্য রিসোর্স ইউআরআই, যেমন http://example.com/jo/MyPost/comments থেকে বিভাগ প্রশ্নগুলিকে আলাদা করতে পারে।
প্রশ্ন উত্তর
অনুরোধের পরামিতিগুলির উপর নির্ভর করে প্রশ্নগুলি একটি এটম ফিড, একটি এটম এন্ট্রি বা একটি RSS ফিড প্রদান করে।
ক্যোয়ারী ফলাফলে সরাসরি <feed> উপাদান বা <channel> উপাদানের অধীনে নিম্নলিখিত OpenSearch উপাদান থাকে (ফলাফল Atom বা RSS কিনা তার উপর নির্ভর করে):
-
openSearch:totalResults - প্রশ্নের জন্য সার্চ ফলাফলের মোট সংখ্যা (অগত্যা সব ফলাফল ফিডে উপস্থিত থাকে না)।
-
openSearch:startIndex - প্রথম ফলাফলের 1-ভিত্তিক সূচক।
-
openSearch:itemsPerPage - একটি পৃষ্ঠায় প্রদর্শিত আইটেমের সর্বাধিক সংখ্যা৷ এটি ক্লায়েন্টদের পরবর্তী পৃষ্ঠাগুলির যেকোনো সেটে সরাসরি লিঙ্ক তৈরি করতে দেয়। যাইহোক, এই নম্বরটি ব্যবহার করার ক্ষেত্রে সম্ভাব্য ত্রুটির জন্য, ক্যোয়ারী অনুরোধ বিভাগে টেবিলে
start-indexসংক্রান্ত নোটটি দেখুন।
এটম রেসপন্স ফিড এবং এন্ট্রিতে নিম্নলিখিত অ্যাটম এবং ডেটা এপিআই উপাদানগুলির যেকোনও অন্তর্ভুক্ত থাকতে পারে (পাশাপাশি অ্যাটম স্পেসিফিকেশনে তালিকাভুক্ত অন্যান্য):
-
<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/> - URI নির্দিষ্ট করে যেখানে সম্পূর্ণ অ্যাটম ফিড পুনরুদ্ধার করা যেতে পারে।
-
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/> - অ্যাটম ফিডের পোস্টইউআরআই নির্দিষ্ট করে (যেখানে নতুন এন্ট্রি পোস্ট করা যেতে পারে)।
-
<link rel="self" type="..." href="..."/> - এই সম্পদের URI ধারণ করে।
typeঅ্যাট্রিবিউটের মান অনুরোধ করা ফরম্যাটের উপর নির্ভর করে। অন্তর্বর্তী সময়ে কোনো ডেটা পরিবর্তন না হলে, এই URI-তে আরেকটি GET পাঠানো একই প্রতিক্রিয়া প্রদান করে। -
<link rel="previous" type="application/atom+xml" href="..."/> - এই ক্যোয়ারী ফলাফল সেটের পূর্ববর্তী খণ্ডের URI নির্দিষ্ট করে, যদি এটি খণ্ড করা হয়।
-
<link rel="next" type="application/atom+xml" href="..."/> - এই ক্যোয়ারী ফলাফল সেটের পরবর্তী অংশের URI নির্দিষ্ট করে, যদি এটি খণ্ড করা হয়।
-
<link rel="edit" type="application/atom+xml" href="..."/> - এটম এন্ট্রির EditURI নির্দিষ্ট করে (যেখানে আপনি একটি আপডেট এন্ট্রি পাঠান)।
একটি অনুসন্ধান প্রশ্নের জবাবে এখানে একটি নমুনা প্রতিক্রিয়া বডি রয়েছে:
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
<id>http://www.example.com/feed/1234.1/posts/full</id>
<updated>2005-09-16T00:42:06Z</updated>
<title type="text">Books and Romance with Jo and Liz</title>
<link rel="alternate" type="text/html" href="http://www.example.net/"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<link rel="http://schemas.google.com/g/2005#post"
type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<link rel="self" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<generator version="1.0"
uri="http://www.example.com">Example Generator Engine</generator>
<openSearch:totalResults>2</openSearch:totalResults>
<openSearch:startIndex>0</openSearch:startIndex>
<entry gd:etag='W/"C0QBRXcycSp7ImA9WxRVGUo."'>
<id>http://www.example.com/feed/1234.1/posts/full/4521614025009481151</id>
<published>2005-01-09T08:00:00Z</published>
<updated>2005-01-09T08:00:00Z</updated>
<category scheme="http://www.example.com/type" term="blog.post"/>
<title type="text">This is the title of entry 1009</title>
<content type="xhtml">
<div
xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1009</div>
</content>
<link rel="alternate" type="text/html"
href="http://www.example.com/posturl"/>
<link rel="edit" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full/4521614025009481151"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
</entry>
<entry gd:etag='W/"C0QBRXrurSp7ImA9WxRVGUo."'>
<id>http://www.example.com/feed/1234.1/posts/full/3067545004648931569</id>
<published>2005-01-07T08:00:00Z</published>
<updated>2005-01-07T08:02:00Z</updated>
<category scheme="http://www.example.com/type" term="blog.post"/>
<title type="text">This is the title of entry 1007</title>
<content type="xhtml">
<div
xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1007</div>
</content>
<link rel="alternate" type="text/html"
href="http://www.example.com/posturl"/>
<link rel="edit" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full/3067545004648931569"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
</entry>
</feed>
যদি অনুরোধ করা ফিডটি অ্যাটম ফর্ম্যাটে হয়, যদি কোনও ক্যোয়ারী প্যারামিটার নির্দিষ্ট করা না থাকে এবং ফলাফলে সমস্ত এন্ট্রি না থাকলে, নিম্নলিখিত উপাদানটি শীর্ষ-স্তরের ফিডে ঢোকানো হয়: <link rel="next" type="application/atom+xml" href="..."/> এটি এন্ট্রিগুলির পরবর্তী সেট ধারণকারী একটি ফিডকে নির্দেশ করে। পরবর্তী সেটগুলিতে একটি অনুরূপ <link rel="previous" type="application/atom+xml" href="..."/> উপাদান রয়েছে৷ পরবর্তী সমস্ত লিঙ্ক অনুসরণ করে, একজন ক্লায়েন্ট একটি ফিড থেকে সমস্ত এন্ট্রি পুনরুদ্ধার করতে পারে।
HTTP স্থিতি কোড
নিম্নলিখিত সারণী বর্ণনা করে যে বিভিন্ন HTTP স্ট্যাটাস কোডগুলি ডেটা API-এর প্রসঙ্গে কী বোঝায়৷
| কোড | ব্যাখ্যা |
|---|---|
| 200 ঠিক আছে | কোন ত্রুটি নেই। |
| 201 তৈরি করা হয়েছে | একটি সম্পদ তৈরি সফল হয়েছে. |
| 304 সংশোধিত নয় | অনুরোধের If-Modified-Since হেডারে নির্দিষ্ট সময় থেকে সংস্থানটি পরিবর্তিত হয়নি। |
| 400 খারাপ অনুরোধ | অবৈধ অনুরোধ URI বা শিরোনাম, অথবা অসমর্থিত ননস্ট্যান্ডার্ড প্যারামিটার। |
| 401 অননুমোদিত | অনুমোদন আবশ্যক. |
| 403 নিষিদ্ধ | অসমর্থিত স্ট্যান্ডার্ড প্যারামিটার, বা প্রমাণীকরণ বা অনুমোদন ব্যর্থ হয়েছে। |
| 404 পাওয়া যায়নি | সম্পদ (যেমন একটি ফিড বা এন্ট্রি) পাওয়া যায়নি. |
| 409 দ্বন্দ্ব | নির্দিষ্ট সংস্করণ নম্বর সম্পদের সর্বশেষ সংস্করণ নম্বরের সাথে মেলে না৷ |
| 410 চলে গেছে | অনুরোধ করা পরিবর্তনের ইতিহাস সার্ভারে আর উপলব্ধ নেই৷ আরও বিস্তারিত জানার জন্য পরিষেবা-নির্দিষ্ট ডকুমেন্টেশন পড়ুন। |
| 500 অভ্যন্তরীণ সার্ভার সমস্যা | অভ্যন্তরীণ ত্রুটি. এটি হল ডিফল্ট কোড যা সমস্ত অচেনা সার্ভার ত্রুটির জন্য ব্যবহৃত হয়। |
সম্পদ সংস্করণ (ETags)
কখনও কখনও আপনাকে একটি নির্দিষ্ট এন্ট্রির একটি নির্দিষ্ট সংস্করণ উল্লেখ করতে সক্ষম হতে হবে।
এটি বিশেষ করে দুটি ক্ষেত্রে গুরুত্বপূর্ণ:
- একটি "শর্তসাপেক্ষ পুনরুদ্ধার" করা, যেখানে আপনার ক্লায়েন্ট একটি এন্ট্রির অনুরোধ করে এবং সার্ভারটি কেবল তখনই এন্ট্রি পাঠায় যদি ক্লায়েন্টের অনুরোধের শেষ সময় থেকে এটি পরিবর্তিত হয়।
- নিশ্চিত করা যে একাধিক ক্লায়েন্ট অসাবধানতাবশত একে অপরের পরিবর্তনগুলি ওভাররাইট করে না। ক্লায়েন্ট যদি এন্ট্রির জন্য একটি পুরানো সংস্করণ শনাক্তকারী নির্দিষ্ট করে তাহলে ডেটা এপিআই আপডেট এবং মুছে ফেলতে ব্যর্থ হয়ে এটি করে।
গুগল ডেটা এপিআই এই উভয় ক্ষেত্রেই ETags ব্যবহার করে, যা HTTP-এর একটি আদর্শ অংশ।
একটি ETag হল একটি শনাক্তকারী যা একটি নির্দিষ্ট এন্ট্রির একটি নির্দিষ্ট সংস্করণ নির্দিষ্ট করে। সার্ভারটি এন্ট্রি এবং ফিড উপাদানগুলিতে একটি ETag সংযুক্ত করে যা এটি ক্লায়েন্টদের কাছে পাঠায়। যখন একটি এন্ট্রি বা ফিড পরিবর্তন হয়, তখন এর ETagও পরিবর্তিত হয়।
Google ডেটা এপিআই দুটি জায়গায় ETag প্রদান করে: একটি ETag HTTP হেডারে এবং একটি gd:etag বৈশিষ্ট্যে <feed> এবং <entry> উপাদান।
Google Data API-এ, একটি ETag সাধারণত অক্ষর এবং সংখ্যার একটি স্ট্রিং, কখনও কখনও হাইফেন এবং পিরিয়ডগুলিও অন্তর্ভুক্ত করে; স্ট্রিংটি সাধারণত উদ্ধৃতি চিহ্নে আবদ্ধ থাকে। (উদ্ধৃতি চিহ্নগুলি ETag-এর অংশ৷) উদাহরণস্বরূপ, এখানে একটি ডেটা API এন্ট্রি থেকে একটি ETag রয়েছে: "S0wCTlpIIip7ImA0X0QI" ৷
দুটি ধরণের ETags রয়েছে: শক্তিশালী এবং দুর্বল। শক্তিশালী ETags একটি নির্দিষ্ট এন্ট্রির একটি নির্দিষ্ট সংস্করণ সনাক্ত করে, এবং অন্যান্য ক্লায়েন্টদের পরিবর্তন ওভাররাইট এড়াতে ব্যবহার করা যেতে পারে। দুর্বল ETags, Google Data API-এর প্রসঙ্গে, শুধুমাত্র শর্তসাপেক্ষ পুনরুদ্ধারের জন্য ব্যবহার করা হয়। একটি দুর্বল ETag সবসময় W/ দিয়ে শুরু হয়। যেমন: W/"D08FQn8-eil7ImA9WxZbFEw."
সমস্ত Google ডেটা API শক্তিশালী ETag সমর্থন করে না। যারা করে তাদের জন্য, শক্তিশালী ETags শুধুমাত্র এন্ট্রির জন্য ব্যবহার করা হয়; ফিডের ETags সবসময় দুর্বল।
শক্তিশালী ETags সমর্থন করে এমন একটি পরিষেবা থেকে পুনরুদ্ধার করা একটি ফিডের (কিছু HTTP শিরোনাম সহ) উদাহরণ এখানে দেওয়া হল:
GData-Version: 2.0
ETag: W/"C0QBRXcycSp7ImA9WxRVFUk."
...
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
...
<entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
...
</entry>
</feed>
ক্লায়েন্ট লাইব্রেরিগুলি যেগুলি ডেটা API-এর সংস্করণ 2 সমর্থন করে আপনার জন্য স্বচ্ছভাবে ETags পরিচালনা করে৷ নিম্নলিখিত তথ্যগুলি ক্লায়েন্টদের জন্য যারা ক্লায়েন্ট লাইব্রেরি ব্যবহার করে না এবং প্রোটোকল স্তরে সংস্করণ কীভাবে পরিচালনা করা হয় সে বিষয়ে আগ্রহী পাঠকদের জন্য।
দ্রষ্টব্য : ডেটা API-এর সংস্করণ 1.0-এ ব্যবহৃত রিসোর্স-সংস্করণ সিস্টেম সম্পর্কে তথ্যের জন্য, 1.0 রেফারেন্স গাইড দেখুন।
শর্তাধীন পুনরুদ্ধার
যদি আপনি একটি এন্ট্রি পুনরুদ্ধার করতে চান যা আপনি আগে পুনরুদ্ধার করেছেন, আপনি সার্ভারকে এন্ট্রি পাঠাতে বলার মাধ্যমে দক্ষতা উন্নত করতে পারেন যদি আপনি শেষবার এটি পুনরুদ্ধার করার পর থেকে এটি পরিবর্তিত হয়।
এই ধরণের শর্তসাপেক্ষ পুনরুদ্ধার করতে, একটি HTTP GET অনুরোধ পাঠান যাতে একটি HTTP If-None-Match শিরোনাম অন্তর্ভুক্ত থাকে। হেডারে, এন্ট্রির ETag উল্লেখ করুন।
এখানে একটি If-None-Match হেডারের একটি উদাহরণ:
If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."
যখন সার্ভার এই অনুরোধটি পায়, তখন এটি পরীক্ষা করে যে আপনি যে এন্ট্রির অনুরোধ করেছেন সেটিতে আপনার নির্দিষ্ট করা ETag-এর মতো একই ETag আছে কিনা। যদি ETags মিলে যায়, তাহলে এন্ট্রি পরিবর্তন করা হয়নি, এবং সার্ভার একটি HTTP 304 Not Modified স্ট্যাটাস কোড প্রদান করে।
যদি ETags মেলে না, তাহলে আপনি শেষবার অনুরোধ করার পর থেকে এন্ট্রিটি সংশোধন করা হয়েছে এবং সার্ভার এন্ট্রিটি ফেরত দেয়।
এন্ট্রি আপডেট করা হচ্ছে
অন্য ক্লায়েন্টের পরিবর্তনগুলি ওভাররাইট করা এড়ানোর সবচেয়ে সহজ উপায় হল সার্ভারের জন্য নিশ্চিত করা যে যখন আপনার ক্লায়েন্ট একটি আপডেটেড এন্ট্রি পাঠায়, তখন আপনার ক্লায়েন্ট যে এন্ট্রি দিয়ে শুরু করেছিলেন সেটি সার্ভারের দ্বারা সংরক্ষিত বর্তমান সংস্করণের মতোই। যদি আপনার ক্লায়েন্ট করার আগে একটি দ্বিতীয় ক্লায়েন্ট একটি আপডেট করে, তাহলে আপনার ক্লায়েন্টের আপডেট অস্বীকার করা হয়, কারণ আপনার ক্লায়েন্ট আর সর্বশেষ সংস্করণে তার পরিবর্তনগুলিকে ভিত্তি করে না।
যখন আপনার ক্লায়েন্ট শক্তিশালী ETags সমর্থন করে এমন একটি পরিষেবা থেকে ডেটা পুনরুদ্ধার করে, তখন প্রতিটি এন্ট্রিতে একটি ETag থাকে যা সেই এন্ট্রির সেই সংস্করণের জন্য একটি অনন্য সংস্করণ সনাক্তকারী হিসাবে কাজ করে।
দ্রষ্টব্য : ETags ব্যবহার করে আপডেট করা শুধুমাত্র শক্তিশালী ETags দিয়ে কাজ করে। দুর্বল ETags সরবরাহকারী পরিষেবাগুলির জন্য, সমস্ত আপডেট সফল হয়, আপনি এটি পুনরুদ্ধার করার পর থেকে অন্য কেউ এন্ট্রি আপডেট করেছে কিনা তা নির্বিশেষে; নতুন আপডেট সবসময় অন্য কোনো পূর্ববর্তী আপডেট ওভাররাইট করে। তাই আপডেট বা মুছে ফেলার সময় দুর্বল ETags পাঠাবেন না; আপনি যদি এটি করেন তবে আপনি একটি ত্রুটি বার্তা পাবেন।
তাই যখন আপনার ক্লায়েন্ট একটি শক্তিশালী-ETags পরিষেবাতে একটি আপডেট পাঠায়, তখন এটি নির্দিষ্ট করতে হবে যে এটি কোন সংস্করণটি আপডেট করছে। এটি করার দুটি উপায় আছে:
- একটি
If-MatchHTTP হেডার ব্যবহার করুন। -
<atom:entry>উপাদানেgd:etagবৈশিষ্ট্য ব্যবহার করুন।
যেখানে সম্ভব আমরা If-Match পদ্ধতির সুপারিশ করি।
If-Match ব্যবহার করে একটি এন্ট্রি আপডেট করতে, আপনি যে এন্ট্রি আপডেট করছেন তা অর্জন করে শুরু করুন। এন্ট্রিতে যেকোনো পছন্দসই পরিবর্তন করুন, তারপর পরিবর্তিত এন্ট্রি সহ একটি নতুন PUT অনুরোধ তৈরি করুন। (ইউআরএল ব্যবহার করার জন্য বিশদ বিবরণের জন্য, পরিষেবা-নির্দিষ্ট ডকুমেন্টেশন দেখুন।)
PUT পাঠানোর আগে, মূল এন্ট্রি থেকে ETag ধারণকারী একটি HTTP If-Match হেডার যোগ করুন:
If-Match: "S0wCTlpIIip7ImA0X0QI"
তারপর PUT অনুরোধ পাঠান।
যদি আপডেট সফল হয়, তাহলে সার্ভার একটি HTTP 200 OK স্ট্যাটাস কোড এবং আপডেট করা এন্ট্রির একটি অনুলিপি প্রদান করে।
যদি আপডেট ব্যর্থ হয় কারণ আপনার নির্দিষ্ট করা ETagটি এন্ট্রির বর্তমান ETag-এর সাথে মেলে না (যা বোঝায় যে আপনি শেষবার এটি পুনরুদ্ধার করার পর থেকে এন্ট্রিটি সার্ভারে পরিবর্তিত হয়েছে), তাহলে সার্ভারটি একটি HTTP 412 Precondition Failed অবস্থা কোড প্রদান করে।
আপনি যদি সহজে HTTP শিরোনাম লিখতে না পারেন, বা If-Match হেডার ব্যবহার এড়াতে অন্য কোনো কারণ থাকে, তাহলে আপনি পরিবর্তে gd:etag বৈশিষ্ট্যটি ব্যবহার করতে পারেন।
আপনি যদি একটি If-Match শিরোনাম না পাঠান, তাহলে সার্ভার আপডেট করা এন্ট্রির gd:etag অ্যাট্রিবিউট মান একটি অন্তর্নিহিত If-Match মান হিসাবে ব্যবহার করে।
সংস্করণ সিস্টেমটিকে ওভাররাইড করতে এবং আপনি এটি পুনরুদ্ধার করার পর অন্য কেউ এটি আপডেট করেছে কিনা তা বিবেচনা না করে এন্ট্রি আপডেট করতে, শিরোনামে ETag উল্লেখ করার পরিবর্তে If-Match: * ব্যবহার করুন।
কোন পরিষেবাগুলি শক্তিশালী ETags সমর্থন করে সে সম্পর্কে তথ্যের জন্য, মাইগ্রেশন গাইড দেখুন।
এন্ট্রি মুছে ফেলা হচ্ছে
শক্তিশালী ETags ব্যবহার করে এমন এন্ট্রি মুছে ফেলা অনেকটা সেগুলিকে আপডেট করার মতো কাজ করে।
একটি শক্তিশালী ETag আছে এমন একটি এন্ট্রি মুছতে, প্রথমে আপনি যে এন্ট্রিটি মুছতে চান সেটি পুনরুদ্ধার করুন, তারপর আপনি এন্ট্রির সম্পাদনা URL-এ একটি DELETE অনুরোধ পাঠান৷
আপনি যদি নিশ্চিত করতে চান যে আপনি একটি এন্ট্রি যেটি পুনরুদ্ধার করার পর থেকে অন্য ক্লায়েন্ট দ্বারা পরিবর্তিত হয়েছে তা মুছে ফেলবেন না, তাহলে একটি HTTP If-Match হেডার অন্তর্ভুক্ত করুন যাতে মূল এন্ট্রির ETag মান রয়েছে৷
আপনি যদি সংস্করণ সিস্টেমটিকে ওভাররাইড করতে চান এবং আপনি এটি পুনরুদ্ধার করার পর অন্য কেউ এটি আপডেট করেছে কিনা তা বিবেচনা না করে এন্ট্রিটি মুছে ফেলতে চান, তাহলে শিরোনামে ETag উল্লেখ করার পরিবর্তে If-Match: * ব্যবহার করুন।
যদি একটি এন্ট্রিতে একটি শক্তিশালী ETag না থাকে, তাহলে একটি DELETE অনুরোধ সর্বদা সফল হয়।
আংশিক প্রতিক্রিয়া (পরীক্ষামূলক)
ডিফল্টরূপে, সার্ভার অনুরোধগুলি প্রক্রিয়া করার পরে লক্ষ্য সম্পদের সম্পূর্ণ উপস্থাপনা ফেরত পাঠায়। আংশিক প্রতিক্রিয়া আপনাকে সম্পূর্ণ সম্পদ উপস্থাপনের পরিবর্তে শুধুমাত্র আগ্রহের উপাদান বা বৈশিষ্ট্যের জন্য অনুরোধ করতে দেয়। এটি আপনার ক্লায়েন্ট অ্যাপ্লিকেশনটিকে অপ্রয়োজনীয় ক্ষেত্রগুলি স্থানান্তর, পার্সিং এবং সংরক্ষণ এড়াতে দেয়, যাতে এটি নেটওয়ার্ক, CPU এবং মেমরি সংস্থানগুলি আরও দক্ষতার সাথে ব্যবহার করতে পারে।
আপনি যে পণ্যটি ব্যবহার করছেন তার জন্য আংশিক প্রতিক্রিয়া উপলব্ধ কিনা তা জানতে, এর API ডকুমেন্টেশন দেখুন।
একটি আংশিক প্রতিক্রিয়া অনুরোধ করতে, আপনি যে উপাদান বা বৈশিষ্ট্যগুলি ফেরত দিতে চান তা নির্দিষ্ট করতে fields ক্যোয়ারী প্যারামিটার ব্যবহার করুন৷ এখানে একটি উদাহরণ:
http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))
সার্ভারের প্রতিক্রিয়াতে ফিডের জন্য শুধুমাত্র লিঙ্ক এবং এন্ট্রি উপাদান রয়েছে; এন্ট্রি উপাদানগুলিতে শুধুমাত্র ETag, ID, আপডেট করা এবং লিঙ্কের তথ্য সম্পাদনা করা থাকে। fields ক্যোয়ারী প্যারামিটার সিনট্যাক্স নিম্নলিখিত বিভাগে আচ্ছাদিত করা হয়েছে. প্রতিক্রিয়া সম্পর্কে আরও বিশদ বিবরণের জন্য, আংশিক প্রতিক্রিয়াগুলি পরিচালনা করা দেখুন।
দ্রষ্টব্য : আপনি যেকোন অনুরোধের সাথে fields কোয়েরি প্যারামিটার ব্যবহার করতে পারেন যা ডেটা ফেরত দেয়। GET ছাড়াও, এতে POST , এবং PUT (পাশাপাশি PATCH , যা আংশিক আপডেট করার জন্য ব্যবহৃত হয়) অন্তর্ভুক্ত রয়েছে। যাইহোক, fields ক্যোয়ারী প্যারামিটার শুধুমাত্র প্রতিক্রিয়া ডেটা প্রভাবিত করে; এটি আপনাকে যে ডেটা প্রদান করতে হবে বা কোন ক্ষেত্রগুলি আপডেট বা তৈরি করা হয়েছে তা প্রভাবিত করে না।
ফিল্ড প্যারামিটার সিনট্যাক্স সারাংশ
fields ক্যোয়ারী প্যারামিটার মান বিন্যাস XPath সিনট্যাক্স উপর ভিত্তি করে; যাইহোক, এটি শুধুমাত্র বৈধ XPath এক্সপ্রেশনের একটি উপসেট সমর্থন করে। সমর্থিত সিনট্যাক্স নীচে সংক্ষিপ্ত করা হয়েছে, এবং অতিরিক্ত উদাহরণ নিম্নলিখিত বিভাগে প্রদান করা হয়েছে.
- বেশ কয়েকটি ক্ষেত্র নির্বাচন করতে একটি কমা-বিচ্ছিন্ন তালিকা ব্যবহার করুন।
- একটি উপাদান
bনির্বাচন করতেa/bব্যবহার করুন যেটিaএলিমেন্টের মধ্যে থাকে;bএর মধ্যেcনেস্টেড একটি উপাদান নির্বাচন করতেa/b/cব্যবহার করুন। - প্রদত্ত নামের সাথে একটি বৈশিষ্ট্য সনাক্ত করতে
'@'উপসর্গ ব্যবহার করুন; একটি উপাদান উল্লেখ করতে'@'উপসর্গ বাদ দিন। - আপনি যে উপাদানটি সীমাবদ্ধ করতে চান তার পরে "
[ ]" বন্ধনীতে অভিব্যক্তি স্থাপন করে নির্দিষ্ট মানদণ্ডের সাথে মেলে এমন উপাদান নির্বাচন করতে ক্ষেত্রের শর্তাবলী প্রয়োগ করুন৷উদাহরণস্বরূপ,
fields=entry[author/name='Elizabeth']শুধুমাত্র ফিড এন্ট্রি প্রদান করে যার জন্য এলিজাবেথ লেখক। - কোনো নির্বাচিত উপাদানের পরে "
( )" বন্ধনীতে অভিব্যক্তি স্থাপন করে শুধুমাত্র নির্দিষ্ট বৈশিষ্ট্য বা উপ-উপাদানের অনুরোধ করার জন্য ক্ষেত্র উপ-নির্বাচনকারীকে নির্দিষ্ট করুন।উদাহরণস্বরূপ,
fields=entry(id,author/email)প্রতিটি ফিড এন্ট্রির জন্য শুধুমাত্র আইডি এবং লেখকের ইমেল প্রদান করে। - আপনি ডাবল বা একক উদ্ধৃতি ব্যবহার করে স্ট্রিংগুলিকে সীমাবদ্ধ করতে পারেন
.
একটি ডবল বা একক উদ্ধৃতি এড়াতে, উদ্ধৃতি পুনরাবৃত্তি করুন. উদাহরণস্বরূপ,"""Hello,"" he said"স্ট্রিং তৈরি করে"Hello," he said, এবং'''Hello,'' he said'স্ট্রিং তৈরি করে'Hello,' he said। - আপনি ক্ষেত্র নির্বাচনে ওয়াইল্ডকার্ড ব্যবহার করতে পারেন।
উদাহরণস্বরূপ,
entry/gd:*gdনামস্থানে প্রবেশের সমস্ত চাইল্ড উপাদান নির্বাচন করে এবংentry/@gd:*একই নামস্থানে চাইল্ড এলিমেন্টের বৈশিষ্ট্য নির্বাচন করে।
fields ক্যোয়ারী প্যারামিটার একটি আউটপুট ফিল্টার হিসাবে কাজ করে। এর মানে হল যে আংশিক প্রতিক্রিয়া শুধুমাত্র বাকি প্রশ্নের প্রক্রিয়া করার পরে গণনা করা হয়। উদাহরণ স্বরূপ, যদি আপনি একটি max-results ক্যোয়ারী প্যারামিটারও উল্লেখ করেন যে আপনি প্রতি পৃষ্ঠায় 20টি ফলাফল চান, তাহলে প্রথম 20টি ফলাফল উত্পন্ন হয় এবং আংশিক প্রতিক্রিয়া সেখান থেকে গণনা করা হয়। যদি fields স্পেসিফিকেশন ক্যোয়ারী দ্বারা নির্বাচিত প্রথম 20টি এন্ট্রির কোনোটির সাথে মেলে না, তাহলে আপনি একটি খালি ফিড ফিরে পাবেন; আপনি প্রথম 20টি মিলে যাওয়া এন্ট্রি ফিরে পাবেন না ।
দ্রষ্টব্য: ক্যোয়ারী নির্বাচক হিসাবে ক্ষেত্রের শর্তগুলি ব্যবহার করার চেষ্টা করবেন না। অর্থাৎ, একটি সম্পূর্ণ ফিড পুনরুদ্ধার করার চেষ্টা করবেন না এবং একটি খুব বড় ডেটা সেট থেকে আগ্রহের আইটেমগুলিকে ফিল্টার করার জন্য ক্ষেত্রের শর্তগুলি প্রয়োগ করবেন না। যখনই সম্ভব, অন্যান্য ক্যোয়ারী প্যারামিটার ব্যবহার করুন, যেমন start-index এবং max-results , প্রতিটি প্রশ্নের ফলাফলকে একটি পরিচালনাযোগ্য আকারে কমাতে। অন্যথায়, আংশিক প্রতিক্রিয়ার সাথে পারফরম্যান্সের লাভগুলি অনুপযুক্ত ব্যবহারের কারণে সৃষ্ট গুরুতর কর্মক্ষমতা অবনতির দ্বারা ছাড়িয়ে যেতে পারে।
ক্ষেত্র পরামিতি মান বিন্যাস
নিম্নলিখিত নির্দেশিকাগুলি ব্যাখ্যা করে কিভাবে fields কোয়েরি প্যারামিটার মান তৈরি করতে হয়। প্রতিটি নির্দেশিকা উদাহরণগুলি অন্তর্ভুক্ত করে এবং প্যারামিটার মান কীভাবে প্রতিক্রিয়াকে প্রভাবিত করে তার বর্ণনা প্রদান করে।
দ্রষ্টব্য: সমস্ত ক্যোয়ারী প্যারামিটার মানের মতো, fields প্যারামিটার মান অবশ্যই URL এনকোড করা উচিত। ভাল পঠনযোগ্যতার জন্য, নীচের উদাহরণগুলি এনকোডিং বাদ দিন।
- আপনি যে ক্ষেত্রগুলি ফেরত দিতে চান তা চিহ্নিত করুন বা ক্ষেত্র নির্বাচন করুন।
-
fieldsক্যোয়ারী প্যারামিটার মান হল উপাদান বা গুণাবলীর একটি কমা-বিভক্ত তালিকা (একত্রে বলা হয় ক্ষেত্র ), এবং প্রতিটি ক্ষেত্র সম্পদ উপস্থাপনের মূল উপাদানের সাথে সম্পর্কিত। এইভাবে, যদি আপনি একটি ফিড পুনরুদ্ধার করেন, ক্ষেত্রগুলি<feed>উপাদানের সাপেক্ষে নির্দিষ্ট করা হয়, এবং যদি আপনি একটি একক এন্ট্রি পুনরুদ্ধার করেন, তাহলে<entry>উপাদানের সাপেক্ষে ক্ষেত্রগুলি নির্দিষ্ট করা হয়। আপনি যে উপাদানটি নির্বাচন করেছেন তা যদি ফিডে পুনরাবৃত্তি করা উপাদান হয় (বা এর অংশ), পরিষেবাটি সেই উপাদানটির সমস্ত দৃষ্টান্ত প্রদান করে৷
এখানে কিছু ফিড-স্তরের উদাহরণ রয়েছে:উদাহরণ প্রভাব entryসমস্ত <entry>উপাদান এবং সেই এন্ট্রিগুলির সমস্ত উপ-উপাদান প্রদান করে, কিন্তু<feed>এর অন্য কোনো চাইল্ড উপাদান নয়।id,entryউভয় ফিড <id>এবং সমস্ত<entry>উপাদান প্রদান করে।entry/titleসমস্ত ফিড এন্ট্রির জন্য <title>উপাদান প্রদান করে।
যখনই একটি নেস্টেড উপাদান ফেরত দেওয়া হয়, প্রতিক্রিয়াতে যেকোনটির জন্য ট্যাগগুলি অন্তর্ভুক্ত থাকেঅভিভাবক উপাদান। অভিভাবক ট্যাগগুলিতে অন্য কোনও শিশু উপাদান বা গুণাবলী অন্তর্ভুক্ত করা হয় না যদি না সেগুলিও স্পষ্টভাবে নির্বাচিত হয়৷entry/author/uriসমস্ত ফিড এন্ট্রির জন্য <author>উপাদানের শুধুমাত্র<uri>উপ-উপাদান প্রদান করে।entry/*:ratingসমস্ত ফিড এন্ট্রির জন্য যেকোনো নামস্থানে স্থানীয় নাম ratingসহ শুধুমাত্র উপ-উপাদানগুলি প্রদান করে।
এখানে কিছু প্রবেশ-স্তরের উদাহরণ রয়েছে:উদাহরণ প্রভাব authorলক্ষ্য এন্ট্রির <author>চাইল্ড উপাদান প্রদান করে।@gd:etagলক্ষ্য এন্ট্রির etagবৈশিষ্ট্য প্রদান করে।author/uriলক্ষ্য এন্ট্রির জন্য <author>উপাদানের<uri>উপ-উপাদান প্রদান করে।media:group/media:*টার্গেট এন্ট্রির জন্য mediaনেমস্পেসে<media:group>এর সমস্ত উপ-ক্ষেত্র ফেরত দেয়। - নির্দিষ্ট মানদণ্ডের সাথে মেলে এমন নির্বাচিত ক্ষেত্রগুলিতে প্রতিক্রিয়া সীমাবদ্ধ করুন, বা ক্ষেত্রের শর্তগুলি ব্যবহার করুন৷
- ডিফল্টরূপে, যদি আপনার অনুরোধ এমন একটি উপাদান নির্দিষ্ট করে যা একাধিকবার ঘটে, আংশিক প্রতিক্রিয়া সেই উপাদানটির সমস্ত দৃষ্টান্ত অন্তর্ভুক্ত করবে। যাইহোক, আপনি এটিও নির্দিষ্ট করতে পারেন যে প্রতিক্রিয়াটিতে শুধুমাত্র এমন উপাদান অন্তর্ভুক্ত করা উচিত যেগুলির একটি নির্দিষ্ট বৈশিষ্ট্যের মান রয়েছে বা উপাদানগুলি যা "
[ ]" সিনট্যাক্স ব্যবহার করে অন্য কিছু শর্ত পূরণ করে, যেমনটি নীচের উদাহরণগুলিতে দেখানো হয়েছে৷ আরো বিস্তারিত জানার জন্য ক্ষেত্রের অবস্থা সিনট্যাক্স বিভাগ দেখুন।উদাহরণ প্রভাব entry[link/@rel='edit']'edit'এরrelঅ্যাট্রিবিউট মান সহ একটি<link>উপাদান রয়েছে এমন যেকোনো ফিড এন্ট্রি ফেরত দেয়।entry/title[text()='Today']ফিড এন্ট্রিতে যে কোনো <title>উপাদান দেখায় যদি তাদের বিষয়বস্তু'Today'হয়।entry/author[name='Jo']ফিড এন্ট্রিতে যে কোনো <author>উপাদান দেখায় যদি তাদের'Jo'বিষয়বস্তু সহ একটি<name>উপ-উপাদান থাকে।author[name='Jo']টার্গেট এন্ট্রিতে <author>উপাদানটি ফেরত দেয় যদি এতে'Jo'বিষয়বস্তু সহ একটি<name>উপ-উপাদান থাকে। - শুধুমাত্র নির্বাচিত উপাদানগুলির অংশগুলির জন্য অনুরোধ করুন, অথবা ক্ষেত্রের উপ-নির্বাচনগুলি ব্যবহার করুন৷
- ডিফল্টরূপে, যদি আপনার অনুরোধ নির্দিষ্ট উপাদানগুলি নির্দিষ্ট করে, পরিষেবাটি সম্পূর্ণরূপে উপাদানগুলিকে ফেরত দেয়। আপনি নির্দিষ্ট করতে পারেন যে প্রতিক্রিয়াটিতে নির্বাচিত উপাদানগুলির মধ্যে শুধুমাত্র কিছু উপ-উপাদান অন্তর্ভুক্ত করা উচিত। আপনি "
( )" উপ-নির্বাচন সিনট্যাক্স ব্যবহার করে এটি করেন, নীচের উদাহরণগুলির মতো৷উদাহরণ প্রভাব entry/author(uri)ফিড এন্ট্রিতে লেখকদের জন্য শুধুমাত্র <uri>উপ-উপাদান প্রদান করে।entry/author[name='Jo'](uri)'Jo'এর লেখকের নাম আছে এমন যেকোনো এন্ট্রির জন্য শুধুমাত্র<uri><author>এর উপ-উপাদান প্রদান করে।entry(link(@rel,@href))ফিড এন্ট্রিতে প্রতিটি <link>উপাদানের জন্য শুধুমাত্রrelএবংhrefবৈশিষ্ট্যের মান দেখায়।entry(title,link[@rel='edit'])প্রতিটি ফিড এন্ট্রির জন্য সম্পাদনা relবৈশিষ্ট্য সহ শুধুমাত্র<title>এবং<link>উপাদানগুলি প্রদান করে।entry(title,author(uri)প্রতিটি ফিড এন্ট্রির জন্য <title>উপাদান এবং লেখক<uri>উপাদান উভয়ই প্রদান করে।
ক্ষেত্রের অবস্থা সিনট্যাক্স সম্পর্কে আরো
আপনি ক্ষেত্র বা উপ-ক্ষেত্র সহ ক্ষেত্রের অবস্থা ব্যবহার করতে পারেন। নির্বাচিত ক্ষেত্রটি ফলাফলে অন্তর্ভুক্ত করার জন্য শর্তটিকে সত্য হিসাবে মূল্যায়ন করতে হবে। যদি কোন ক্ষেত্রের শর্ত না থাকে, তাহলে নির্বাচিত ধরনের সমস্ত ক্ষেত্র অন্তর্ভুক্ত করা হয়।
নির্বাচিত ক্ষেত্রের পাঠ্য মান তুলনা করার জন্য ব্যবহার করা হয়। এই প্রসঙ্গে, যদি ক্ষেত্রটি একটি উপাদান হয়, তাহলে পাঠ্যের মান হল এর বিষয়বস্তু; if the field is an attribute, the text value is the attribute's value. If the field has no text value, then the comparison fails and the field is not included in the results.
The following table shows the XPath operators that are supported for field conditions and provides some examples.
| Operator | Syntax | Examples |
|---|---|---|
| String comparison | |
|
| Logical comparison | and |
|
| Numerical comparison | = or eq!= or ne> or gt> = or ge< or lt<= or le |
|
| Date comparison | Use numerical comparison operators, as shown in examples. | To do date or date/time comparisons, you can cast elements, attributes, or string literals into
|
| Existence | Use name of element or attribute as shown in examples. |
|
| Boolean | true() false() | Booleans can be useful during testing to force field conditions into a true or false state.
|
Handling partial responses
After a server that supports partial response processes a valid request that includes the fields query parameter, it sends back an HTTP 200 OK status code along with the requested attributes or elements. If the fields query parameter has an error or is otherwise invalid, the server returns an HTTP 400 Bad Request status code.
The root element of the response is either <feed> or <entry> , depending on the target URI. The root element's content includes only the selected fields for that feed or entry, along with the enclosing tags for any parent elements.
The value of the the request's fields query parameter can be echoed back in two ways:
- The root element has a
gd:fieldsattribute that shows value of thefieldsquery parameter specified in the request. - If the target URI is a feed, each editable entry has a
gd:fieldsattribute that shows the portion of thefieldsselection that applies to it.
Note: In order to see these gd:fields attribute values in your partial response, you must include them in your fields query parameter specification. You can do this explicitly, using @gd:fields , or using the more general @gd:* , which also includes ETag information.
The following example query asks the server to return a document that contains only attributes in the gd namespace (at both the feed and entry level), as well as the feed ID, the title, and the edit link for each feed entry:
http://example.com/myFeed?fields=@gd:*,id,entry(@gd:*,title,link[@rel='edit'])
The server returns the following partial response, along with a 200 Successful HTTP status code:
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
<id>http://example.com/myFeed</id>
<entry gd:etag='"EksPTg1Bfyp7IWA6WhJT"'
gd:fields="@gd:*,title,link[@rel='edit']">
<link rel='edit' href='http://example.com/myFeed/1/'/>
<title>This year</title>
</entry>
<entry gd:etag='"EksPQA1Cdyp7IWA6WhJT"'
gd:fields="@gd:*,title,link[@rel='edit']">
<link rel='edit' href='http://example.com/myFeed/2/'/>
<title>Last year</title>
</entry>
<entry d:etag='"EksPQAxHeCp7IWA6WhJT"'
gd:fields="@gd:*,title,link[@rel='edit']">
<link rel='edit' href='http://example.com/myFeed/3/'/>
<title>Today</title>
</entry>
</feed> If the selected fields do not match anything, the service still returns a 200 Successful HTTP status code, but the partial response is an empty feed:
<?xml version='1.0' encoding='utf-8'?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."' gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])> </feed>
Partial update (Experimental)
Google products that support partial response and editable resources also allow you to use partial update . With partial update, you send only the fields you want to update, rather sending a modified version of the full resource representation. This lets your client application be more efficient when making updates, as well as when using partial response to retrieve data.
Instead of using PUT , however, you must use a PATCH request when making a partial update. The semantics for PATCH are powerful enough to let you add, replace, and delete specific fields for a particular entry, all with a single request.
To find out if partial update is available for the product you are using, refer to the product-specific documentation.
Submitting a partial update request
To submit a partial update request, you send an HTTP PATCH request to the same URL that you would normally use with PUT to update the resource. The body of the PATCH request is a partial <entry> element that specifies the fields you want to add or modify. The entry's gd:fields attribute indicates the fields you want to delete.
The server processes PATCH requests in a specific order:
- It first removes from the resource representation the fields specified by the
gd:fieldsattribute.The syntax for the
gd:fieldsattribute is the same as for thefieldsquery parameter used when requesting a partial response. See Supported syntax for more details. - It then merges into the existing resource representation the data provided in the body of the request.
More details on how the data is merged are provided in Adding or updating fields below.
Note: Since the body of a PATCH request is not typically compliant with the Atom Syndication Format, the Content-Type you use with a PATCH request is application/xml .
Here is an example of a partial update request:
PATCH /myFeed/1/1/
Content-Type: application/xml
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:fields='description'>
<title>New title</title>
</entry> This PATCH request makes the following changes to the resource representation stored on the server for the target URI's entry:
- Removes the
<description>element. - Updates the
<title>element.
Semantics of a partial update request
The instructions below explain how to set up your PATCH request to delete, add, or update specific fields within an entry. A single PATCH request can perform any combination of these operations.
Deleting fields. Use the
<entry>element'sgd:fieldsattribute to identify any fields you want deleted from the resource. The following sample request deletes the title and summary associated with an entry. However the request does not add or update any other data for the entry.PATCH /myfeed/1/1/ Content-Type: application/xml <entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:fields='title,summary'/>Adding or updating fields. Use the body of the
<entry>element to specify the data that you want to add or update for a resource. These fields are merged into the existing data for the resource, after any deletions are made, according to the following rules:Fields not already present are added. If the resource data does not already specify a value for a field, then the field is added to the existing data. For example, if an entry does not have a title, and your
PATCHrequest contains a<title>element, then the new title is added to the entry.Fields already present are replaced or appended. The specific behavior for merging fields that are already specified in the resource data depends on the characteristics of the field:
Non-repeating fields are replaced. If the resource data already specifies a value for a non-repeating element, then the value you specify in the
PATCHrequest replaces the existing value for that element. For example, in the example below, the new title replaces the existing title.PATCH /myFeed/1/1/ Content-Type: application/xml <entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005'> <title>New Title</title> </entry>A more complex example is given below. For this example, assume that the entry can have only one author, and that the target resource already has values for the author's name and email address. Even though
<author>element has two child fields, only the<name>element is present in the data provided. As a result, only that field's value is overwritten. The value of the<email>element, which is missing from the data provided, remains unchanged.PATCH /myfeed/1/1/ Content-Type: application/xml <entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005'> <author> <name>New Name</name> </author> </entry>Repeating fields are appended. If the resource data already specifies a value for a repeating element, then the new element you provide is added to the existing set of values.
Note that there might be times when you want to do something other than add a new instance of a repeating element. For example, you might want to do one of the following:
Replace an entire list of repeating elements. You can delete all the repeating fields using the
gd:fieldsattribute (gd:fields='ns:accessControl', for example) and provide a complete set of the replacement fields. Since all the existing elements are deleted first, the set of fields you provide do not conflict with any existing values when they are appended.Replace one value in a set of existing values for a repeating element. In this case, simply remove the single element by defining the
gd:fieldsvalue narrowly enough to avoid deleting other values that you want to keep. For example, to remove only an access control with anactionofembed, you might usegd:fields='ns:accessControl[@action="embed"]'. Then you provide the single field that you want to replace it with in the body of the<entry>element:PATCH /myfeed/1/1/ Content-Type: application/xml <entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005' gd:fields='ns:accessControl[@action="embed"]> <ns:accessControl action="embed" permission="allowed" /> </entry>
Handling the response to a partial update
After processing a valid partial update request, the API returns a 200 OK HTTP response code. By default, the body of the response is the complete entry that you updated. The server updates ETag values when it successfully processes a PATCH request, just as it does with PUT .
If a PATCH request results in a new resource state that is syntactically or semantically invalid, the server returns an HTTP 400 Bad Request or 422 Unprocessable Entity HTTP status code, and the resource state remains unchanged. For example, if you attempt to delete a required field and do not provide a replacement, the server returns an error.
Note: It is important to understand how different fields relate to each other. It might be possible to put a resource into an inconsistent state by updating only part of mutually interdependent values. For example, it might be possible to update a start time to a later value than an end time. Although the API should return an error code, we recommend that you fully test these kinds of conditions to ensure consistency.
Alternate notation when PATCH is not supported
If your firewall does not allow PATCH , then do an HTTP POST request and set the override header to PATCH , as shown below:
POST /myfeed/1/1/ X-HTTP-Method-Override: PATCH Content-Type: application/xml ...
Using partial response with partial update
You can use a partial response as the basis of a subsequent partial update request. If you do this, specify a fields query parameter that includes edit links, as well as @gd:* . This ensures that the partial response includes information like the ETag and gd:fields attribute values, which are important for subsequent requests.
Here is an example that returns a partial response that you could use as the basis for a future partial update:
http://example.com/myFeed/1/1/?fields=@gd:*,link[@rel='edit'](@href),gd:who
The server responds:
<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='"E0UKRAREeCp7IWA6WhJT"'
gd:fields="@gd;*,link[@rel='edit'](@href),gd:who">
<link href='http://example.com/myFeed/1/1/'/>
<gd:who email='liz@gmail.com'/>
<gd:who email='jo@gmail.com'/>
<gd:who email='jane@gmail.com'/>
</entry> Suppose that you want to remove the user with email 'jane@gmail.com' , add a user with email 'will@gmail.com' , and change the email for the user currently listed as 'jo@gmail.com' to 'josy@gmail.com' .
You can make these changes simply by starting with the results of the previous response, modifying only the fields that are different, and submitting the modified partial entry as the body of the PATCH request. For this example, the needed modifications are:
- Delete
<gd:who email='jane'/>from the list of elements provided. - Add
<gd:who email='will@gmail.com'/>to the list of elements provided. - Replace
<gd:who email='jo@gmail.com'/>with<gd:who email='josy@gmail.com'/>.
The PATCH request based on the pevious partial response is shown below:
PATCH /myFeed/1/1/
Content-Type: application/xml
<entry gd:fields="@gd:*,link[@rel='edit'](@href),gd:who"
gd:etag="FE8LQQJJeSp7IWA6WhVa">
<link href='http://example.com/myFeed/1/1'/>
<gd:who email='liz@gmail.com'/>
<gd:who email='josy@gmail.com'/>
<gd:who email='will@gmail.com'/>
</entry> Note: This approach relies on the gd:fields and gd:etag (if supported) attributes being included in the partial response for the entry. The body of the partial entry must retain all fields and attribute that were present in the partial response — except for those you explicitly want to remove. You can update any of the existing fields in the body with new values, and you can include any new fields you want to add.
Authentication
When a client tries to access a service, it may need to provide the user's credentials to the service, to demonstrate that the user has the authority to perform the action in question.
The approach that a client should use for authentication depends on the type of client:
- A desktop application should use a Google-specific authentication system called Account Authentication for Installed Applications (also known as "ClientLogin"). (Web-based clients should not use this system.)
- A web-based client, such as a third-party front end to a Google service, should use a Google-specific authentication system called Account Authentication Proxy for Web-Based Applications (also known as "AuthSub").
In the ClientLogin system, the desktop client asks the user for their credentials, and then sends those credentials to the Google authentication system.
If authentication succeeds, then the authentication system returns a token that the client subsequently uses (in an HTTP Authorization header) when it sends Data API requests.
If authentication fails, then the server returns a 403 Forbidden status code, along with a WWW-Authenticate header containing a challenge applicable to the authentication.
The AuthSub system works similarly, except that instead of asking the user for their credentials, it connects the user to a Google service that requests credentials. The service then returns a token that the web application can use; the advantage of this approach is that Google (rather than the web front end) securely handles and stores the user's credentials.
For details about these authentication systems, see the Google Data APIs Authentication Overview or the Google Account Authentication documentation.
Session state
Many business logic implementations require session stickiness—keeping track of the state of a user's session.
Google tracks session state in two ways: using cookies, and using a token that can be sent as a query parameter. Both methods achieve the same effect. We recommend that clients support one of these session-state tracking methods (either one is sufficient). If a client doesn't support either of these methods, then that client will still work with Data APIs, but performance may suffer compared to clients that do support these methods. Specifically, if a client doesn't support these methods, then every request results in a redirect, and therefore every request (and any associated data) is sent to the server twice, which affects the performance of both the client and the server.
The Google client libraries handle session state for you, so if you use our libraries, you don't have to do anything to get session state support.
Additional resources
You may find the following third-party documents useful:
- Comparison of Atom and RSS from intertwingly
- Overview of Atom from IBM
- Dublin Core extensions to RSS
- HTTP 1.1 method definitions ; specification for
GET,POST,PUT, andDELETE - HTTP 1.1 status code definitions
- How to Create a REST Protocol
- Building Web Services the REST Way
- A Technical Introduction to XML
- XML Namespaces by Example
- ETag section of HTTP specification