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

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

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

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

शुरू करने से पहले, अपने पसंदीदा टूल के लिए एनवायरमेंट सेट अप करें:

gcloud

gcloud सीएलआई इंस्टॉल और कॉन्फ़िगर करें. साथ ही, Developer Knowledge API चालू करें.

REST

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

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

YOUR_API_KEY को अपने Developer Knowledge API पासकोड से बदलें.

दस्तावेज़ खोजना

क्वेरी स्ट्रिंग से मेल खाने वाले दस्तावेज़ के हिस्सों को खोजने के लिए, gcloud developer-knowledge documents search-chunks कमांड या documents.searchDocumentChunks REST तरीके का इस्तेमाल करें. नतीजों में, मिलते-जुलते दस्तावेज़ों के कॉन्टेंट के कुछ हिस्से शामिल होते हैं. साथ ही, एक parent रेफ़रंस होता है. इसका इस्तेमाल करके, उन दस्तावेज़ों का पूरा कॉन्टेंट पाया जा सकता है.

यहां दिए गए उदाहरण में, "BigQuery" से मिलते-जुलते दस्तावेज़ों को खोजा जा रहा है:

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery"

REST

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 का रेफ़रंस देखें.

खोज के नतीजों को पेजों में बांटना

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

  • --page-size (gcloud सीएलआई) या pageSize (पूर्णांक): इससे यह तय होता है कि हर पेज पर ज़्यादा से ज़्यादा कितने नतीजे दिखाए जाएं. अगर कोई जानकारी नहीं दी गई है, तो एपीआई डिफ़ॉल्ट रूप से पांच नतीजे दिखाता है. ज़्यादा से ज़्यादा 100 वैल्यू डाली जा सकती हैं. 100 से ज़्यादा वैल्यू डालने पर, उन्हें 100 पर सेट कर दिया जाता है.

  • --limit (gcloud सीएलआई) या pageToken (स्ट्रिंग): gcloud सीएलआई में, --limit का इस्तेमाल करके, सभी पेजों पर दिखाए जाने वाले नतीजों की कुल संख्या को कंट्रोल करें. REST अनुरोधों में, नतीजों का अगला पेज फ़ेच करने के लिए, पिछले जवाब में मिली pageToken वैल्यू पास करें.

gcloud

हर पेज पर दिखाए जाने वाले नतीजों की संख्या और दिखाए गए कुल नतीजों की संख्या को कंट्रोल करने के लिए, --page-size और --limit फ़्लैग पास करें:

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --page-size=5 \
  --limit=10

REST

  1. पहले पेज का अनुरोध करने के लिए, अपने अनुरोध में 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"
}

  2. इसके बाद के पेजों को वापस पाने के लिए, अपने अगले अनुरोध में pageToken पैरामीटर को nextPageToken की वैल्यू पास करें:

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

    नतीजों के आखिरी पेज पर पहुंचने पर, जवाब में nextPageToken नहीं दिखता.

खोज के नतीजों को फ़िल्टर करना

खोज के नतीजों पर सख्त फ़िल्टर लागू करने के लिए, gcloud CLI में --query-filter फ़्लैग या REST अनुरोधों में 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 (या -) का इस्तेमाल करके शर्तों को मिलाएं.

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

यहां दिए गए उदाहरणों में, फ़िल्टर एक्सप्रेशन बनाने का तरीका बताया गया है. gcloud सीएलआई का इस्तेमाल करते समय, एक्सप्रेशन को --query-filter फ़्लैग में पास करें. curl के साथ REST API को कॉल करते समय, पक्का करें कि आपने filter पैरामीटर को यूआरएल-कोड में बदला हो या --data-urlencode का इस्तेमाल किया हो.

किसी एक डेटा सोर्स को मैच करना

खोज के नतीजों को किसी एक दस्तावेज़ डोमेन तक सीमित करने के लिए:

data_source = "docs.cloud.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Functions deployment" \
  --query-filter='data_source = "docs.cloud.google.com"'

REST

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

एक से ज़्यादा डेटा सोर्स मैच करना

एक से ज़्यादा सोर्स से दस्तावेज़ शामिल करने के लिए, OR का इस्तेमाल करें:

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

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="database" \
  --query-filter='data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"'

REST

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"

टाइमस्टैंप के हिसाब से फ़िल्टर करना

किसी खास तारीख के बाद अपडेट किया गया कॉन्टेंट ढूंढने के लिए, आरएफ़सी 3339 टाइमस्टैंप के साथ कंपैरिज़न ऑपरेटर का इस्तेमाल करें:

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

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --query-filter='update_time >= "2025-01-01T00:00:00Z"'

REST

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

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Storage" \
  --query-filter='content_length_bytes < 5000'

REST

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"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="service worker" \
  --query-filter='(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"'

