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

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

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

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

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

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

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

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

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

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

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

גילוי מסמכים לשירות 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

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

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

ציון הגרסה מתבצע על ידי הגדרת השדה PreviewVersion בבקשות. לדוגמה, כדי ליצור קריטריון הערכה עם ממשק ה-API של CRUD של Rubrics, צריך להגדיר 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 משמש בשיחה כשדה לקריאה בלבד, כדי לעזור לך להבין באיזו גרסה אתם משתמשים. לדוגמה, התשובה מהיצירה הקודמת הקריאה מכילה את הערך 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 בגוף ההודעה (ראה את ממשק ה-API הספציפי המתאים ). בתצוגה מקדימה שגלויה לכולם, התווית היא DEVELOPER_PREVIEW.

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

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 והגדרה של פרויקט בסיסי. לאחר מכן צריך לפעול לפי כדי להתחיל להפעיל את ממשקי ה-API של התצוגה המקדימה:

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

בקטע Project Settings (הגדרות הפרויקט), לוחצים על Change project (שינוי הפרויקט) ומזינים את מזהה הפרויקט ב-Cloud של הפרויקט שרשמתם למפתחים Preview Program (כברירת מחדל, הסקריפטים של 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, להוסיף באופן ידני את ההיקפים המתאימים.

בהגדרות הפרויקט, מפעילים את האפשרות הצגת 'appsscript.json'. קובץ מניפסט ב- Editor. בחזרה ב-Editor, מוסיפים את oauthScopes לקובץ appscript.json של כל היקפים שאתם צריכים. היקפים של שיטה נתונה מפורטים בקטע דף העזר. לדוגמה, ניתן לראות את שיטת הרשימה 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 ל- השירות של הקריטריונים להערכה ייראה כך:

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