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

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

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

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

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

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

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

מומלץ להשתמש ב-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, צריך להגדיר את 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()

הערה: גרסאות הטרום-השקה הן זמניות, עד שהתכונות יאושרו לזמינות לכלל המשתמשים ב-API בגרסה 1. ההתנהגות של גרסת ה-Preview עשויה להשתנות אחרי חלון ההוצאה משימוש. מידע נוסף זמין בתוכנית העבודה של Classroom API.

משאבים שמשויכים לקריאה של שיטת תצוגה מקדימה מכילים גם את הערך של 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",
  ...
}

הערה: גרסת התצוגה המקדימה שמשויכת למשאב תואמת לגרסה שבה נעשה שימוש כדי לאחזר את המשאב, ולא בהכרח לקריאה ליצירת המשאב. אם תבצעו בעתיד קריאה ל-GET, ל-LIST או ל-PATCH עם ציון גרסה חדשה, הגרסה החדשה תוחזר.

בקשות 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 שרשמתם לתוכנית Developer Preview.
2. Advanced Services לא תומכים בשיטות תצוגה מקדימה, לכן תצטרכו לשלוח בקשות ישירות באמצעות HTTP.
3. חובה לספק תווית וגרסה של תצוגה מקדימה, כפי שמתואר בקטע הקודם בנושא 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 ברמות ההיקף הנדרשות. ההיקפים של שיטה מסוימת מפורטים בדף העזרה. לדוגמה, ראו דף השיטה list של courses.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);
}