מסמך

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

שיטות 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 כדי לאחזר את המזהה של קובץ. קריאה לשיטה ללא פרמטרים תחזיר רשימה של כל הקבצים והתיקיות של המשתמש, כולל המזהים.

סוג 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, והנתונים שמוחזרים בכל אחת מהן:

מפעיל תיאור Usage
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. האפליקציה קוראת ל-method documents.batchUpdate כדי לבצע באופן אטומי קבוצה של בקשות עריכה לעדכון המסמך.
  5. שרת האינטרנט שולח תגובת HTTP. שיטות מסוימות של documents.batchUpdate מספקות גוף התגובה עם מידע על הבקשות שהוחלו, ואילו שיטות אחרות מציגות תשובה ריקה.

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