מבוא

Google Docs API מאפשר ליצור מסמכים ולשנות אותם.

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

  • אוטומציה של תהליכים
  • יצירת מסמכים בכמות גדולה
  • להפיק חשבוניות או חוזים

סקירה כללית של ה-API

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

שיטות API

תוכלו להשתמש בשיטות הבאות כדי ליצור, לקרוא ולעדכן מסמכים ב-Google Docs:

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

השיטות get ו-batchUpdate מחייבות שימוש בפרמטר documentId (ראו בהמשך) כדי לציין את מסמך היעד. השיטה create מחזירה מופע של המסמך שנוצר, שממנו אפשר לקרוא את המזהה.

עדכונים בכמות גדולה

השיטה batchUpdate לוקחת רשימה של אובייקטים של בקשה, ומבצעת עדכונים לפי אותו הסדר שבו הם מופיעים בבקשת האצווה. העדכונים בכמות גדולה מוחלים באופן אטומי. כלומר, אם בקשה כלשהי לא תקינה, העדכון כולו לא ייכשל ואף אחד מהשינויים (שעשויים להיות תלויים בו) לא מיושם.

השיטה batchUpdate מחזירה רשימה של אובייקטים בתגובה. לאובייקטים ברשימה הזו יש סדר אינדקס זהה לזה של הבקשה התואמת.

במאמר שיטות מומלצות לשליחת בקשות בכמות גדולה מוסבר איך לקבץ קריאות ל-API באצווה, ובמסמכי התיעוד בנושא batchUpdate תוכלו למצוא את סוג הבקשה והתגובה.

מזהה המסמך

מזהי מסמכים מפנים למסמך, והם יכולים להיות נגזרים מכתובת ה-URL:

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

השדה documentId הוא מחרוזת ייחודית שמכילה אותיות, מספרים וכמה תווים מיוחדים. ניתן להשתמש בביטוי הרגולרי הבא כדי לחלץ את מזהה המסמך מכתובת אתר של Google Docs:

/document/d/([a-zA-Z0-9-_]+)

אם אתם מכירים את Google Drive API, הערך documentId תואם למזהה של משאב File.

מיקומים בתוך מסמך: אינדקסים

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

תהליך העבודה של עדכון המסמכים

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

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

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

תהליך עבודה לעדכון מסמך.

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