מסמך

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

שיטות API

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

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

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

מזהה המסמך

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

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

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

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

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

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

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

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

כדי לייצא תוכן של בייטים במסמך ב-Google Workspace, צריך להשתמש files.export עם documentId מהקובץ לייצוא ולייצוא MIME הנכון type. מידע נוסף זמין במאמר ייצוא מסמך ב-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 שיטות לספק גוף תשובה עם מידע על הבקשות שמוחלות, אחרים מציגים תגובה ריקה.

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