המדריך ל-CalDAV API

CalDAV הוא הרחבה של WebDAV שמאפשרת ללקוחות לקבל גישה לנתוני שרת מסוים בשרת מרוחק.

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

מפרטים

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

  • rfc4918: תוספי HTTP עבור יצירה והפצת גרסאות מבוזרות באינטרנט (WebDAV)
    • תמיכה בשיטות HTTP GET, PUT, HEAD, DELETE, POST, OPTIONS, PROPFIND וגם PROPPATCH.
    • לא תומכת בשיטות HTTP LOCK, UNLOCK, COPY, MOVE או MKCOL, או בכותרת If* (מלבד If-Match).
    • לא תומך בנכסי WebDAV שרירותיים (בהגדרת המשתמש).
    • אין תמיכה ב-WebDAV Access Control (rfc3744).
  • rfc4791: תוספים ליומנים ב-WebDAV (CalDAV)
    • תומך בשיטת HTTP REPORT. כל הדוחות מלבד הדוח 'פנוי-עסוק' מיושמים.
    • לא תומך בשיטת HTTP MKCALENDAR.
    • לא תומך בפעולה 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 iCal פרוטוקול ה-CalDAV צריך לפעול באופן תקין.

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

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

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

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

נכנסים למסוף Google API. לוחצים על Create Project, מזינים שם ולוחצים על Create.

השלב הבא הוא להפעיל CalDAV API.

כדי להפעיל ממשק API לפרויקט, מבצעים את הפעולות הבאות:

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

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

  1. בוחרים פרטי כניסה קיימים של OAuth 2.0 או פותחים את דף פרטי הכניסה.
  2. אם עדיין לא עשית זאת, יש ליצור פרטי כניסה ל-OAuth 2.0 של הפרויקט. לשם כך, לוחצים על Create credentials > OAuth client ID [פרטי כניסה > מזהה לקוח OAuth], ומזינים את הפרטים הדרושים ליצירת פרטי הכניסה.
  3. מחפשים את מספר הלקוח בקטע Client-ID מסוג OAuth 2.0. לפרטים, לוחצים על מספר הלקוח.

מתבצע חיבור לשרת CalDAV של Google

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

אם תוכנת הלקוח (למשל Apple iCal) מחייבת אוסף ראשי בתור נקודת ההתחלה, ה-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.