নথি অনুসন্ধান ও পুনরুদ্ধার করুন

এই নির্দেশিকাটি আপনাকে দেখাবে কীভাবে ডেভেলপার নলেজ এপিআই (Developer Knowledge API) ব্যবহার করে প্রোগ্রাম্যাটিকভাবে গুগলের পাবলিক ডেভেলপার ডকুমেন্টেশন অনুসন্ধান ও পুনরুদ্ধার করা যায়। ম্যানুয়ালি ওয়েব পেজ স্ক্র্যাপ করার পরিবর্তে, এই এপিআই আপনার অ্যাপ্লিকেশনগুলোকে প্রাসঙ্গিক টেক্সট স্নিপেট খুঁজে পেতে বা সম্পূর্ণ মার্কডাউন ডকুমেন্ট সংগ্রহ করতে সাহায্য করে।

এই নথিতে আপনি নিম্নলিখিত কাজগুলির উদাহরণ পাবেন:

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

শুরু করার আগে, নিশ্চিত করুন যে আপনি API সক্রিয় করেছেন এবং একটি ডেভেলপার নলেজ API কী তৈরি করেছেন । তারপর, আপনার কী-টি একটি এনভায়রনমেন্ট ভেরিয়েবলে সংরক্ষণ করুন:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

SearchDocumentChunks ব্যবহার করে নথি অনুসন্ধান করুন

একটি কোয়েরি স্ট্রিং-এর সাথে মেলে এমন ডকুমেন্ট চাঙ্ক খুঁজে বের করতে documents.searchDocumentChunks মেথডটি ব্যবহার করুন। ফলাফলে মিলে যাওয়া ডকুমেন্টগুলোর কন্টেন্টের চাঙ্কের পাশাপাশি একটি parent রেফারেন্সও থাকে, যা ব্যবহার করে আপনি সেই ডকুমেন্টগুলোর সম্পূর্ণ কন্টেন্ট পুনরুদ্ধার করতে পারবেন।

নিম্নলিখিত উদাহরণটি 'BigQuery'-এর সাথে মেলে এমন ডকুমেন্ট অনুসন্ধান করে:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&key=$DEVELOPERKNOWLEDGE_API_KEY"

আউটপুটটি নিম্নলিখিতের অনুরূপ:

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "BigQuery overview",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z"
      },
      "relevanceScore": 0.92
    }
  ]
}

results তালিকার প্রতিটি ফলাফলে অন্তর্ভুক্ত রয়েছে:

  • parent : ডকুমেন্ট রিসোর্সের নাম (উদাহরণস্বরূপ, documents/docs.cloud.google.com/bigquery/docs/introduction )।
  • id : ডকুমেন্টের মধ্যে থাকা চাঙ্ক শনাক্তকারী (উদাহরণস্বরূপ, chunk_0 )।
  • content : ডকুমেন্ট থেকে মিলে যাওয়া পাঠ্যাংশ।
  • document : উৎস ডকুমেন্ট সম্পর্কিত মেটাডেটা, যেমন এর title , uri , dataSource এবং updateTime ।
  • relevanceScore : সার্চ কোয়েরির সাথে চাঙ্কটির প্রাসঙ্গিকতার স্কোর, যার পরিসর [0.0, 1.0] ।

রেসপন্স স্কিমা এবং উপলব্ধ সকল মেটাডেটা ফিল্ড সম্পর্কে আরও তথ্যের জন্য, documents.searchDocumentChunks API রেফারেন্স দেখুন।

অনুসন্ধানের ফলাফল পৃষ্ঠাঙ্কিত করুন

যখন কোনো সার্চ কোয়েরি একাধিক ফলাফল প্রদান করে, তখন আপনি পেজিনেশন প্যারামিটার ব্যবহার করে ফলাফলের সেটের মধ্যে চলাচল করতে পারেন:

  • pageSize (পূর্ণসংখ্যা): প্রতি পৃষ্ঠায় ফেরত দেওয়া ফলাফলের সর্বোচ্চ সংখ্যা নির্দিষ্ট করে। যদি নির্দিষ্ট না করা হয়, তাহলে API ডিফল্টরূপে পাঁচটি ফলাফল দেখায়। সর্বোচ্চ অনুমোদিত মান হলো ১০০; ১০০-এর বেশি মানকে ১০০-তে রূপান্তরিত করা হয়।
  • pageToken (স্ট্রিং): ফলাফলের পরবর্তী পৃষ্ঠা আনার জন্য পূর্ববর্তী রেসপন্সে প্রাপ্ত টোকেনটি নির্দিষ্ট করে।

