המדריך למפתחים של 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 על ידי יצירת פרויקט.

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

בשלב הבא מפעילים את 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, תוכנת לקוח מתחברת בהתחלה עם שרת Google, באחת משתי נקודות התחלה. בכל מקרה, החיבור חייב להיות ב-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 באופן הבא: בתפריט הנפתח שליד שם היומן, בוחרים הגדרות יומן Google. בדף שמתקבל מזהה היומן מופיע בקטע יומן Google כתובת. מזהה היומן של היומן הראשי של המשתמש זהה למזהה בכתובת האימייל של המשתמש הזה.

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

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

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

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