झलक दिखाने वाले एपीआई ऐक्सेस करें

इस पेज पर बताया गया है कि Classroom API में झलक देखने की सुविधाओं को कैसे ऐक्सेस किया जा सकता है और झलक के वर्शन कैसे तय किए जा सकते हैं.

स्टेबल वर्शन 1 एपीआई के साथ तुलना करते समय, झलक वाली सुविधाओं का इस्तेमाल करते समय इन दो बातों का ध्यान रखें:

  1. रिलीज़ होने से पहले इस्तेमाल करने या प्रीव्यू प्रोग्राम में एपीआई की सुविधाएं, स्टैंडर्ड क्लाइंट लाइब्रेरी में सार्वजनिक नहीं की जाती हैं. साथ ही, हो सकता है कि ये सुविधाएं एचटीटीपी पर डिफ़ॉल्ट रूप से ऐक्सेस न की जा सकें.
  2. किसी एक समय पर, झलक में एपीआई की कई स्थितियां या वर्शन हो सकते हैं.

क्लाइंट लाइब्रेरी में, झलक देखने की सुविधाएं चालू करें

Classroom एपीआई के इस्तेमाल का एक सामान्य विकल्प क्लाइंट लाइब्रेरी है. क्लाइंट लाइब्रेरी तीन तरह की होती हैं:

  1. डाइनैमिक रूप से जनरेट की गई क्लाइंट लाइब्रेरी
  2. Google से मिली स्टैटिक क्लाइंट लाइब्रेरी
  3. आपकी कस्टम क्लाइंट लाइब्रेरी

डाइनैमिक रूप से जनरेट की गई या Google की दी गई स्टैटिक लाइब्रेरी का इस्तेमाल करना, एपीआई इस्तेमाल करने का सुझाया गया तरीका है. अगर आपको अपनी लाइब्रेरी बनानी है, तो क्लाइंट लाइब्रेरी बनाना देखें. अपनी खुद की लाइब्रेरी बनाना इस गाइड के दायरे में नहीं आता, लेकिन आपको डाइनैमिक लाइब्रेरी सेक्शन पर जाना चाहिए, ताकि आप झलक लेबल और डिस्कवरी में उनकी भूमिका के बारे में जान सकें.

डाइनैमिक लाइब्रेरी

Python जैसी भाषाओं की लाइब्रेरी, रनटाइम के दौरान डिस्कवरी सेवा के डिस्कवरी दस्तावेज़ का इस्तेमाल करके, क्लाइंट लाइब्रेरी जनरेट करती हैं.

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

Classroom एपीआई सेवा (classroom.googleapis.com) के लिए, डिस्कवरी दस्तावेज़ इस एंडपॉइंट पर देखे जा सकते हैं:

https://classroom.googleapis.com/$discovery/rest?labels=PREVIEW_LABEL&version=v1&key=API_KEY

झलक एपीआई के साथ काम करने के लिए सबसे अहम अंतर यह है कि सही label बताया गया हो. Classroom की सार्वजनिक झलक के लिए, इसका लेबल DEVELOPER_PREVIEW है.

Python लाइब्रेरी जनरेट करने और झलक के तरीकों की मदद से Classroom सेवा को इंस्टैंशिएट करने के लिए, सही सेवा, क्रेडेंशियल, और लेबल का इस्तेमाल करके डिस्कवरी यूआरएल की जानकारी दी जा सकती है:

