המדריך למפתחים של CalDAV API

CalDAV הוא תוסף של WebDAV שמספק תקן ללקוחות לגשת למידע ביומן בשרת מרוחק.

Google מספקת ממשק CalDAV שבעזרתו אפשר להציג ולנהל יומנים באמצעות פרוטוקול CalDAV.

מפרטים

התמיכה של Google ב-CalDAV בכל אחת מהמפרטים הרלוונטיים היא:

  • rfc4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)
    • תמיכה בשיטות ה-HTTP: GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND ו-PROPPATCH.
    • לא תומך בשיטות ה-HTTP LOCK,‏ UNLOCK,‏ COPY,‏ MOVE או MKCOL, או בכותרת If* (למעט If-Match).
    • אין תמיכה במאפייני WebDAV שרירותיים (שהוגדרו על ידי משתמשים).
    • אין תמיכה בבקרת גישה ל-WebDAV‏ (rfc3744).
  • rfc4791: תוספים ליומן ל-WebDAV‏ (CalDAV)
    • תמיכה בשיטת ה-HTTP REPORT. כל הדוחות מוטמעים, מלבד שאילתה לגבי זמינות.
    • אין תמיכה בשיטת ה-HTTP‏ MKCALENDAR.
    • אין תמיכה בפעולה AUDIO.
  • rfc5545: iCalendar
    • הנתונים שמוצגים בממשק CalDAV מעוצבים בהתאם למפרט של iCalendar.
    • בשלב הזה אין תמיכה בנתוני VTODO או VJOURNAL.
    • לא תומך בתוסף Apple iCal® כדי לאפשר הגדרת מאפייני כתובת URL על ידי משתמשים.
  • rfc6578: Collection Synchronization for WebDAV
    • אפליקציות הלקוח צריכות לעבור למצב הפעולה הזה אחרי הסנכרון הראשוני.
  • rfc6638: תוספים לתזמון ב-CalDAV
    • תמיכה ב'תיבת דואר נכנס' פשוטה שתמיד ריקה.
    • ההזמנות שאתם מקבלים מועברות באופן אוטומטי לאוסף 'אירועים' ולא ל'תיבת דואר נכנס'.
    • אין תמיכה בחיפוש זמינות.
  • caldav-ctag-02: תג ישות של אוסף ביומן (CTag) ב-CalDAV
    • היומן ctag הוא כמו משאב etag. הוא משתנה בכל פעם שמשהו ביומן משתנה. כך אפליקציית הלקוח יכולה לקבוע במהירות שהיא לא צריכה לסנכרן אירועים שהשתנו.
  • calendar-proxy: פונקציונליות של שרת proxy של משתמש ביומן ב-CalDAV
    • כדי לשפר את הביצועים של סנכרון לוח השנה ממכשירי iOS שלא תומכים בהענקת גישה, השימוש בנכסים calendar-proxy-read-for או calendar-proxy-write-for עם מזהה משתמש (User-Agent) של iOS נכשל.

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

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

יצירת מזהה הלקוח

כדי להשתמש ב-CalDAV API, צריך חשבון Google. אם כבר יש לכם חשבון שבו אתם יכולים להשתמש, הכול מוכן.

כדי לשלוח בקשות ל-CalDAV API, צריך ליצור פרויקט ב-Google API Console ולרשום בו את הלקוח.

נכנסים למסוף Google API. לוחצים על Create project, מזינים שם ולוחצים על Create.

השלב הבא הוא הפעלת CalDAV API.

כדי להפעיל ממשק API בפרויקט:

  1. פותחים את API Library במסוף Google API. אם מופיעה בקשה, בוחרים פרויקט או יוצרים פרויקט חדש. בספריית ה-API מפורטים כל ממשקי ה-API הזמינים, שמקובצים לפי משפחת מוצרים ופופולריות.
  2. אם ה-API שרוצים להפעיל לא מופיע ברשימה, מחפשים אותו.
  3. בוחרים את ה-API שרוצים להפעיל ולוחצים על הלחצן Enable.
  4. אם תופיע בקשה, מפעילים את החיוב.
  5. אם מופיעה בקשה, מאשרים את התנאים וההגבלות של ה-API.
כדי לבצע בקשות ל-CalDAV API, צריך מזהה לקוח וסוד לקוח.

כדי למצוא את מזהה הלקוח ואת סוד הלקוח של הפרויקט:

  1. בוחרים פרטי כניסה קיימים של OAuth 2.0 או פותחים את דף פרטי הכניסה.
  2. אם עדיין לא עשיתם זאת, יוצרים את פרטי הכניסה של הפרויקט ל-OAuth 2.0 בלחיצה על Create credentials > OAuth client ID, ומספקים את הפרטים הנדרשים ליצירת פרטי הכניסה.
  3. מחפשים את מזהה הלקוח בקטע מזהי לקוחות ב-OAuth 2.0. לפרטים, לוחצים על מזהה הלקוח.

התחברות לשרת CalDAV של Google

כדי להשתמש בממשק CalDAV, תוכנת לקוח מתחברת בהתחלה לשרת לוח השנה באחת משתי נקודות ההתחלה. בכל מקרה, החיבור חייב להתבצע דרך HTTPS וצריך להשתמש בסכמת האימות OAuth 2.0. שרת CalDAV יסרב לאמת בקשה אלא אם היא תגיע דרך HTTPS עם אימות OAuth 2.0 של חשבון Google. ניסיון להתחבר באמצעות HTTP או באמצעות אימות בסיסי גורם לקוד סטטוס HTTP‏ 401 Unauthorized.

אם תוכנית הלקוח (למשל אפליקציית יומן Google של Apple) דורשת אוסף חשבונות משתמשים כנקודת ההתחלה, ה-URI שאליו צריך להתחבר הוא:

https://apidata.googleusercontent.com/caldav/v2/calid/user

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

אם תוכנית לקוח (כמו Mozilla Sunbird) דורשת אוסף של יומנים בתור נקודת ההתחלה, ה-URI שאליו צריך להתחבר הוא:

https://apidata.googleusercontent.com/caldav/v2/calid/events

נקודת הקצה הישנה https://www.google.com/calendar/dav הוצאה משימוש והיא לא נתמכת יותר. השימוש בה הוא באחריותכם בלבד. מומלץ לעבור לפורמט הנקודה הקצה החדש שמתואר למעלה.

iCal®‎ הוא סימן מסחרי של Apple Inc.‎