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

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

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

ל-CalDAV API יש את אותן מגבלות מכסה כמו ל-Calendar API. מידע נוסף זמין במאמר בנושא מגבלות שימוש.

מפרטים

התמיכה של 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: Calendaring Extensions to WebDAV (CalDAV)

    • יש תמיכה בשיטת ה-HTTP‏ REPORT. כל הדוחות מלבד free-busy-query מוטמעים.
    • אין תמיכה בשיטת ה-HTTP‏ MKCALENDAR.
    • אין תמיכה בפעולה AUDIO.

  • rfc5545: iCalendar

    • הנתונים שנחשפים בממשק CalDAV מעוצבים לפי מפרט iCalendar.
    • אין תמיכה בנתוני VTODO או VJOURNAL.
    • לא תומך בתוסף Apple iCal כדי לאפשר הגדרת מאפייני כתובת URL על ידי המשתמש.

  • rfc6578: Collection Synchronization for WebDAV

    • אחרי הסנכרון הראשוני, אפליקציות לקוח צריכות לעבור למצב הפעולה הזה.

  • rfc6638: Scheduling Extensions to CalDAV

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

  • caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV

    • היומן ctag הוא כמו משאב etag, והוא משתנה כשמשהו ביומן משתנה. כך אפליקציית הלקוח יכולה לקבוע במהירות שהיא לא צריכה לסנכרן אירועים ששונו.

  • calendar-proxy: Calendar User Proxy Functionality in CalDAV

    • כדי לשפר את הביצועים של סנכרון היומן, בקשות שכוללות את המאפיינים calendar-proxy-read-for או calendar-proxy-write-for ייכשלו עם UserAgent של iOS, כי מכשירי iOS לא תומכים בהקצאת הרשאות.

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

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

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

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

עוברים אל Google API Console. לוחצים על Create project (יצירת פרויקט), מזינים שם ולוחצים על Create (יצירה).

בשלב הבא צריך להפעיל את CalDAV API.

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

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

כדי לבצע בקשות CalDAV API, צריך מזהה לקוח וסוד לקוח.

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

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

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

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

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

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

מחליפים את CALENDAR_ID במזהה של היומן שרוצים לגשת אליו.

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

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

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