יצירה וניהול של מחברות (API)

תצוגה מקדימה

השימוש בתכונה הזו כפוף לתנאי השימוש במוצרים בגרסת טרום-GA, שמפורטים בחלק "תנאי שירות הכלליים" בתנאים הספציפיים של השירות. השימוש בתכונות בגרסת טרום-GA הוא "כפי שהן" (As is), ויכול להיות שהתמיכה בהן תהיה מוגבלת. מידע נוסף זמין בקטע תיאור שלבי ההשקה.

‫Gemini Notebook Enterprise הוא כלי רב עוצמה ליצירת תובנות וסיכומים מהמסמכים שלכם. בדף הזה מתוארים ממשקי ה-API שמאפשרים לבצע באופן פרוגרמטי את משימות הניהול הבאות של מחברות:

• יצירת נוטבוק
• שחזור של נוטבוק
• הצגת רשימה של מחברות שנצפו לאחרונה
• מחיקת מחברת
• שיתוף נוטבוק

לפני שמתחילים

לפני שמתחילים לעבוד עם מחברות, חשוב לבצע את הפעולות הבאות:

• הגדרת Gemini Notebook Enterprise
• קבלת רישיונות ל-Gemini Notebook Enterprise

יצירת Notebook

כדי ליצור נוטבוק חדש, משתמשים בשיטה notebooks.create.

REST

curl -X POST \
  -H "Authorization:Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/notebooks" \
  -d '{
  "title": "NOTEBOOK_TITLE",
  }'

מחליפים את מה שכתוב בשדות הבאים:

• ‫ENDPOINT_LOCATION: האזור הרב-אזורי של בקשת ה-API. מציינים אחד מהערכים הבאים:
  • ‫us לאזור מרובה בארה"ב
  • ‫eu לאזור עם מספר אזורים באיחוד האירופי
  • global למיקום הגלובלי
  מידע נוסף זמין במאמר בנושא הגדרת מאגר נתונים במספר אזורים.
• ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
• LOCATION: המיקום הגיאוגרפי של מאגר הנתונים, כמו global. מידע נוסף מופיע במאמר מיקומים.
• ‫NOTEBOOK_TITLE: מחרוזת בקידוד UTF-8 שמשמשת ככותרת למחברת שרוצים ליצור.

אם הבקשה מצליחה, אמור להתקבל קובץ JSON שדומה לזה.

{
"title": "NOTEBOOK_TITLE",
"notebookId": "NOTEBOOK_ID",
"emoji": "",
"metadata": {
  "userRole": "PROJECT_ROLE_OWNER",
  "isShared": false,
  "isShareable": true
},
"name": "NOTEBOOK_NAME"
}

שימו לב לנקודות הבאות:

• ‫NOTEBOOK_ID: מזהה ייחודי לזיהוי המחברת שנוצרה. תצטרכו את מזהה המחברת למשימות אחרות של ניהול מחברות, כמו שיתוף או אחזור.
• ‫NOTEBOOK_NAME: שם המשאב המלא של מחברת ה-Notebook. השדה הזה הוא בפורמט הבא: projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID

גישה לתיקיית ה-Notebook שנוצרה וקבלת המזהה שלה בדפדפן

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

1. עוברים לדף הבית של Gemini Notebook Enterprise באחת מהכתובות הבאות:

   1. אם אתם משתמשים בזהות Google, אתם יכולים לעבור אל:

      https://notebook.cloud.google.com/LOCATION/?project=PROJECT_NUMBER
      

   2. אם אתם משתמשים בזהות של צד שלישי, עוברים אל:

      https://notebook.cloud.google/LOCATION/?project=PROJECT_NUMBER
      

2. בוחרים את ה-Notebook שנוצר. כתובת ה-URL של תיקיית ה-Notebook שנבחרה היא מהתבנית הבאה:

   1. אם אתם משתמשים בזהות Google:

      https://notebook.cloud.google.com/LOCATION/notebook/NOTEBOOK_ID?project=PROJECT_NUMBER
      

   2. אם אתם משתמשים בזהות של צד שלישי:

      https://notebook.cloud.google/LOCATION/notebook/NOTEBOOK_ID?project=PROJECT_NUMBER
      

