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

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

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

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

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

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

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

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

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

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

जानकारी देने वाला दस्तावेज़, मशीन से पढ़े जा सकने वाले फ़ॉर्मैट में होता है. इसमें REST API के बारे में जानकारी दी जाती है और उन्हें इस्तेमाल करने का तरीका बताया जाता है. इसका इस्तेमाल क्लाइंट लाइब्रेरी बनाने, आईडीई प्लगिन, और 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 का इस्तेमाल किया जा रहा है, तो 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 preview API की मदद से कोई रूब्रिक बनाने के लिए, 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 को सीधे तौर पर एचटीटीपी के साथ भी इस्तेमाल किया जा सकता है.

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

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

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 प्रोजेक्ट का आईडी डालें जिसे आपने डेवलपर प्रीव्यू प्रोग्राम में रजिस्टर किया है. डिफ़ॉल्ट रूप से, 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 को सीधे तौर पर एचटीटीपी कॉल करने के लिए, आपको सही स्कोप मैन्युअल तरीके से जोड़ने होंगे.

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

अपडेट की गई 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);
}