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

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

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

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

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

gcloud

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

आराम का समय

एपीआई को चालू करें और 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"

आराम का समय

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

आराम का समय

  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. इसके बाद के पेजों को वापस पाने के लिए, अपने अगले अनुरोध में nextPageToken की वैल्यू को pageToken पैरामीटर में पास करें:

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

आराम का समय

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"'

आराम का समय

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"'

आराम का समय

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"'

आराम का समय

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

आराम का समय

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 = "https://docs.cloud.google.com/storage/docs/creating-buckets") बनाते समय, uri फ़ील्ड के लिए इस फ़ॉर्मैट का इस्तेमाल करें.

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 enum के लिए, ये वैल्यू इस्तेमाल की जा सकती हैं:

  • --view=basic (gcloud CLI) या DOCUMENT_VIEW_BASIC: सिर्फ़ बुनियादी मेटाडेटा फ़ील्ड (name, uri, dataSource, title, description, updateTime, और view) दिखाता है. content फ़ील्ड को शामिल नहीं किया जाता.
  • --view=content (gcloud सीएलआई) या DOCUMENT_VIEW_CONTENT: मार्कडाउन 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

आराम का समय

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: प्रोजेक्ट ने अपना कोटा पूरा कर लिया है. कोटा और सीमाएं देखें.

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