প্রথম পৃষ্ঠার জন্য অনুরোধ করুন

পৃষ্ঠার আকার নির্ধারণ করতে, আপনার অনুরোধে pageSize প্যারামিটারটি পাস করুন:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&key=$DEVELOPERKNOWLEDGE_API_KEY"

যদি অতিরিক্ত ফলাফল পাওয়া যায়, তাহলে প্রতিক্রিয়ায় একটি nextPageToken অন্তর্ভুক্ত থাকে:

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "What is BigQuery?",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z",
        "view": "DOCUMENT_VIEW_BASIC"
      },
      "relevanceScore": 0.88
    }
  ],
  "nextPageToken": "CAUQABgB"
}

পরবর্তী পৃষ্ঠাগুলি পুনরুদ্ধার করুন

আপনার পরবর্তী অনুরোধে nextPageToken এর মান pageToken প্যারামিটারে পাঠান:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&pageToken=CAUQABgB&key=$DEVELOPERKNOWLEDGE_API_KEY"

যখন আপনি ফলাফলের শেষ পৃষ্ঠায় পৌঁছান, তখন রেসপন্স থেকে nextPageToken বাদ দেওয়া হয়।

অনুসন্ধানের ফলাফল ফিল্টার করুন

অনুসন্ধানের ফলাফলে কঠোর ফিল্টার প্রয়োগ করতে filter প্যারামিটারটি ব্যবহার করুন। ফিল্টার এক্সপ্রেশনটি প্রতিটি চাঙ্কের জন্য প্যারেন্ট ডকুমেন্টের মেটাডেটাতে প্রয়োগ করা হয়।

filter এক্সপ্রেশনটির ৫০০ অক্ষরের সীমা রয়েছে।

সমর্থিত ক্ষেত্র

