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

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

יש שלושה שיקולים שצריך לקחת בחשבון כשמשתמשים בתכונות בגרסת טרום-השקה בהשוואה ל-API היציב בגרסה 1:

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

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

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

1. ספריות לקוח שנוצרות באופן דינמי
2. ספריות לקוח סטטיות שסופקו על ידי Google
3. ספריית לקוח מותאמת אישית משלכם

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

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

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

‫Discovery Document הוא מפרט שניתן לקריאה על ידי מכונה, שמתאר ממשקי 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 המתאים. בגרסאות טרום-השקה ציבוריות של 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 בבקשות. לדוגמה, כדי ליצור קריטריון הערכה באמצעות ה-API של תצוגה מקדימה של פעולות CRUD בקריטריוני הערכה, צריך להגדיר את 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.

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

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

שינוי פרויקט 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);
}