תוספים ל-Google Classroom זמינים עכשיו למפתחים! למידע נוסף, יש לעיין במסמכי התיעוד בנושא תוספים.

דף זה תורגם על ידי Cloud Translation API.

גישה לממשקי API לתצוגה מקדימה

בדף הזה נסביר איך לגשת לתכונות של Classroom API בגרסה טרום-השקה, ואיך לציין גרסאות טרום-השקה.

שלושת השיקולים לשימוש בתכונות בגרסת טרום-השקה (Preview) בהשוואה ל-API היציב בגרסה 1 הם:

הפרויקט של הקריאה ב-Google Cloud צריך להיות רשום לתוכנית התצוגה המקדימה למפתחים של Google Workspace, ולאפשר את התיעוד של Google Workspace.
תכונות ה-API בתוכניות גישה מוקדמת או בתצוגה מקדימה לא מוצגות בספריות הלקוח הסטנדרטיות, ויכול להיות שלא תהיה אליהן גישה כברירת מחדל דרך HTTP.
בכל רגע נתון יכולים להיות כמה מצבים או גרסאות של API בתצוגה מקדימה.

הפעלת תכונות של תצוגה מקדימה בספריות לקוח

אפשרות נפוצה לשימוש ב-Classroom API היא באמצעות ספריית לקוח. יש שלושה סוגים של ספריות לקוח:

ספריות לקוח שנוצרות באופן דינמי
ספריות לקוח סטטיות ש-Google מספקת
ספריית לקוח בהתאמה אישית

מומלץ להשתמש ב-API באמצעות ספריות סטטיות שנוצרו באופן דינמי או ספריות סטטיות ש-Google מספקת. אם אתם צריכים ליצור ספרייה משלכם, ראו יצירת ספריות לקוח. יצירת ספרייה משלכם לא נכללת בהיקף המדריך הזה, אבל כדאי לעיין בקטע ספריות דינמיות כדי ללמוד על תוויות תצוגה מקדימה ועל התפקיד שלהן במודעות Discovery.

ספריות דינמיות

ספריות בשפות כמו Python יוצרות את ספריית הלקוח בזמן הריצה באמצעות מסמך גילוי משירות הגילוי.

מסמך Discovery הוא מפרט שקריא למכונות, שמתאר ממשקי API ל-REST ומאפשר להשתמש בהם. הוא משמש לבניית ספריות לקוח, יישומי פלאגין של סביבת פיתוח משולבת (IDE) וכלים אחרים שיוצרים אינטראקציה עם Google APIs. שירות אחד עשוי לספק כמה מסמכי גילוי.

מסמכי הגילוי של שירות Classroom API‏ (classroom.googleapis.com) נמצאים בנקודת הקצה הבאה:

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

ההבחנה החשובה בעבודה עם ממשקי API לתצוגה מקדימה היא לציין את ה-label המתאים. בתצוגות המקדימה הציבוריות של Classroom, התווית היא DEVELOPER_PREVIEW.

כדי ליצור את ספריית Python וליצור מופע של שירות Classroom באמצעות שיטות של תצוגה מקדימה, אפשר לציין את כתובת ה-URL של 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. כדי לראות תצוגות מקדימות פרטיות, צריך לפנות לאיש הקשר ב-Google אם אתם צריכים ליצור ספריות סטטיות.

יכול להיות שתצטרכו לשנות את הגדרות התלות הרגילות כדי להשתמש בספריות המקומיות האלה במקום לייבא את ספריות הלקוח הסטנדרטיות, שאין בהן את תכונות התצוגה המקדימה.

לדוגמה, כדי להשתמש בספריית הלקוח של Go, צריך להשתמש בהוראה replace בקובץ go.mod כדי לדרוש מודול מספרייה מקומית:

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,
});

...

ציון גרסת Preview API

לא משנה אם אתם משתמשים בספרייה סטטית או דינמית, עליכם לציין את גרסת ה-preview כשאתם מבצעים קריאות ל-API לשיטות עם יכולות של תצוגה מקדימה.

הגרסאות השונות הזמינות והתכונות שהן כוללות מתועדות בתוכנית העבודה של Classroom API. במסמכי העזרה של השיטות והשדות מפורטות גם הגרסאות שבהן השיטה או השדה זמינים.