3. כדאי לשים לב לכתובת ה-URL ולמזהה המחברת, כי הם שימושיים למשימות אחרות של ניהול מחברות, כמו שיתוף.

אחזור של Notebook

כדי לאחזר מחברת ספציפית באמצעות המזהה שלה, משתמשים בשיטה notebooks.get.

REST

curl -X GET \
  -H "Authorization:Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID"

מחליפים את מה שכתוב בשדות הבאים:

• ‫ENDPOINT_LOCATION: האזור הרב-אזורי של בקשת ה-API. מציינים אחד מהערכים הבאים:
  • ‫us לאזור מרובה בארה"ב
  • ‫eu לאזור עם מספר אזורים באיחוד האירופי
  • global למיקום הגלובלי
  מידע נוסף זמין במאמר בנושא הגדרת מאגר נתונים במספר אזורים.
• ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
• LOCATION: המיקום הגיאוגרפי של מאגר הנתונים, כמו global. מידע נוסף מופיע במאמר מיקומים.
• ‫NOTEBOOK_ID: המזהה הייחודי של ה-Notebook שקיבלתם כשנוצר ה-Notebook.

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

{
"title": "NOTEBOOK_TITLE",
"notebookId": "NOTEBOOK_ID",
"emoji": "",
"metadata": {
  "userRole": "PROJECT_ROLE_OWNER",
  "isShared": false,
  "isShareable": true,
  "lastViewed": "LAST_VIEWED_TIME",
  "createTime": "LAST_CREATED_TIME"
},
"name": "NOTEBOOK_NAME"
}

הצגת רשימה של פריטי notebook שנצפו לאחרונה

כדי לקבל רשימה של כל הנוטבוקים בפרויקט שנצפו לאחרונה, משתמשים בשיטה notebooks.listRecentlyViewed. כברירת מחדל, בתגובה מופיעים 500 המחברות האחרונות. אפשר לבחור להוסיף מספור לדפים של התשובות באמצעות פרמטר השאילתה pageSize.

REST

curl -X GET \
  -H "Authorization:Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/notebooks:listRecentlyViewed"

מחליפים את מה שכתוב בשדות הבאים:

• ‫ENDPOINT_LOCATION: האזור הרב-אזורי של בקשת ה-API. מציינים אחד מהערכים הבאים:
  • ‫us לאזור מרובה בארה"ב
  • ‫eu לאזור עם מספר אזורים באיחוד האירופי
  • global למיקום הגלובלי
  מידע נוסף זמין במאמר בנושא הגדרת מאגר נתונים במספר אזורים.
• ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
• LOCATION: המיקום הגיאוגרפי של מאגר הנתונים, כמו global. מידע נוסף מופיע במאמר מיקומים.

אם הבקשה מצליחה, אמורה להתקבל תגובת JSON שדומה לזו. התשובה מכילה עד 500 מחברות שהמשתמש ניגש אליהן לאחרונה.

{
  "notebooks": [
    {
      "title": "NOTEBOOK_TITLE_1",
      "notebookId": "NOTEBOOK_ID_1",
      "emoji": "",
      "metadata": {
        "userRole": "PROJECT_ROLE_OWNER",
        "isShared": false,
        "isShareable": true,
        "lastViewed": "LAST_VIEWED_TIME",
        "createTime": "LAST_CREATED_TIME"
      },
      "name": "NOTEBOOK_NAME_1"
    },
    {
      "title": "NOTEBOOK_TITLE_2",
      "notebookId": "NOTEBOOK_ID_2",
      "emoji": "",
      "metadata": {
        "userRole": "PROJECT_ROLE_OWNER",
        "isShared": false,
        "isShareable": true,
        "lastViewed": "LAST_VIEWED_TIME",
        "createTime": "LAST_CREATED_TIME"
      },
      "name": "NOTEBOOK_NAME_2"
    }
  ]
}

מחיקת Notebook

כדי למחוק מחברת, משתמשים בשיטה notebooks.batchDelete.

REST

curl -X POST \
  -H "Authorization:Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/notebooks:batchDelete" \
  -d '{
    "names": [
      "NOTEBOOK_NAME"
    ]
  }'

מחליפים את מה שכתוב בשדות הבאים:

