दस्तावेज़ खोजना और उन्हें वापस पाना

इस गाइड में, Developer Knowledge API का इस्तेमाल करके, Google के सार्वजनिक डेवलपर दस्तावेज़ों को प्रोग्राम के हिसाब से खोजने और वापस पाने का तरीका बताया गया है. एपीआई, वेब पेजों को मैन्युअल तरीके से स्क्रैप करने के बजाय, आपके ऐप्लिकेशन को काम के टेक्स्ट स्निपेट ढूंढने या पूरे Markdown दस्तावेज़ फ़ेच करने में मदद करता है.

इस दस्तावेज़ में, आपको इन टास्क के उदाहरण मिलेंगे:

  • दस्तावेज़ों के कॉर्पस में खोजा जा रहा है.
  • खोज के नतीजों को पेजों में बांटना.
  • आपकी खोज के लिए, मुश्किल फ़िल्टर लागू किए जा रहे हैं.
  • पूरे दस्तावेज़ का कॉन्टेंट वापस पाना.
  • जवाब के पेलोड को ऑप्टिमाइज़ करके, इंतज़ार के समय को कम किया जाता है.

शुरू करने से पहले, पक्का करें कि आपने एपीआई चालू कर दिया हो और डेवलपर नॉलेज एपीआई पासकोड जनरेट कर लिया हो. इसके बाद, अपनी कुंजी को किसी एनवायरमेंट वैरिएबल में सेव करें:

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 (पूर्णांक): इससे हर पेज पर ज़्यादा से ज़्यादा नतीजे दिखाने की संख्या तय की जाती है. अगर कोई वैल्यू नहीं दी जाती है, तो एपीआई डिफ़ॉल्ट रूप से पांच नतीजे दिखाता है. ज़्यादा से ज़्यादा 100 वैल्यू डाली जा सकती हैं. 100 से ज़्यादा वैल्यू डालने पर, उन्हें 100 में बदल दिया जाता है.
  • 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 एक्सप्रेशन में ज़्यादा से ज़्यादा 500 वर्ण हो सकते हैं.

इस्तेमाल किए जा सकने वाले फ़ील्ड

पेरेंट दस्तावेज़ के इन फ़ील्ड का इस्तेमाल करके, खोज के नतीजों को फ़िल्टर किया जा सकता है:

  • content_length_bytes (पूर्णांक): दस्तावेज़ के content फ़ील्ड की लंबाई, बाइट में.
  • data_source (string): दस्तावेज़ का सोर्स डोमेन, जैसे कि docs.cloud.google.com या firebase.google.com. इस्तेमाल किए जा सकने वाले सभी डेटा सोर्स के लिए, कॉर्पस रेफ़रंस देखें.
  • update_time (टाइमस्टैंप): वह टाइमस्टैंप जब दस्तावेज़ को आखिरी बार अपडेट किया गया था. वैल्यू, आरएफ़सी 3339 फ़ॉर्मैट में होनी चाहिए. उदाहरण के लिए, "2025-01-01T00:00:00Z".
  • uri (string): दस्तावेज़ का पूरा यूआरआई (उदाहरण के लिए, https://docs.cloud.google.com/bigquery/docs/tables).

ये ऑपरेटर इस्तेमाल किए जा सकते हैं

फ़िल्टर एक्सप्रेशन पार्सर, फ़ील्ड के डेटा टाइप के आधार पर अलग-अलग ऑपरेटर इस्तेमाल करता है:

  • स्ट्रिंग फ़ील्ड (data_source, uri): स्ट्रिंग से पूरी तरह मेल खाने के लिए, = (बराबर है) और != (बराबर नहीं है) का इस्तेमाल किया जा सकता है. प्रीफ़िक्स, रेगुलर एक्सप्रेशन, और कुछ हद तक मिलते-जुलते शब्दों का इस्तेमाल नहीं किया जा सकता.
  • टाइमस्टैंप फ़ील्ड (update_time): =, <, <=, >, और >= के साथ काम करते हैं.
  • पूर्णांक फ़ील्ड (content_length_bytes): =, !=, <, <=, >, और >= के साथ काम करते हैं.
  • लॉजिकल ऑपरेटर: AND, OR, और NOT (या -) का इस्तेमाल करके शर्तों को मिलाएं.

फ़िल्टर के उदाहरण

यहां दिए गए उदाहरणों में, फ़िल्टर एक्सप्रेशन बनाने का तरीका बताया गया है. curl के साथ REST API को कॉल करते समय, फ़िल्टर पैरामीटर को यूआरएल-कोड में बदलें या --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 तरीके का इस्तेमाल करें.

संसाधन के नाम बनाम यूआरआई

Developer Knowledge API में दस्तावेज़ों का रेफ़रंस देते समय, संसाधन के नामों और वेब यूआरआई के बीच अंतर को ध्यान में रखें:

  • संसाधन का नाम (parent, name): इसे documents/{uri_without_scheme} के तौर पर फ़ॉर्मैट किया जाता है. उदाहरण के लिए, documents/docs.cloud.google.com/storage/docs/creating-buckets. इस वैल्यू को GetDocument में पाथ पैरामीटर के तौर पर या 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 की मदद से एक से ज़्यादा दस्तावेज़ों को वापस पाना

एक ही एपीआई कॉल में, नाम के हिसाब से ज़्यादा से ज़्यादा 20 दस्तावेज़ वापस पाने के लिए, 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"

फ़ील्ड मास्क का इस्तेमाल करना

जवाब के पेलोड को कुछ फ़ील्ड तक सीमित करने के लिए, Google के स्टैंडर्ड एपीआई के 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"

गड़बड़ियां ठीक करना

Developer Knowledge API, स्टैंडर्ड एचटीटीपी स्टेटस कोड दिखाता है. यहां दिए गए उदाहरणों में, Developer Knowledge API में एचटीटीपी स्टेटस कोड और उनकी वजहों के बारे में बताया गया है:

  • 400 INVALID_ARGUMENT:
    • filter एक्सप्रेशन स्ट्रिंग में 500 से ज़्यादा वर्ण हैं.
    • update_time टाइमस्टैंप अमान्य है. इसके लिए, आरएफ़सी 3339 फ़ॉर्मैट का इस्तेमाल करना ज़रूरी है.
    • BatchGetDocuments अनुरोध में, 20 से ज़्यादा दस्तावेज़ों के नाम दिए गए थे.
  • 401 UNAUTHENTICATED: अनुरोध में एपीआई पासकोड मौजूद नहीं है या अमान्य पासकोड का इस्तेमाल किया गया है. पुष्टि करना देखें.
  • 404 NOT_FOUND: अनुरोध किया गया दस्तावेज़ मौजूद नहीं है या यह ऐसे डोमेन से जुड़ा है जो कॉर्पस में शामिल नहीं है.
  • 429 RESOURCE_EXHAUSTED: प्रोजेक्ट ने अपना कोटा पूरा कर लिया है. कोटा और सीमाएं देखें.

आगे क्या करना है