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

इस पेज पर, 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 सेवा को पूर्वावलोकन के तरीकों के साथ इंस्टैंटिएट करने के लिए, सही सेवा, क्रेडेंशियल, और लेबल के साथ Discovery यूआरएल तय किया जा सकता है:

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 प्रोजेक्ट बदलना

प्रोजेक्ट की सेटिंग में जाकर, प्रोजेक्ट बदलें पर क्लिक करें. इसके बाद, उस Cloud प्रोजेक्ट का आईडी डालें जिसे आपने Developer Preview Program में रजिस्टर किया है. डिफ़ॉल्ट रूप से, 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);
}