המדריך למפתחים של 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: פונקציונליות של פרוקסי של משתמש ביומן ב-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 או פותחים את דף פרטי הכניסה.
  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/valid/user

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

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

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

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

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