שיטות לתצוגה מקדימה בגישה מוקדמת לתוספים

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

מסמך זה דן בארבע אפשרויות לשימוש ב-API של התצוגה המקדימה:

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

הדרך המומלצת להשתמש ב-API היא שימוש בספריות סטטיות או בספריות שנוצרות באופן דינמי מ-Google.

ספריות סטטיות

ספריות לקוח בשפות כמו Java, Node.js, PHP ו-C# צריכות להיבנות על בסיס מקור. הספריות האלה זמינות עבורכם בהורדות של ספריות הלקוח, והן כבר כוללות את השיטות לתצוגה מקדימה.

יכול להיות שתצטרכו לשנות את ההגדרה הטיפוסית של יחסי התלות כדי להשתמש בספריות המקומיות האלה במקום לייבא את ספריות הלקוח הסטנדרטיות, שאין להן את השיטות של התצוגה המקדימה.

לדוגמה, אם משתמשים ב-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-addons": "file:./googleapis-classroom-1.0.4.tgz"
  }
}

לאחר מכן, מוסיפים לאפליקציה את המודול classroom-with-addons בנוסף ליחסי תלות רגילים, ומפעילים את השירות classroom מהמודול הזה:

const {authenticate} = require('@google-cloud/local-auth');
const {google} = require('googleapis');
const classroomWithAddons = require('classroom-with-addons');

...

const classroom = classroomWithAddons.classroom({
  version: 'v1',
  auth: auth,
});

...

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

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

מסמך 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>

כדי ליצור את ספריית Python וליצור מופע של שירות Classroom עם שיטות של תוספים, אפשר לציין את כתובת ה-URL של Discovery עם השירות המתאים, פרטי הכניסה והתווית:

classroom_service_with_rubrics = googleapiclient.discovery.build(
  serviceName="classroom",
  version="v1",
  credentials=credentials,
  static_discovery=False,
  discoveryServiceUrl=f"https://classroom.googleapis.com/$discovery/rest?labels=ADD_ONS_ALPHA&key=ABCXYZ")

פרטים על כל שפה מופיעים במסמכי התיעוד של ספריית הלקוח של Google API בנפרד. ההבדל החשוב בעבודה עם ממשקי API בתצוגה מקדימה הוא השדה label המתאים. בתצוגה המקדימה הזו התווית היא ADD_ONS_ALPHA.

בקשות HTTP

אם אתם שולחים בקשות HTTP בלי ספריית לקוח, הקפידו לכלול את התווית (ADD_ONS_ALPHA) ככותרת X-Goog-Visibilities.

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

curl \
  'https://classroom.googleapis.com/v1/courses/[courseId]/posts/[postId]/addOnAttachments?key=[YOUR_API_KEY]' \
  --header 'X-Goog-Visibilities: ADD_ONS_ALPHA' \
  --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
  --header 'Accept: application/json' \
  --compressed

ה-API של כל בקשת HTTP מתואר במסמכי התיעוד בנושא REST.

ספריות לקוח בהתאמה אישית

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