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

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

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

על המוצר

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

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

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

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

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

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

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

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

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

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

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

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

  1. בוחרים פרטי כניסה קיימים של OAuth 2.0 או פותחים את הדף Credentials.
  2. אם עדיין לא עשיתם זאת, אתם צריכים ליצור את פרטי הכניסה ל-OAuth 2.0 לפרויקט. לשם כך, לוחצים על Create credentials > מזהה לקוח OAuth, וממלאים את המידע שדרוש ליצירת פרטי הכניסה.
  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 או משתמשים באימות בסיסי, נוצר קוד הסטטוס 401 Unauthorized של HTTP.

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

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

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

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

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

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

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