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

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

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

מפרטים

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

  • rfc4918: תוספי HTTP לכתיבה ולגרסה שמופצת באינטרנט (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: סנכרון אוסף של WebDAV
    • אפליקציות לקוח צריכות לעבור למצב הפעולה הזה אחרי הסנכרון הראשוני.
  • rfc6638: תזמון תוספים ל-CalDAV
    • יש תמיכה ב'תיבת דואר נכנס' טריוויאלית, תמיד ריקה.
    • ההזמנות שמקבלים באופן אוטומטי מועברות לאוסף 'אירועים', ולא לתיבת הדואר הנכנס.
    • לא תומך בחיפוש זמן פנוי.
  • caldav-ctag-02: תג ישות של אוסף היומן (CTag) ב-CalDAV
    • היומן ctag הוא כמו משאב etag, הוא משתנה כאשר משהו ביומן משתנה. כך אפליקציית הלקוח יכולה לקבוע במהירות שאין צורך לסנכרן אירועים שהשתנו.
  • calendar-proxy: פונקציונליות של שרת proxy של משתמש ביומן Google ב-CalDAV
    • כדי לשפר את ביצועי סנכרון היומן ממכשירי iOS, שלא תומכים בהענקת גישה, השימוש בנכסים של calendar-proxy-read-for או calendar-proxy-write-for עם סוכן משתמש של iOS ייכשל.

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

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

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

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

לפני שתוכלו לשלוח בקשות ל-CalDAV API, עליכם ליצור פרויקט כדי לרשום את הלקוח במסוף Google API.

עוברים אל Google API Console. לוחצים על Create project, מזינים שם ולוחצים על Create.

בשלב הבא מפעילים CalDAV API.

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

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

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

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

מתבצע חיבור לשרת CalDAV של Google

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

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

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

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

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

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

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

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