מסמך

במדריך הזה נסביר על מושגים כמו השיטות הראשיות שמרכיבות את Google Docs API, איך ניגשים למסמך ותהליך העבודה ביצירת מסמך.

שיטות API

המשאב documents מספק שיטות להפעלת Docs API. בעזרת השיטות הבאות תוכלו ליצור, לקרוא ולעדכן מסמכים ב-Docs:

  • משתמשים ב-method documents.create כדי ליצור מסמך.
  • משתמשים בשיטה documents.get כדי לאחזר את התוכן של מסמך ספציפי.
  • משתמשים בשיטה documents.batchUpdate כדי לבצע באופן אטומי קבוצה של עדכונים במסמך מסוים.

בשיטות documents.get ו-documents.batchUpdate נדרש פרמטר documentId כדי לציין את מסמך היעד. השיטה documents.create מחזירה מופע של המסמך שנוצר, שממנו אפשר לקרוא את documentId. למידע נוסף על בקשות API של Docs ועל שיטות תגובה, ראו בקשות ותגובות.

מזהה המסמך

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

https://docs.google.com/document/d/DOCUMENT_ID/edit

אפשר להשתמש בביטוי הרגולרי הבא כדי לחלץ את documentId מכתובת URL של Google Docs:

/document/d/([a-zA-Z0-9-_]+)

אם אתם מכירים את Google Drive API, הערך documentId תואם לערך id במשאב files.

נהל מסמכים ב-Google Drive

קובצי Docs מאוחסנים ב-Google Drive, שירות האחסון שלנו בענן. ל-Docs API יש שיטות עצמאיות משלו, אבל לרוב צריך להשתמש גם בשיטות של Google Drive API כדי לבצע פעולות בקבצים של משתמש ב-Docs. לדוגמה, כדי להעתיק קובצי Docs, משתמשים ב-method‏ files.copy של Drive API. מידע נוסף זמין במאמר העתקת מסמך קיים.

כברירת מחדל, כשמשתמשים ב-Docs API, מסמך חדש נשמר בתיקיית הבסיס של המשתמש ב-Drive. יש כמה אפשרויות לשמירת קובץ בתיקייה ב-Drive. מידע נוסף זמין במאמר עבודה עם תיקיות ב-Google Drive.

עבודה עם קובצי Docs

כדי לאחזר מסמך מהאזור 'הדפים שלי' של משתמש, בדרך כלל צריך להשתמש קודם בשיטה files.list של Drive כדי לאחזר את המזהה של הקובץ. קריאה ל-method ללא פרמטרים מחזירה רשימה של כל הקבצים והתיקיות של המשתמש, כולל המזהים.

סוג ה-MIME של המסמך מציין את הסוג והפורמט של הנתונים. הפורמט של סוג ה-MIME ב-Docs הוא application/vnd.google-apps.document. רשימה של סוגי MIME זמינה במאמר סוגי MIME נתמכים ב-Google Workspace וב-Google Drive.

כדי לחפש לפי סוג MIME רק קובצי Docs ב'אחסון שלי', מוסיפים את המסנן הבא למחרוזות השאילתה:

q: mimeType = 'application/vnd.google-apps.document'

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

אחרי שהבנתם מה documentId, תוכלו להשתמש בשיטה documents.get כדי לאחזר מופע מלא של המסמך שצוין. למידע נוסף, ראו בקשות ותשובות.

כדי לייצא תוכן בבייטים של מסמך ב-Google Workspace, צריך להשתמש בשיטה files.export של Drive עם documentId של הקובץ כדי לייצא אותו ובסוג ה-MIME המתאים לייצוא. מידע נוסף זמין במאמר ייצוא תוכן של מסמכים ב-Google Workspace.

השוואה בין השיטות Get ו-List

בטבלה הבאה מתוארים ההבדלים בין ה-methods ב-Drive וב-Docs, והנתונים שמוחזרים בכל אחת מהן:

מפעיל תיאור שימוש
drive.files.get אחזור המטא-נתונים של קובץ לפי מזהה. הפונקציה מחזירה מופע של המשאב files. קבלת המטא-נתונים של קובץ ספציפי.
drive.files.list אחזור הקבצים של משתמש. מחזירה רשימה של קבצים. קבלת רשימה של קובצי משתמש כשלא בטוחים איזה קובץ צריך לשנות.
docs.documents.get הפונקציה מקבלת את הגרסה העדכנית ביותר של המסמך שצוין, כולל כל הפורמטים והטקסט. הפונקציה מחזירה מופע של המשאב documents. מאתרים את המסמך של מזהה מסמך ספציפי.

תהליך העבודה ליצירת מסמך

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

תהליך העבודה ליצירה של מסמך חדש ויישוב שלו.
איור 1. תהליך עבודה ליצירה ולאכלוס של מסמך חדש.

באיור 1, למשתמש שמבצע פעולה עם המשאב documents יש את תהליך העברת המידע הבא:

  1. אפליקציה מפעילה את השיטה documents.create בשרת אינטרנט.
  2. שרת האינטרנט שולח תגובת HTTP שמכילה מופע של המסמך שנוצר כמשאב documents.
  3. לחלופין, האפליקציה קוראת ל-method documents.batchUpdate כדי לבצע קבוצה של בקשות עריכה באופן אטומי כדי לאכלס את המסמך בנתונים.
  4. שרת האינטרנט שולח תגובת HTTP. חלק מהשיטות documents.batchUpdate מספקות גוף תשובה עם מידע על הבקשות שהוחלו, ואילו שיטות אחרות מציגות תגובה ריקה.

תהליך העבודה של עדכון מסמכים

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

תהליך עבודה לעדכון מסמך.
איור 2. תהליך עבודה לעדכון מסמך.

באיור 2, למשתמש שמקיים אינטראקציה עם המשאב documents יש את תהליך העברת המידע הבא:

  1. אפליקציה מפעילה את ה-method documents.get בשרת אינטרנט, כאשר ה-documentId של הקובץ נמצא.
  2. שרת האינטרנט שולח תגובת HTTP שמכילה מופע של המסמך שצוין כמשאב documents. קובץ ה-JSON המוחזר מכיל את תוכן המסמך, הפורמט שלו ותכונות אחרות.
  3. האפליקציה מפענחת את ה-JSON כדי שהמשתמש יוכל לקבוע איזה תוכן או פורמט לעדכן.
  4. האפליקציה קוראת לשיטה documents.batchUpdate כדי לבצע באופן אטומי קבוצה של בקשות עריכה לעדכון המסמך.
  5. שרת האינטרנט שולח תגובת HTTP. חלק מהשיטות של documents.batchUpdate מספקות גוף תגובה עם מידע על הבקשות שהוחלו, ואילו שיטות אחרות מספקות תשובה ריקה.

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