במדריך הזה מופיעה סקירה כללית על השימוש ב-Notebooks API ועל מסמכי העיון שלו.
REST, gRPC וספריות לקוח
אפשר לגשת ל-API באמצעות REST, gRPC או אחת מספריות הלקוח שסופקו (שמבוססות על gRPC).
ספריות לקוח
Google מספקת ספריות לקוח לשפות פופולריות רבות כדי לגשת ל-API הזה. אם שפת התכנות שבה אתם רוצים להשתמש נתמכת על ידי ספריות הלקוח, כדאי להשתמש באפשרות הזו.
| יתרונות | חסרונות |
|---|---|
|
בניהול של Google.
אימות מובנה. ניסיונות חוזרים מובנים. ניב שמתאים לכל שפה. יעיל גוף בקשת HTTP של מאגר אחסון לפרוטוקולים. |
האפשרות הזו לא זמינה לכל שפות התכנות. |
REST
ה-API הזה תומך ב-REST. מידע נוסף על ה-API הזה זמין במאמר בנושא הפניית REST. כדאי גם לעיין במאמר איך קוראים לממשקי Google API: מהדורת REST.
| יתרונות | חסרונות |
|---|---|
|
ממשק JSON פשוט.
יש תמיכה טובה ב-Google Cloud CLI בהרבה כלים וספריות של Google ושל צד שלישי. |
אתם צריכים ליצור לקוח משלכם.
עליך להטמיע אימות. חובה להטמיע ניסיונות חוזרים. תוכן בקשת HTTP בפורמט JSON פחות יעיל. API הזה לא תומך בסטרימינג של REST. |
gRPC
ה-API הזה תומך ב-gRPC. במאמר העזר בנושא RPC ל-API הזה מופיע תיאור כללי של הסוגים, השיטות והשדות שנוצרים עבור ספריית gRPC. אפשר גם לעיין במאמר בנושא איך שולחים קריאות לממשקי Google API: מהדורת RPC.
| יתרונות | חסרונות |
|---|---|
|
תומך בשפות תכנות רבות.
יעיל גוף בקשת HTTP של מאגר אחסון לפרוטוקולים. |
אתם צריכים ליצור לקוח משלכם ממאגרי פרוטוקולים שסופקו על ידי Google.
עליך להטמיע אימות. חובה להטמיע ניסיונות חוזרים. |
סוג, שיטה ושמות שדות
בהתאם לשימוש בספריות לקוח, ב-REST או ב-gRPC, סוג ה-API, השיטה ושמות השדות משתנים במידה מסוימת:
- ממשק REST מסודר לפי היררכיות של משאבים והשיטות שלהם.
- ספריות לקוח ו-gRPC מסודרות לפי שירותים והשיטות שלהם.
- שמות השדות ב-REST הם בפורמט CamelCase, אבל שירות ה-API יקבל גם פורמט CamelCase וגם פורמט SnakeCase.
- שמות השדות ב-gRPC הם בפורמט snake case.
- שמות השדות בספריית הלקוח הם באותיות רישיות בתחילת כל מילה (title case), בשיטת CamelCase או בשיטת snake_case, בהתאם לשם שמתאים לשפה.
מאגרי אחסון לפרוטוקולים
בין אם אתם משתמשים בספריות לקוח, ב-REST או ב-gRPC, השירות הבסיסי מוגדר באמצעות מאגרי פרוטוקולים. באופן ספציפי, השירות משתמש ב-proto3.
כששולחים קריאה ל-API, יכול להיות שיהיה צורך בהבנה בסיסית של סוגים מוכרים של מאגר אחסון לפרוטוקולים בשדות מסוימים של בקשות או תגובות.
בנוסף, כשקוראים ל-API בארכיטקטורת REST, יכול להיות ששדות יחסרו בתגובת JSON בגלל התנהגות ערך ברירת המחדל של מאגרי פרוטוקולים. השדות האלה פשוט מוגדרים לערך ברירת המחדל, ולכן הם לא נכללים בתגובה.
גרסאות API
אלו גרסאות ה-API שזמינות:
- v2 (זמין לכולם) מיועד לניהול מופעים של Gemini Enterprise Agent Platform Workbench.