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

इस पेज पर, 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 की उन सुविधाओं के लिए जो Public Preview प्रोग्राम में शामिल हैं, यह लेबल 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 को सीधे तौर पर HTTP के साथ भी इस्तेमाल किया जा सकता है.

अगर क्लाइंट लाइब्रेरी के बिना एचटीटीपी अनुरोध किए जाते हैं, तो आपको झलक वाली सुविधाएं चालू करनी होंगी. साथ ही, झलक वाला वर्शन तय करना होगा. इसके लिए, 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 प्रोजेक्ट बदलना

प्रोजेक्ट की सेटिंग में जाकर, प्रोजेक्ट बदलें पर क्लिक करें. इसके बाद, उस 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);
}