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