• ‫ENDPOINT_LOCATION: האזור הרב-אזורי של בקשת ה-API. מציינים אחד מהערכים הבאים:
  • ‫us לאזור מרובה בארה"ב
  • ‫eu לאזור עם מספר אזורים באיחוד האירופי
  • global למיקום הגלובלי
  מידע נוסף זמין במאמר בנושא הגדרת מאגר נתונים במספר אזורים.
• ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
• LOCATION: המיקום הגיאוגרפי של מאגר הנתונים, כמו global. מידע נוסף מופיע במאמר מיקומים.

• ‫NOTEBOOK_NAME: שם המשאב המלא של מחברת ה-Notebook שרוצים למחוק. התבנית של השדה הזה היא: projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID.

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

שיתוף מחברת

כדי לשתף נוטבוק חדש, משתמשים בשיטה notebooks.share.

למשתמש שאיתו רוצים לשתף את ה-Notebook צריך להיות מוקצה התפקיד משתמש ב-Cloud Gemini Notebook.

REST

1. בפרויקט ב- Google Cloud , מקצים את התפקיד Cloud Gemini Notebook Userבממשק לניהול זהויות והרשאות גישה (IAM) למשתמשים שרוצים לשתף איתם את המחברת.

2. מבצעים קריאה ל-method הבא.

   curl -X POST \
     -H "Authorization:Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/notebooks/NOTEBOOK_ID:share" \
     -d '{
       "accountAndRoles": [
        {
           "email":"USER_EMAIL_1",
           "role":"USER_ROLE_1",
        },
        {
           "email":"USER_EMAIL_2",
           "role":"USER_ROLE_2",
        },
       ]
     }'
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫ENDPOINT_LOCATION: האזור הרב-אזורי של בקשת ה-API. מציינים אחד מהערכים הבאים:
     • ‫us לאזור מרובה בארה"ב
     • ‫eu לאזור עם מספר אזורים באיחוד האירופי
     • global למיקום הגלובלי
     מידע נוסף זמין במאמר בנושא הגדרת מאגר נתונים במספר אזורים.
   • ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
   • LOCATION: המיקום הגיאוגרפי של מאגר הנתונים, כמו global. מידע נוסף מופיע במאמר מיקומים.
   • NOTEBOOK_ID: מזהה ייחודי לזיהוי המחברת שרוצים לשתף. תצטרכו את מזהה המחברת למשימות אחרות של ניהול מחברות, כמו שיתוף או אחזור.
   • ‫USER_EMAIL: כתובת האימייל של המשתמש שאיתו רוצים לשתף את המחברת.

   • ‫USER_ROLE: תפקיד שרוצים להקצות למשתמש. הערך יכול להיות אחד מהבאים:

     • ‫PROJECT_ROLE_OWNER: המשתמש הוא הבעלים של הפרויקט.
     • ‫PROJECT_ROLE_WRITER: למשתמש יש הרשאות כתיבה בפרויקט.
     • ‫PROJECT_ROLE_READER: למשתמש יש הרשאות קריאה בפרויקט.
     • ‫PROJECT_ROLE_NOT_SHARED:למשתמש אין גישה לפרויקט.

   אם הבקשה מצליחה, מקבלים אובייקט JSON ריק.

אימות משתמשים באמצעות דפדפן

כדי לוודא ששיתפתם את המחברת עם המשתמשים הנכונים והקציתם להם את התפקידים הנכונים, אתם צריכים:

1. פותחים את הנוטבוק בדפדפן. תבנית כתובת ה-URL של מחברת היא:

   1. אם אתם משתמשים בזהות Google:

      https://notebook.cloud.google.com/LOCATION/notebook/NOTEBOOK_ID?project=PROJECT_NUMBER
      

   2. אם אתם משתמשים בזהות של צד שלישי:

      https://notebook.cloud.google/LOCATION/notebook/NOTEBOOK_ID?project=PROJECT_NUMBER
      

2. לוחצים על שיתוף.

3. בודקים את המשתמשים שמופיעים בקטע אנשים עם גישה ואת התפקידים שהוקצו להם.

המאמרים הבאים

• הוספה של מקורות נתונים מסוגים שונים ל-Notebooks באמצעות תכנות.