האם המשתמשים שלך משתמשים ב-Classroom דרך Google Meet? רוצים לדעת איך בודקים את הנוכחות של התלמידים בקורסים של Google Meet? הסקריפט למתחילים של Apps Script

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

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

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

שני השיקולים שיש להביא בחשבון כשמשתמשים בתכונות של תצוגה מקדימה בהשוואה ל-API היציב v1 הם:

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

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

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

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

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

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

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

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

אפשר למצוא את מסמכי Discovery של שירות 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,
});

...

ציון גרסת ה-API לתצוגה המקדימה

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

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

ציון גרסה מתבצע על ידי הגדרת השדה PreviewVersion בבקשות. לדוגמה, כדי ליצור קריטריון הערכה באמצעות Rubrics CRUD Preview API, צריך להגדיר את 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

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

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

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

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

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