מסמך

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

שיטות API

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

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

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

מזהה המסמך

השדה 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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