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