আপনি নিম্নলিখিত মূল ডকুমেন্ট ফিল্ডগুলি ব্যবহার করে আপনার অনুসন্ধানের ফলাফল ফিল্টার করতে পারেন:

  • content_length_bytes (পূর্ণসংখ্যা): ডকুমেন্টের content ফিল্ডের দৈর্ঘ্য, যা বাইটে পরিমাপ করা হয়।
  • data_source (স্ট্রিং): ডকুমেন্টটির উৎস ডোমেইন, যেমন docs.cloud.google.com বা firebase.google.com । সকল সমর্থিত ডেটা সোর্সের জন্য কর্পাস রেফারেন্স দেখুন।
  • update_time (টাইমস্ট্যাম্প): ডকুমেন্টটি সর্বশেষ আপডেট করার সময়কার টাইমস্ট্যাম্প। মান অবশ্যই RFC 3339 ফরম্যাট ব্যবহার করে দিতে হবে (উদাহরণস্বরূপ, "2025-01-01T00:00:00Z" )।
  • uri (স্ট্রিং): ডকুমেন্টটির সম্পূর্ণ URI (উদাহরণস্বরূপ, https://docs.cloud.google.com/bigquery/docs/tables )।

সমর্থিত অপারেটররা

ফিল্ডের ডেটা টাইপের উপর নির্ভর করে ফিল্টার এক্সপ্রেশন পার্সার বিভিন্ন অপারেটর সমর্থন করে:

  • স্ট্রিং ফিল্ড ( data_source , uri ): হুবহু স্ট্রিং মেলানোর জন্য = (সমান) এবং != (সমান নয়) সমর্থন করে। আংশিক, প্রিফিক্স এবং রেগুলার এক্সপ্রেশন মেলানো সমর্থিত নয়।
  • টাইমস্ট্যাম্প ফিল্ড ( update_time ): = , < , <= , > , এবং >= সমর্থিত।
  • পূর্ণসংখ্যা ক্ষেত্র ( content_length_bytes ): = , != , < , <= , > , এবং >= সমর্থিত।
  • লজিক্যাল অপারেটর : AND , OR , এবং NOT (বা - ) ব্যবহার করে শর্তগুলো একত্রিত করুন।

ফিল্টার উদাহরণ

নিম্নলিখিত উদাহরণগুলিতে ফিল্টার এক্সপ্রেশন কীভাবে তৈরি করতে হয় তা দেখানো হয়েছে। curl দিয়ে REST API কল করার সময়, ফিল্টার প্যারামিটারটি URL-এনকোড করতে বা --data-urlencode ব্যবহার করতে ভুলবেন না।

একাধিক ডেটা উৎসের সাথে মেলান

একাধিক উৎস থেকে নথি অন্তর্ভুক্ত করতে OR ব্যবহার করুন:

data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"

curl অনুরোধ:

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=database" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

টাইমস্ট্যাম্প অনুসারে ফিল্টার করুন

একটি নির্দিষ্ট তারিখের পরে আপডেট হওয়া কন্টেন্ট খুঁজে বের করতে RFC 3339 টাইমস্ট্যাম্পের সাথে তুলনা অপারেটর ব্যবহার করুন:

update_time >= "2025-01-01T00:00:00Z"

curl অনুরোধ: 

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=BigQuery" \
  --data-urlencode 'filter=update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

বিষয়বস্তুর দৈর্ঘ্য অনুসারে ফিল্টার করুন

বাইট সাইজের উপর ভিত্তি করে ডকুমেন্ট খুঁজে বের করতে content_length_bytes এর সাথে তুলনা অপারেটর ব্যবহার করুন: 

content_length_bytes < 5000

curl অনুরোধ: 

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Storage" \
  --data-urlencode 'filter=content_length_bytes < 5000' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

ডেটা উৎস, টাইমস্ট্যাম্প এবং গ্রুপিং একত্রিত করুন

একটি নির্দিষ্ট তারিখের পরে আপডেট হওয়া নির্দিষ্ট উৎসগুলিতে ফলাফল সীমাবদ্ধ করতে AND , OR এবং প্রথম বন্ধনী (...) একত্রিত করুন: 

(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"

curl অনুরোধ: 

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=service worker" \
  --data-urlencode 'filter=(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

ডেটা উৎস বাদ দিন

কোনো নির্দিষ্ট উৎস থেকে ফলাফল বাদ দিতে NOT বা != ব্যবহার করুন: 

data_source != "firebase.google.com"

curl অনুরোধ: 

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=authentication" \
  --data-urlencode 'filter=data_source != "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

GetDocument ব্যবহার করে একটি ডকুমেন্ট পুনরুদ্ধার করুন

কোনো একটি ডকুমেন্টের সম্পূর্ণ বিষয়বস্তু পেতে documents.get মেথডটি ব্যবহার করুন।

রিসোর্সের নাম বনাম ইউআরআই

ডেভেলপার নলেজ এপিআই-তে ডকুমেন্ট রেফারেন্স করার সময়, রিসোর্স নেম এবং ওয়েব ইউআরআই-এর মধ্যে পার্থক্যটি লক্ষ্য করুন:

  • রিসোর্সের নাম ( parent , name ): documents/{uri_without_scheme} ফরম্যাটে (উদাহরণস্বরূপ, documents/docs.cloud.google.com/storage/docs/creating-buckets )। এই মানটি GetDocument এর path প্যারামিটার হিসেবে অথবা BatchGetDocuments এর names প্যারামিটারে পাস করুন।
  • ওয়েব ইউআরআই ( uri ): স্কিম সহ সম্পূর্ণ ওয়েব ইউআরএল (উদাহরণস্বরূপ, https://docs.cloud.google.com/storage/docs/creating-buckets )। filter এক্সপ্রেশন তৈরি করার সময় uri ফিল্ডের জন্য এই ফরম্যাটটি ব্যবহার করুন (উদাহরণস্বরূপ, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets" )।

নিম্নলিখিত উদাহরণটি তার রিসোর্স নাম দ্বারা একটি ডকুমেন্ট পুনরুদ্ধার করে: 

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?key=$DEVELOPERKNOWLEDGE_API_KEY"

প্রতিক্রিয়াটি একটি Document রিসোর্স, যার content ফিল্ডে মেটাডেটা এবং সম্পূর্ণ মার্কডাউন কন্টেন্ট থাকে।

BatchGetDocuments ব্যবহার করে একাধিক ডকুমেন্ট পুনরুদ্ধার করুন

একটিমাত্র এপিআই কলে নাম দিয়ে সর্বোচ্চ ২০টি ডকুমেন্ট পাওয়ার জন্য documents.batchGet মেথডটি ব্যবহার করুন। একাধিক GetDocument রিকোয়েস্ট পাঠানোর চেয়ে এটি বেশি কার্যকর।

নিম্নলিখিত উদাহরণটি নাম অনুসারে দুটি ডকুমেন্ট পুনরুদ্ধার করে: 

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&key=$DEVELOPERKNOWLEDGE_API_KEY"

প্রতিক্রিয়াটিতে আপনার অনুরোধ করা ক্রমানুসারে অনুরোধকৃত Document রিসোর্সগুলির একটি তালিকা রয়েছে।

প্রতিক্রিয়া পেলোড অপ্টিমাইজ করুন

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

ডকুমেন্ট ভিউ ব্যবহার করুন

view প্যারামিটারটি নিয়ন্ত্রণ করে যে Document মেসেজগুলিতে কোন ফিল্ডগুলি পূরণ করা হবে।

DocumentView enum নিম্নলিখিত মানগুলিকে সমর্থন করে:

  • DOCUMENT_VIEW_BASIC : শুধুমাত্র মৌলিক মেটাডেটা ফিল্ডগুলো ( name , uri , data_source , title , description , update_time , এবং view ) ফেরত দেয়। content ফিল্ডটি বাদ দেওয়া হয়।
  • DOCUMENT_VIEW_CONTENT : মার্কডাউন content ফিল্ডের সাথে মেটাডেটা ফিল্ডগুলোও ফেরত দেয়। GetDocument এবং BatchGetDocuments জন্য এটিই ডিফল্ট।
  • DOCUMENT_VIEW_FULL : ডকুমেন্টের সমস্ত ফিল্ড ফেরত দেয়।

বৃহৎ মার্কডাউন কন্টেন্ট ডাউনলোড না করে শুধুমাত্র ডকুমেন্টের মেটাডেটা পুনরুদ্ধার করতে, view=DOCUMENT_VIEW_BASIC সেট করুন: 

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

আপনি BatchGetDocuments এর সাথে view=DOCUMENT_VIEW_BASIC ব্যবহার করতে পারেন: 

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

ফিল্ড মাস্ক ব্যবহার করুন

রেসপন্স পেলোডকে নির্দিষ্ট ফিল্ডে আরও সীমিত করতে, স্ট্যান্ডার্ড গুগল এপিআই fields কোয়েরি প্যারামিটার (ফিল্ড মাস্ক) ব্যবহার করুন।

GetDocument এ ফিল্ড ফিল্টার করুন

একটি ডকুমেন্টের শুধুমাত্র title , uri , এবং updateTime ফিল্ডগুলো পুনরুদ্ধার করতে: 

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?fields=title,uri,updateTime&key=$DEVELOPERKNOWLEDGE_API_KEY"

BatchGetDocuments এ ফিল্ড ফিল্টার করুন

ব্যাচের প্রতিটি ডকুমেন্ট থেকে শুধুমাত্র নির্দিষ্ট ফিল্ডগুলো পুনরুদ্ধার করতে: 

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&fields=documents(name,title,uri)&key=$DEVELOPERKNOWLEDGE_API_KEY"

একটি সার্চ থেকে শুধুমাত্র চাঙ্ক id ও content , প্যারেন্ট ডকুমেন্টের title ও uri , এবং nextPageToken ফেরত পেতে: 

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&fields=results(id,content,document(title,uri)),nextPageToken&key=$DEVELOPERKNOWLEDGE_API_KEY"

ত্রুটিগুলি পরিচালনা করুন

ডেভেলপার নলেজ এপিআই স্ট্যান্ডার্ড HTTP স্ট্যাটাস কোডগুলো রিটার্ন করে। নিম্নলিখিত কার্যকরী উদাহরণগুলো ডেভেলপার নলেজ এপিআই-তে HTTP স্ট্যাটাস কোড এবং সেগুলোর কারণগুলোকে ম্যাপ করে:

  • 400 INVALID_ARGUMENT :
    • filter এক্সপ্রেশন স্ট্রিংটি ৫০০ অক্ষরের বেশি।
    • update_time টাইমস্ট্যাম্পটি অবৈধ (অবশ্যই RFC 3339 ফরম্যাট ব্যবহার করতে হবে)।
    • একটি BatchGetDocuments অনুরোধে ২০টিরও বেশি নথির নাম প্রদান করা হয়েছিল।
  • 401 UNAUTHENTICATED : অনুরোধটিতে একটি এপিআই কী নেই অথবা একটি অবৈধ কী ব্যবহার করা হয়েছে। প্রমাণীকরণ দেখুন।
  • 404 NOT_FOUND : অনুরোধকৃত ডকুমেন্টের নামটি বিদ্যমান নেই অথবা এটি এমন একটি ডোমেইনের অন্তর্গত যা কর্পাসে অন্তর্ভুক্ত নয়।
  • 429 RESOURCE_EXHAUSTED : প্রকল্পটি তার কোটা অতিক্রম করেছে। কোটা ও সীমা দেখুন।

এরপর কী?