מסמך

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

שיטות API

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

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

ב-methods documents.get ו-documents.batchUpdate נדרש documentId כפרמטר כדי לציין את מסמך היעד. ה-method 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, והנתונים שמוחזרים בכל אחת מהן:

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

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

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

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

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

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

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