REST

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"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="authentication" \
  --query-filter='data_source != "firebase.google.com"'

REST

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"

दस्तावेज़ वापस पाना

किसी एक दस्तावेज़ का पूरा कॉन्टेंट वापस पाने के लिए, gcloud developer-knowledge documents describe कमांड या documents.get REST तरीके का इस्तेमाल करें.

यहां दिए गए उदाहरण में, किसी दस्तावेज़ को उसके संसाधन के नाम से वापस पाया गया है:

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets

REST

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

जवाब, Document संसाधन है. इसमें मेटाडेटा और content फ़ील्ड में पूरा मार्कडाउन कॉन्टेंट शामिल होता है.

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

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

  • संसाधन का नाम (parent, name): इसे इस तरह फ़ॉर्मैट किया जाता है documents/{uri_without_scheme} (उदाहरण के लिए, documents/docs.cloud.google.com/storage/docs/creating-buckets). इस वैल्यू को gcloud developer-knowledge documents describe में पोज़िशनल आर्ग्युमेंट के तौर पर, GetDocument में पाथ पैरामीटर के तौर पर या BatchGetDocuments के names पैरामीटर में पास करें.
  • वेब यूआरआई (uri): यह पूरा वेब यूआरएल होता है. इसमें स्कीम भी शामिल होती है. उदाहरण के लिए, https://docs.cloud.google.com/storage/docs/creating-buckets. --query-filter या filter एक्सप्रेशन बनाते समय, uri फ़ील्ड के लिए इस फ़ॉर्मैट का इस्तेमाल करें. उदाहरण के लिए, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets".

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 संसाधनों की सूची होती है. यह सूची, आपके अनुरोध के क्रम में होती है.

जवाब के पेलोड को ऑप्टिमाइज़ करना

मार्कडाउन फ़ॉर्मैट में दस्तावेज़ का कॉन्टेंट बड़ा हो सकता है. अगर आपके ऐप्लिकेशन को सिर्फ़ मेटाडेटा (जैसे, पेज के टाइटल, यूआरआई या टाइमस्टैंप) या कुछ फ़ील्ड की ज़रूरत है, तो बैंडविड्थ और लेटेन्सी को कम करने के लिए, पेलोड के साइज़ को ऑप्टिमाइज़ किया जा सकता है.

दस्तावेज़ व्यू का इस्तेमाल करना

gcloud CLI में मौजूद --view फ़्लैग या REST अनुरोधों में मौजूद view पैरामीटर से यह कंट्रोल किया जाता है कि Document मैसेज में कौनसे फ़ील्ड भरे गए हैं.

--view फ़्लैग और DocumentView एनम के लिए, ये वैल्यू इस्तेमाल की जा सकती हैं:

  • --view=basic (gcloud CLI) या DOCUMENT_VIEW_BASIC: सिर्फ़ बुनियादी मेटाडेटा फ़ील्ड (name, uri, dataSource, title, description, updateTime, और view) दिखाता है. content फ़ील्ड को शामिल नहीं किया जाता.
  • --view=content (gcloud सीएलआई) या DOCUMENT_VIEW_CONTENT: मेटाडेटा फ़ील्ड के साथ-साथ Markdown content फ़ील्ड दिखाता है. यह gcloud developer-knowledge documents describe, GetDocument, और BatchGetDocuments के लिए डिफ़ॉल्ट सेटिंग है.
  • --view=full (gcloud सीएलआई) या DOCUMENT_VIEW_FULL: इससे दस्तावेज़ के सभी फ़ील्ड दिखते हैं.

बड़े मार्कडाउन कॉन्टेंट को डाउनलोड किए बिना, सिर्फ़ दस्तावेज़ का मेटाडेटा वापस पाने के लिए, दस्तावेज़ का बुनियादी व्यू तय करें:

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets \
  --view=basic

REST

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

view=DOCUMENT_VIEW_BASIC को BatchGetDocuments के साथ भी इस्तेमाल किया जा सकता है:

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 टाइमस्टैंप अमान्य है. इसका फ़ॉर्मैट RFC 3339 होना चाहिए.
    • BatchGetDocuments अनुरोध में, 20 से ज़्यादा दस्तावेज़ों के नाम दिए गए थे.
  • 401 UNAUTHENTICATED: अनुरोध में एपीआई पासकोड मौजूद नहीं है या अमान्य पासकोड का इस्तेमाल किया गया है. पुष्टि करना लेख पढ़ें.
  • 404 NOT_FOUND: अनुरोध किया गया दस्तावेज़ मौजूद नहीं है या यह ऐसे डोमेन से जुड़ा है जो कॉर्पस में शामिल नहीं है.
  • 429 RESOURCE_EXHAUSTED: प्रोजेक्ट ने अपना कोटा पूरा कर लिया है. कोटा और सीमाएं देखें.

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