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

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

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

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

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

Classroom API का इस्तेमाल करने का एक सामान्य तरीका, क्लाइंट लाइब्रेरी का इस्तेमाल करना है. क्लाइंट लाइब्रेरी तीन तरह की होती हैं:

1. डाइनैमिक तौर पर जनरेट की गई क्लाइंट लाइब्रेरी
2. Google की दी गई स्टैटिक क्लाइंट लाइब्रेरी
3. अपनी पसंद के मुताबिक बनाई गई क्लाइंट लाइब्रेरी

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

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

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

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

Classroom API सेवा (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 का इस्तेमाल किया जा रहा है, तो package.json में Node.js क्लाइंट लाइब्रेरी डाउनलोड (googleapis-classroom-1.0.4.tgz) को लोकल डिपेंडेंसी के तौर पर जोड़ें:

{
  "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 API का इस्तेमाल सीधे HTTP के साथ भी किया जा सकता है.

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

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

curl \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_WORK_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_WORK_ID/rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]"}' \
  --compressed

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

Google Apps Script

Google Apps Script से झलक वाले एपीआई को कॉल किया जा सकता है. हालांकि, Apps Script के सामान्य इस्तेमाल से इसमें कुछ अंतर हैं.

1. आपको अपनी स्क्रिप्ट को कॉन्फ़िगर करना होगा, ताकि उस Google Cloud प्रोजेक्ट का इस्तेमाल किया जा सके जिसे आपने Developer Preview Program में रजिस्टर किया है.
2. ऐडवांस सेवाएं, झलक देखने के तरीकों के साथ काम नहीं करतीं. इसलिए, आपको सीधे एचटीटीपी से अनुरोध करने होंगे.
3. आपको लेबल और झलक वाला वर्शन देना होगा, जैसा कि पिछले एचटीटीपी सेक्शन में बताया गया है.

Apps Script के बारे में जानने और कोई बुनियादी प्रोजेक्ट सेट अप करने के लिए, इससे जुड़ा क्विकस्टार्ट देखें. इसके बाद, झलक वाले एपीआई को कॉल करने के लिए, इन निर्देशों का पालन करें:

स्क्रिप्ट में इस्तेमाल किया गया Cloud प्रोजेक्ट बदलना

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

एचटीटीपी अनुरोध कॉन्फ़िगर करना

इसके बाद, एडिटर में, उस तरीके के एचटीटीपी अनुरोध को कॉन्फ़िगर करें जिसे आपको कॉल बैक करना है. उदाहरण के लिए, क्विकस्टार्ट में, Classroom की सेवा के साथ कोर्स की सूची इस तरह दिखती है:

function listCourses() {
  try {
    const response = Classroom.Courses.list();
    const courses = response.courses;
    if (!courses || courses.length === 0) {
      console.log('No courses found.');
      return;
    }
    for (const course of courses) {
      console.log('%s (%s)', course.name, course.id);
    }
  } catch (err) {
    // TODO: Developer to handle.
    console.log(err.message);
  }
}

सीधे एचटीटीपी का इस्तेमाल करके, यह काम करने का तरीका है:

function listCourses() {
  const response = UrlFetchApp.fetch(
        'https://classroom.googleapis.com/v1/courses', {
        method: 'GET',
        headers: {'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()},
        contentType: 'application/json',
      });
  const data = JSON.parse(response.getContentText());
  if (data.error) {
    // TODO: Developer to handle.
    console.log(err.message);
    return;
  }
  if (!data.courses || !data.courses.length) {
    console.log('No courses found.');
    return;
  }
  for (const course of data.courses) {
    console.log('%s (%s)', course.name, course.id);
  }
}

ऐडवांस सेवाओं का इस्तेमाल करते समय, ज़रूरी OAuth स्कोप का अनुमान लगाया जाता है. हालांकि, Apps Script में Google API को सीधे HTTP कॉल करने के लिए, आपको मैन्युअल रूप से सही स्कोप जोड़ने होंगे.

प्रोजेक्ट सेटिंग में, एडिटर में "appsscript.json" मेनिफ़ेस्ट फ़ाइल दिखाएं को चालू करें. एडिटर में वापस जाकर, appscript.json फ़ाइल में oauthScopes जोड़ें. ऐसा उन सभी स्कोप के लिए करें जिनकी आपको ज़रूरत है. किसी दिए गए तरीके के स्कोप, रेफ़रंस पेज में दिए गए हैं. उदाहरण के लिए, courses.courseWork.rubrics list method page देखें.

अपडेट की गई appscript.json फ़ाइल कुछ इस तरह दिख सकती है:

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/classroom.coursework.students",
    "https://www.googleapis.com/auth/classroom.courses",
    "https://www.googleapis.com/auth/spreadsheets.readonly",
    "https://www.googleapis.com/auth/spreadsheets"
  ]
}

लेबल और झलक वाला वर्शन दें

अपनी स्क्रिप्ट पर वापस जाकर, पक्का करें कि आपने सही लेबल और झलक वाला वर्शन जोड़ा हो. इस बारे में, पिछले एचटीटीपी सेक्शन में बताया गया है. Rubrics सेवा के लिए LIST कॉल का उदाहरण ऐसा दिखेगा:

function listRubrics() {
  const courseId = COURSE_ID;
  const courseWorkId = COURSE_WORK_ID;
  const response = UrlFetchApp.fetch(
         `https://classroom.googleapis.com/v1/courses/${courseId}/courseWork/${courseWorkId}/rubrics?previewVersion=V1_20231110_PREVIEW`, {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer ' + ScriptApp.getOAuthToken(),
          'X-Goog-Visibilities': 'DEVELOPER_PREVIEW'
        },
        contentType: 'application/json',
        muteHttpExceptions: true
      });
  const data = JSON.parse(response.getContentText());
  console.log(data)
  if (data.error) {
    // TODO: Developer to handle.
    console.log(error.message);
    return;
  }
  if (!data.rubrics || !data.rubrics.length) {
    console.log('No rubrics for this coursework!');
    return;
  }
  console.log(data.rubrics);
}