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

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

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

1. תכונות API בתוכניות גישה מוקדמת או בתוכניות טרום-השקה לא נחשפות ספריות לקוח רגילות, וייתכן שלא יהיו נגישות כברירת מחדל ב-HTTP.
2. בכל רגע נתון יכולים להיות מספר מצבי 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.