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

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

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

מפרטים

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

  • rfc4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)
    • תומך ב-methods של 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
    • תומך בתיבת דואר נכנס פשוטה, שתמיד ריקה.
    • ההזמנות שאתם מקבלים מועברות אוטומטית לאוסף 'אירועים' ולא לתיבת הדואר הנכנס.
    • אין תמיכה בחיפוש מידע על זמינות.
  • caldav-ctag-02: Calendar Collection Entity Tag (CTag) in CalDAV
    • היומן ctag הוא כמו משאב etag, והוא משתנה כשמשהו ביומן משתנה. כך אפליקציית הלקוח יכולה לקבוע במהירות שהיא לא צריכה לסנכרן אירועים שהשתנו.
  • calendar-proxy: Calendar User Proxy Functionality in CalDAV
    • כדי לשפר את הביצועים של סנכרון היומן ממכשירי iOS שלא תומכים בהקצאת הרשאות, שימוש במאפיינים calendar-proxy-read-for או calendar-proxy-write-for עם UserAgent של iOS ייכשל.

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

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

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

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

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

עוברים אל 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 או פותחים את הדף Credentials (פרטי כניסה).
  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.

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

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

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

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

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

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

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