מסמך

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

שיטות API

המשאב documents מספק methods שמשמשות להפעלת Docs API. ה-methods הבאות מאפשרות ליצור, לקרוא ולעדכן מסמכים ב-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, משתמשים בשיטה files.copy של Drive API. מידע נוסף זמין במאמר בנושא העתקת מסמך קיים.

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

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

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

סוג ה-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

בטבלה הבאה מתוארים ההבדלים בין השיטות 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השיטות מספקות גוף תגובה עם מידע על הבקשות שהוגשו, ואילו אחרות מספקות תגובה ריקה.

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