כדי לציין גרסה, מגדירים את השדה PreviewVersion בבקשות. לדוגמה, כדי ליצור קריטריון הערכה באמצעות ה-API של Rubrics CRUD preview, צריך להגדיר את previewVersion כ-V1_20231110_PREVIEW בבקשת ה-CREATE:

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",
  ...
}

בקשות HTTP

אפשר גם לצרוך את Classroom API ישירות באמצעות HTTP.

אם שולחים בקשות HTTP בלי ספריית לקוח, עדיין צריך להפעיל את התכונות של התצוגה המקדימה ולציין את גרסת התצוגה המקדימה. כדי לעשות זאת, מגדירים את label עם כותרת X-Goog-Visibilities וגרסת התצוגה המקדימה שצוינה למעלה כפרמטר של שאילתה או כשדה גוף של POST (ראו את מסמכי העזרה המתאימים של ה-API). בתצוגות מקדימות ציבוריות, התווית היא DEVELOPER_PREVIEW.

לדוגמה, בקשת ה-curl הבאה מבצעת קריאת LIST לשירות Rubrics עם תווית החשיפה וגרסת התצוגה המקדימה המתאימות:

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

ה-API לכל בקשת HTTP מתואר במסמכי העזרה של REST.

Google Apps Script

אפשר לבצע קריאה לממשקי API בתצוגה מקדימה מ-Google Apps Script. עם זאת, יש כמה הבדלים ביחס לשימוש הרגיל ב-Apps Script.

תצטרכו להגדיר את הסקריפט כך שישתמש בפרויקט ב-Google Cloud שרשמתם לתוכנית התצוגה המקדימה למפתחים.
Advanced Services לא תומכים בשיטות תצוגה מקדימה, לכן תצטרכו לשלוח בקשות ישירות באמצעות HTTP.
חובה לספק תווית וגרסה של תצוגה מקדימה, כפי שמתואר בקטע הקודם בנושא HTTP.

מומלץ לעיין במדריך למתחילים המתאים כדי להכיר את Apps Script ולהגדיר פרויקט בסיסי. לאחר מכן צריך לבצע את ההוראות הבאות כדי להתחיל בקריאה לממשקי API של תצוגה מקדימה:

שינוי הפרויקט ב-Cloud שבו נעשה שימוש בסקריפט

בקטע Project Settings, לוחצים על Change project ומזינים את מזהה הפרויקט ב-Cloud של הפרויקט שנרשמ לתוכנית Developer Preview (ברירת המחדל היא שימוש בפרויקט כללי בסקריפטים של Apps Script). רק פרויקטים רשומים יכולים להפעיל שיטות של תצוגה מקדימה.

הגדרת בקשות HTTP

בשלב הבא, מגדירים את בקשת ה-HTTP של השיטה שרוצים לבצע לה קריאה חוזרת בעורך. לדוגמה, במדריך למתחילים, הצגת קורסים באמצעות השירות 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);
  }
}

הפעולה המקבילה באמצעות HTTP ישירות היא:

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 משוערים, אבל כדי לבצע קריאות HTTP ישירות ל-Google APIs ב-Apps Script, צריך להוסיף את ההיקפים המתאימים באופן ידני.

בקטע Project Settings (הגדרות הפרויקט), מפעילים את האפשרות Show "appsscript.json" manifest file in editor (הצגת קובץ המניפסט 'appsscript.json' בעורך). חוזרים ל-Editor, מוסיפים את oauthScopes לקובץ appscript.json בהתאם להיקפים שאתם צריכים. ההיקפים של שיטה מסוימת מפורטים בדף העזרה. לדוגמה, תוכלו לעיין בדף ה-methods של רשימת הקורסים בסגנוןcourseWork.rubrics.

קובץ 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"
  ]
}

מציינים תווית וגרסה של תצוגה מקדימה

חזרה לסקריפט, מוודאים שהוספתם את התווית המתאימה ואת גרסת התצוגה המקדימה, כפי שמתואר בקטע HTTP הקודם. קריאת ה-LIST לדוגמה לשירות Rubrics תיראה כך:

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);
}