classroom_service_with_preview_features = googleapiclient.discovery.build(
  serviceName='classroom',
  version='v1',
  credentials=credentials,
  static_discovery=False,
  discoveryServiceUrl='https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key=API_KEY)'

हर भाषा के बारे में जानने के लिए, अलग-अलग Google API क्लाइंट लाइब्रेरी का दस्तावेज़ देखें.

स्टैटिक लाइब्रेरी

Java, Node.js, PHP, C#, और Go जैसी भाषाओं की क्लाइंट लाइब्रेरी, सोर्स से बनी होनी चाहिए. ये लाइब्रेरी आपके लिए उपलब्ध कराई गई हैं और इनमें झलक दिखाने की सुविधाएं पहले से ही मौजूद हैं.

सभी के लिए उपलब्ध झलक के लिए, Classroom की क्लाइंट लाइब्रेरी, Workspace Developer Preview Program की अन्य क्लाइंट लाइब्रेरी के साथ मिल सकती हैं. निजी झलक के लिए, अगर आपको स्टैटिक लाइब्रेरी जनरेट करनी हैं, तो अपने Google संपर्क से संपर्क करें.

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

उदाहरण के लिए, Go क्लाइंट लाइब्रेरी का इस्तेमाल करने के लिए, आपको अपनी go.mod फ़ाइल में replace डायरेक्टिव का इस्तेमाल करना होगा, ताकि किसी लोकल डायरेक्ट्री से मॉड्यूल ज़रूरी हो सके:

module example.com/app

go 1.21.1

require (
    golang.org/x/oauth2 v0.12.0
    google.golang.org/api v0.139.0 // Classroom library is in here.
)

require (
  ...
)

// Use a local copy of the Go client library.
replace google.golang.org/api v0.139.0 => ../google-api-go-client

एक अन्य उदाहरण के तौर पर, अगर Node.js और npm का इस्तेमाल किया जा रहा है, तो Node.js क्लाइंट लाइब्रेरी डाउनलोड (googleapis-classroom-1.0.4.tgz) को package.json में, लोकल डिपेंडेंसी के तौर पर जोड़ें:

{
  "name": "nodejs-classroom-example",
  "version": "1.0.0",
  ...
  "dependencies": {
    "@google-cloud/local-auth": "^2.1.0",
    "googleapis": "^95.0.0",
    "classroom-with-preview-features": "file:./googleapis-classroom-1.0.4.tgz"
  }
}

इसके बाद, आपको अपने ऐप्लिकेशन में सामान्य डिपेंडेंसी के साथ-साथ classroom-with-preview-features मॉड्यूल की ज़रूरत होगी और उस मॉड्यूल से classroom सेवा को इंस्टैंशिएट करें:

const {authenticate} = require('@google-cloud/local-auth');
const {google} = require('googleapis');
const classroomWithPreviewFeatures = require('classroom-with-preview-features');

...

const classroom = classroomWithPreviewFeatures.classroom({
  version: 'v1',
  auth: auth,
});

...

झलक एपीआई वर्शन तय करें

भले ही, स्टैटिक या डाइनैमिक लाइब्रेरी का इस्तेमाल किया जा रहा हो, आपको झलक वर्शन के बारे में बताना होगा. झलक देखने की सुविधा वाले तरीकों के लिए एपीआई कॉल करते समय, आपको झलक वर्शन के बारे में बताना होगा.

अलग-अलग वर्शन और उनमें शामिल सुविधाओं की जानकारी Classroom API रोडमैप में दी गई है. तरीकों और फ़ील्ड के रेफ़रंस दस्तावेज़ में यह भी बताया गया है कि वह तरीका या फ़ील्ड किस वर्शन में उपलब्ध है.

अनुरोधों में PreviewVersion फ़ील्ड सेट करके वर्शन तय किया जाता है. उदाहरण के लिए, Rubrics CRUD प्रीव्यू एपीआई की मदद से रूब्रिक बनाने के लिए, आपको CREATE के अनुरोध में previewVersion को V1_20231110_PREVIEW पर सेट करना होगा:

rubric = service.courses().courseWork().rubrics().create(
            courseId=course_id,
            courseWorkId=coursework_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW",
            body=body
).execute()

झलक के तरीके बताने वाले कॉल से जुड़े संसाधनों में, कॉल में इस्तेमाल किए गए previewVersion को भी रीड-ओनली फ़ील्ड के तौर पर शामिल किया जाता है. इससे, आपको यह समझने में मदद मिलती है कि कौनसा वर्शन इस्तेमाल किया जा रहा है. उदाहरण के लिए, पिछले CREATE कॉल के रिस्पॉन्स में V1_20231110_PREVIEW वैल्यू शामिल है:

print(json.dumps(rubric, indent=4))
{
  "courseId": "123",
  "courseWorkId": "456",
  "creationTime": "2023-10-23T18:18:29.932Z",
  "updateTime": "2023-10-23T18:18:29.932Z",
  "id": "789",
  "criteria": [...],
  # The preview version used in the call that returned this resource.
  "previewVersion": "V1_20231110_PREVIEW",
  ...
}

एचटीटीपी अनुरोध

Classroom एपीआई का इस्तेमाल, एचटीटीपी के साथ भी किया जा सकता है.

अगर क्लाइंट लाइब्रेरी के बिना एचटीटीपी अनुरोध किए जाते हैं, तब भी आपको 'झलक देखें' सुविधाओं को चालू करना होगा, ताकि झलक वर्शन के बारे में बताया जा सके. ऐसा करने के लिए, X-Goog-Visibilities हेडर के साथ label और ऊपर दिए गए झलक वर्शन को क्वेरी पैरामीटर या पोस्ट के बॉडी फ़ील्ड के तौर पर सेट किया जाता है. सभी के लिए उपलब्ध झलक के लिए, लेबल DEVELOPER_PREVIEW है.

उदाहरण के लिए, नीचे दिया गया कर्ल अनुरोध उचित दृश्यता लेबल और झलक वर्शन के साथ रूब्रिक सेवा को LIST कॉल देता है:

curl \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_ID/rubrics?key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --compressed

अनुरोध के मुख्य हिस्से में झलक के वर्शन के बारे में भी बताया जा सकता है. उदाहरण के लिए, पोस्ट अनुरोध करते समय:

curl --request PATCH \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_ID//rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]", "preview_version": "V1_20231110_PREVIEW"}' \
  --compressed

हर एचटीटीपी अनुरोध के एपीआई के बारे में, REST दस्तावेज़ में बताया गया है.