בדף הזה מוסבר איך לגשת לתכונות בתצוגה מקדימה של Classroom API ולציין גרסאות בתצוגה מקדימה.
יש שלושה שיקולים שצריך לקחת בחשבון כשמשתמשים בתכונות בגרסת Preview בהשוואה ל-API היציב בגרסה 1:
- הפרויקט ב-Google Cloud שממנו מתבצעת השיחה צריך להיות רשום בתוכנית התצוגה המקדימה למפתחים של Google Workspace, ולהיכלל ברשימת ההיתרים של Google.
- תכונות API בתוכניות גישה מוקדמת או בתקופת ניסיון לא מוצגות בספריות הלקוח הרגילות, ויכול להיות שלא תהיה אליהן גישה כברירת מחדל דרך HTTP.
- יכול להיות שבכל רגע נתון יהיו כמה מצבים או גרסאות של API בתצוגה מקדימה.
הפעלת תכונות בתצוגה מקדימה בספריות לקוח
אפשרות נפוצה לשימוש ב-Classroom API היא באמצעות ספריית לקוח. יש שלושה סוגים של ספריות לקוח:
- ספריות לקוח שנוצרות באופן דינמי
- ספריות לקוח סטטיות ש-Google מספקת
- ספריית לקוח מותאמת אישית משלכם
הדרך המומלצת להשתמש ב-API היא באמצעות ספריות סטטיות שנוצרות באופן דינמי או ספריות סטטיות ש-Google מספקת. אם אתם צריכים ליצור ספרייה משלכם, תוכלו לעיין במאמר בנושא יצירת ספריות לקוח. יצירת ספרייה משלכם היא מעבר להיקף המדריך הזה, אבל כדאי לעיין בקטע ספריות דינמיות כדי לקבל מידע על תוויות תצוגה מקדימה והתפקיד שלהן ב-Discovery.
ספריות דינמיות
ספריות בשפות כמו Python יוצרות את ספריית הלקוח בזמן הריצה באמצעות מסמך גילוי משירות הגילוי.
מסמך 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 בגרסת Preview היא ציון label
המתאים. בתוכניות Public Preview של 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
לא משנה אם משתמשים בספרייה סטטית או דינמית, צריך לציין את גרסת הטרום-השקה כשמבצעים קריאות ל-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
אפשר גם להשתמש ישירות ב-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 שאיתו נרשמתם לתוכנית התצוגה המקדימה למפתחים.
- שירותים מתקדמים לא תומכים בשיטות תצוגה מקדימה, ולכן תצטרכו לשלוח בקשות ישירות באמצעות HTTP.
- חובה לספק תווית וגרסת תצוגה מקדימה, כפי שמתואר בקטע הקודם בנושא HTTP.
כדי להכיר את Apps Script ולהגדיר פרויקט בסיסי, אפשר לעיין במדריך למתחילים המתאים. אחר כך פועלים לפי ההוראות האלה כדי להתחיל לשלוח קריאות ל-API בתצוגה מקדימה:
שינוי פרויקט Cloud שמשמש את הסקריפט
בהגדרות הפרויקט, לוחצים על שינוי הפרויקט ומזינים את מזהה פרויקט Cloud של הפרויקט שאליו נרשמתם לתוכנית התצוגה המקדימה למפתחים (כברירת מחדל, סקריפטים של Apps Script משתמשים בפרויקט כללי). אפשר להפעיל שיטות לתצוגה מקדימה רק בפרויקטים שרשומים לתוכנית.
הגדרת בקשות HTTP
לאחר מכן, מגדירים את בקשת ה-HTTP של ה-method שרוצים להפעיל ב-Editor. לדוגמה, במדריך למתחילים, רשימת הקורסים עם שירות 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, צריך להוסיף ידנית את היקפי ההרשאות המתאימים.
בהגדרות הפרויקט, מפעילים את האפשרות הצגת קובץ המניפסט 'appsscript.json' בעורך. חוזרים אל Editor ומוסיפים את oauthScopes
לקובץ appscript.json
לכל ההיקפים שצריך. ההיקפים של שיטה מסוימת מפורטים בדף ההפניה. לדוגמה, אפשר לעיין בדף השיטה 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"
]
}
הוספת תווית ותצוגה מקדימה של הגרסה
חוזרים אל הסקריפט ומוודאים שהוספתם את התווית המתאימה ואת גרסת התצוגה המקדימה כפי שמתואר בקטע 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);
}