במדריך הזה נסביר מושגים כמו השיטות הראשיות שמהן מורכב ה-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, משתמש שמקיים אינטראקציה עם המשאב documents
מקבל את תהליך המידע הבא:
- האפליקציה מפעילה את השיטה
documents.create
בשרת אינטרנט. - שרת האינטרנט שולח תגובת HTTP שמכילה מופע של המסמך שנוצר כמשאב
documents
. - לחלופין, האפליקציה מפעילה את השיטה
documents.batchUpdate
כדי לבצע באופן אטומי קבוצה של בקשות עריכה כדי לאכלס את המסמך בנתונים. - שרת האינטרנט שולח תגובת HTTP. שיטות מסוימות של
documents.batchUpdate
מספקות גוף התגובה עם מידע על הבקשות שהוחלו, ואילו שיטות אחרות מציגות תשובה ריקה.
תהליך עבודה של עדכון מסמכים
עדכון של מסמך קיים הוא מורכב יותר. לפני שתוכלו לבצע קריאות משמעותיות לעדכון מסמך, עליכם לדעת את המצב הנוכחי שלו: מאילו אלמנטים הוא מורכב, איזה תוכן כלול בהם ומה סדר הרכיבים במסמך. תרשים הרצף הבא מראה איך זה עובד:
באיור 2. במהלך האינטראקציה עם המשאב documents
, יש את זרימת המידע הבאה:
- האפליקציה מפעילה את השיטה
documents.get
בשרת אינטרנט, עם ה-documentId
של הקובץ שצריך למצוא. - שרת האינטרנט שולח תגובת HTTP שמכילה מופע של המסמך שצוין כמשאב
documents
. ה-JSON שמוחזר מכיל את התוכן, העיצוב ותכונות נוספות של המסמך. - האפליקציה מנתחת את קובץ ה-JSON כדי שהמשתמש יוכל לקבוע איזה תוכן או פורמט לעדכן.
- האפליקציה קוראת ל-method
documents.batchUpdate
כדי לבצע באופן אטומי קבוצה של בקשות עריכה לעדכון המסמך. - שרת האינטרנט שולח תגובת HTTP. שיטות מסוימות של
documents.batchUpdate
מספקות גוף התגובה עם מידע על הבקשות שהוחלו, ואילו שיטות אחרות מציגות תשובה ריקה.
בתרשים הזה לא נכללים תהליכי עבודה שבהם מתבצעים עדכונים בו-זמנית על ידי שותפי עריכה אחרים באותו מסמך. מידע נוסף זמין בקטע 'שיטות מומלצות', תכנון לשיתוף פעולה.
נושאים קשורים
- המבנה של מסמך ב-Google Docs
- בקשות ותשובות
- כללים והתנהגות עריכה מבנית
- שיטות מומלצות להשגת התוצאות הטובות ביותר