Events: import

لاستيراد حدث. تُستخدم هذه العملية لإضافة نسخة خاصة من حدث حالي إلى تقويم. لا يمكن استيراد سوى الأحداث التي تحتوي على eventType من default.

السلوك المتوقّف نهائيًا: إذا تم استيراد حدث ليس "default"، سيتم تغيير نوعه إلى "default" وسيتم استبعاد أي خصائص من نوع الحدث قد تكون مدرَجة.

جرِّبه الآن أو اطّلِع على مثال.

الطلب

طلب HTTP

POST https://www.googleapis.com/calendar/v3/calendars/calendarId/events/import

المَعلمات

اسم المعلَمة القيمة الوصف
مَعلمات المسار
calendarId string معرّف التقويم. لاسترداد معرّفات التقويم، يمكنك استدعاء الطريقة calendarList.list. إذا كنت تريد الوصول إلى التقويم الأساسي للمستخدم الذي سجّل دخوله حاليًا، استخدِم الكلمة الرئيسية "primary".
مَعلمات طلب البحث الاختيارية
conferenceDataVersion integer رقم إصدار بيانات مكالمات الفيديو التي يدعمها برنامج واجهة برمجة التطبيقات. لا يفترض الإصدار 0 أي دعم لبيانات المؤتمر ويتجاهل بيانات المؤتمر في نص الحدث. يتيح الإصدار 1 إمكانية نسخ "بيانات المؤتمر" بالإضافة إلى إنشاء مؤتمرات جديدة باستخدام الحقل createRequest في بيانات المؤتمر. والقيمة التلقائية هي 0. تتراوح القيم المقبولة بين 0 و1، بما في ذلك القيم الواقعة بينهما.
supportsAttachments boolean ما إذا كان تنفيذ عميل واجهة برمجة التطبيقات يتيح استخدام مرفقات الأحداث اختياريّ. والقيمة التلقائية هي "خطأ".

التفويض

يتطلب هذا الطلب تفويضًا باستخدام نطاق واحد على الأقل من النطاقات التالية:

النطاق
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.events

للحصول على مزيد من المعلومات، يمكنك الاطلاع على صفحة المصادقة والتفويض.

نص الطلب

في نص الطلب، وفِّر مورد الأحداث بالخصائص التالية:

اسم الموقع القيمة الوصف Notes
الخصائص المطلوبة
end nested object تمثّل هذه السمة وقت انتهاء الحدث (الحصري). بالنسبة إلى حدث متكرر، هذا هو وقت انتهاء الحدث الأول.
iCalUID string المعرّف الفريد للحدث على النحو المحدّد في RFC5545. ويتم استخدامه لتعريف الأحداث بشكل فريد عبر أنظمة التقويم ويجب تقديمه عند استيراد الأحداث من خلال طريقة import.

يُرجى العِلم أنّ حقلَي iCalUID وid غير متطابقَين ويجب تقديم حقل واحد منهما فقط في وقت إنشاء الحدث. الاختلاف الوحيد في دلالاتهما هو أنه في الأحداث المتكررة، تحتوي جميع تكرارات أحد الأحداث على id مختلفة بينما تشترك جميعها في نفس iCalUID. لاسترداد حدث باستخدام السمة iCalUID، يمكنك استدعاء طريقةevents.list باستخدام مَعلمة iCalUID. لاسترداد حدث باستخدام id التابع له، يمكنك استدعاء طريقة events.get.
start nested object وقت بدء الحدث (بشكل شامل). بالنسبة إلى حدث متكرر، يكون هذا هو وقت بدء الحدث الأول.
السمات الاختيارية
anyoneCanAddSelf boolean ما إذا كان بإمكان أي شخص دعوة نفسه إلى الحدث (متوقف). اختياريّ. والقيمة التلقائية هي "خطأ". قابل للكتابة
attachments[].fileUrl string عنوان URL المؤدي إلى المرفق.

لإضافة مرفقات ملفات من Google Drive، استخدِم التنسيق نفسه المستخدَم في السمة alternateLink في المورد Files في Drive API.

مطلوب عند إضافة مرفق.

 قابل للكتابة
attendees[] list المشاركون في الفعالية. يمكنك الاطّلاع على دليل الأحداث التي يشارك فيها ضيوف للحصول على مزيد من المعلومات حول جدولة الأحداث مع مستخدمي التقويم الآخرين. يجب أن تستخدم حسابات الخدمة تفويض المرجع على مستوى النطاق لتعبئة قائمة الضيوف. قابل للكتابة
attendees[].additionalGuests integer عدد النزلاء الإضافيين اختياريّ. والقيمة التلقائية هي 0. قابل للكتابة
attendees[].comment string التعليق على ردّ الضيف اختياريّ. قابل للكتابة
attendees[].displayName string تشير هذه السمة إلى اسم الضيف، إذا كان متوفّرًا. اختياريّ. قابل للكتابة
attendees[].email string عنوان البريد الإلكتروني للضيف، إذا كان متاحًا يجب أن يكون هذا الحقل متاحًا عند إضافة ضيف. ويجب أن يكون عنوان بريد إلكتروني صالحًا وفق RFC5322.

مطلوب عند إضافة ضيف.

 قابل للكتابة
attendees[].optional boolean ما إذا كان هذا الحاضر اختياريًا. اختياريّ. والقيمة التلقائية هي "خطأ". قابل للكتابة
attendees[].resource boolean تُستخدَم لتحديد ما إذا كان الضيف مصدرًا. لا يمكن ضبط هذا الإعداد إلا عند إضافة الضيف إلى الحدث للمرة الأولى. ويتم تجاهل التعديلات اللاحقة. اختياريّ. والقيمة التلقائية هي "خطأ". قابل للكتابة
attendees[].responseStatus string حالة ردّ الضيف القيم المتاحة:
  • "needsAction" - لم يردّ الضيف على الدعوة (وهذا الإجراء مقترَح للأحداث الجديدة).
  • "declined" - رفض الضيف الدعوة.
  • "tentative" - قبل الضيف الدعوة بشكل مبدئي.
  • "accepted" - قبل الضيف الدعوة.
 قابل للكتابة
attendeesOmitted boolean تُستخدَم لتحديد ما إذا كان قد تم حذف الضيوف من تمثيل الحدث. عند استرداد حدث، قد يرجع ذلك إلى قيود تحدّدها مَعلمة طلب البحث maxAttendee. عند تحديث حدث، يمكن استخدام ذلك لتحديث رد المشارك فقط. اختياريّ. والقيمة التلقائية هي "خطأ". قابل للكتابة
colorId string لون الحدث هذا معرّف يشير إلى إدخال في القسم event من تعريف الألوان (راجِع نقطة نهاية الألوان). اختياريّ. قابل للكتابة
conferenceData nested object المعلومات المتعلقة بمكالمات الفيديو، مثل تفاصيل مكالمة فيديو على Google Meet لإنشاء تفاصيل جديدة لمكالمات الفيديو، استخدِم الحقل createRequest. للاستمرار في إجراء التغييرات، تذكّر ضبط مَعلمة طلب conferenceDataVersion على 1 لجميع طلبات تعديل الأحداث. قابل للكتابة
description string تمثّل هذه السمة وصف الفعالية. يمكن أن تحتوي على HTML. اختياريّ. قابل للكتابة
end.date date التاريخ، بالتنسيق "yyyy-mm-dd"، إذا كان هذا الحدث يستمر طوال اليوم. قابل للكتابة
end.dateTime datetime الوقت، كقيمة مجمّعة للتاريخ والوقت (بتنسيق RFC3339). يجب معادلة المنطقة الزمنية ما لم يتم تحديد منطقة زمنية صراحةً في timeZone. قابل للكتابة
end.timeZone string المنطقة الزمنية التي يتم تحديد الوقت فيها. (منسق كاسم قاعدة بيانات المناطق الزمنية الصادرة عن منظمة IANA (المنظمة المعنية بأرقام الإنترنت المخصصة)، مثل "أوروبا/زيورخ"). بالنسبة إلى الأحداث المتكرّرة، يكون هذا الحقل مطلوبًا، ويحدّد المنطقة الزمنية التي يتم توسيع التكرار فيها. بالنسبة إلى الأحداث الفردية، يكون هذا الحقل اختياريًا ويشير إلى منطقة زمنية مخصّصة لبداية الحدث أو نهايته. قابل للكتابة
extendedProperties.private object الخصائص الخاصة بنسخة الحدث الذي يظهر في هذا التقويم. قابل للكتابة
extendedProperties.shared object الخصائص التي تتم مشاركتها بين نُسخ الحدث في تقاويم الضيوف الآخرين. قابل للكتابة
focusTimeProperties nested object بيانات أحداث وقت التركيز تُستخدَم إذا كانت قيمة eventType هي focusTime. قابل للكتابة
gadget.display string وضع عرض الأداة. تمّ الإيقاف. القيم المتاحة:
  • "icon" - يتم عرض الأداة إلى جانب عنوان الحدث في عرض التقويم.
  • "chip" - يتم عرض الأداة عند النقر على الحدث.
 قابل للكتابة
gadget.height integer ارتفاع الأداة بالبكسل. يجب أن يكون الارتفاع عددًا صحيحًا أكبر من 0. اختياريّ. تمّ الإيقاف. قابل للكتابة
gadget.preferences object الإعدادات المفضّلة. قابل للكتابة
gadget.title string عنوان الأداة. تمّ الإيقاف. قابل للكتابة
gadget.type string نوع الأداة. تمّ الإيقاف. قابل للكتابة
gadget.width integer عرض الأداة بالبكسل. يجب أن يكون العرض عددًا صحيحًا أكبر من 0. اختياريّ. تمّ الإيقاف. قابل للكتابة
guestsCanInviteOthers boolean ما إذا كان بإمكان الضيوف غير المنظِّم دعوة الآخرين إلى الحدث اختياريّ. والقيمة التلقائية هي "صحيح". قابل للكتابة
guestsCanModify boolean ما إذا كان بإمكان الضيوف غير المنظِّم تعديل الحدث اختياريّ. والقيمة التلقائية هي "خطأ". قابل للكتابة
guestsCanSeeOtherGuests boolean ما إذا كان بإمكان الضيوف، غير المنظِّم، معرفة الحاضرين في الحدث. اختياريّ. والقيمة التلقائية هي "صحيح". قابل للكتابة
location string الموقع الجغرافي للفعالية كنص مرن اختياريّ. قابل للكتابة
organizer object منظِّم الحدث. وإذا كان المنظِّم أيضًا ضيفًا، تتم الإشارة إلى ذلك بإدخال منفصل في attendees مع ضبط الحقل organizer على "صحيح". لتغيير المنظم، استخدِم عملية النقل. للقراءة فقط، إلا عند استيراد حدث. قابل للكتابة
organizer.displayName string تشير هذه السمة إلى اسم المنظِّم، إذا كان متاحًا. قابل للكتابة
organizer.email string تمثّل هذه السمة عنوان البريد الإلكتروني للمنظِّم، إذا كان متاحًا. ويجب أن يكون عنوان بريد إلكتروني صالحًا وفق RFC5322. قابل للكتابة
originalStartTime.date date التاريخ، بالتنسيق "yyyy-mm-dd"، إذا كان هذا الحدث يستمر طوال اليوم. قابل للكتابة
originalStartTime.dateTime datetime الوقت، كقيمة مجمّعة للتاريخ والوقت (بتنسيق RFC3339). يجب معادلة المنطقة الزمنية ما لم يتم تحديد منطقة زمنية صراحةً في timeZone. قابل للكتابة
originalStartTime.timeZone string المنطقة الزمنية التي يتم تحديد الوقت فيها. (منسق كاسم قاعدة بيانات المناطق الزمنية الصادرة عن منظمة IANA (المنظمة المعنية بأرقام الإنترنت المخصصة)، مثل "أوروبا/زيورخ"). بالنسبة إلى الأحداث المتكرّرة، يكون هذا الحقل مطلوبًا، ويحدّد المنطقة الزمنية التي يتم توسيع التكرار فيها. بالنسبة إلى الأحداث الفردية، يكون هذا الحقل اختياريًا ويشير إلى منطقة زمنية مخصّصة لبداية الحدث أو نهايته. قابل للكتابة
outOfOfficeProperties nested object بيانات الأحداث خارج المكتب تُستخدَم إذا كانت قيمة eventType هي outOfOffice. قابل للكتابة
recurrence[] list قائمة أسطر RRU وEXCODE وRDATE وEXDATE لحدث متكرر، على النحو المحدّد في RFC5545. تجدر الإشارة إلى أنّه لا يُسمح باستخدام أسطر DTSTART وDTEND في هذا الحقل، مع العلم أنّ وقت بدء الحدث ووقت انتهائه محدّدان في الحقلين start وend. يتم حذف هذا الحقل للأحداث الفردية أو الحالات المتكررة للأحداث. قابل للكتابة
reminders.overrides[] list إذا كان الحدث لا يستخدم التذكيرات التلقائية، سيؤدّي ذلك إلى إدراج التذكيرات الخاصة بالحدث، أو إذا لم يتم ضبطه، يشير إلى أنّه لم يتم ضبط أيّ تذكيرات لهذا الحدث. الحد الأقصى لعدد تذكيرات الإلغاء هو 5. قابل للكتابة
reminders.overrides[].method string تمثّل هذه السمة الطريقة المستخدمة في هذا التذكير. القيم المتاحة:
  • "email" - يتم إرسال التذكيرات عبر البريد الإلكتروني.
  • "popup" - يتم إرسال التذكيرات من خلال نافذة منبثقة لواجهة المستخدم.

مطلوبة عند إضافة تذكير.

 قابل للكتابة
reminders.overrides[].minutes integer يشير ذلك إلى عدد الدقائق التي تسبق بدء الحدث والتزامن مع تشغيل التذكير. تتراوح القيم الصالحة بين 0 و40320 (4 أسابيع بالدقائق).

مطلوبة عند إضافة تذكير.

 قابل للكتابة
reminders.useDefault boolean ما إذا كانت التذكيرات التلقائية للتقويم تنطبق على الحدث أم لا. قابل للكتابة
sequence integer رقم التسلسل وفقًا لـ iالتقويم قابل للكتابة
source.title string عنوان المصدر، مثل عنوان صفحة ويب أو موضوع رسالة إلكترونية. قابل للكتابة
source.url string تمثّل هذه السمة عنوان URL للمصدر الذي يشير إلى مورد. يجب أن يكون مخطط عنوان URL إما HTTP أو HTTPS. قابل للكتابة
start.date date التاريخ، بالتنسيق "yyyy-mm-dd"، إذا كان هذا الحدث يستمر طوال اليوم. قابل للكتابة
start.dateTime datetime الوقت، كقيمة مجمّعة للتاريخ والوقت (بتنسيق RFC3339). يجب معادلة المنطقة الزمنية ما لم يتم تحديد منطقة زمنية صراحةً في timeZone. قابل للكتابة
start.timeZone string المنطقة الزمنية التي يتم تحديد الوقت فيها. (منسق كاسم قاعدة بيانات المناطق الزمنية الصادرة عن منظمة IANA (المنظمة المعنية بأرقام الإنترنت المخصصة)، مثل "أوروبا/زيورخ"). بالنسبة إلى الأحداث المتكرّرة، يكون هذا الحقل مطلوبًا، ويحدّد المنطقة الزمنية التي يتم توسيع التكرار فيها. بالنسبة إلى الأحداث الفردية، يكون هذا الحقل اختياريًا ويشير إلى منطقة زمنية مخصّصة لبداية الحدث أو نهايته. قابل للكتابة
status string حالة الحدث اختياريّ. القيم المتاحة:
  • "confirmed" - تم تأكيد الحدث. وهذه هي الحالة التلقائية.
  • "tentative" - تم تأكيد الحدث مبدئيًا.
  • "cancelled" - تم إلغاء الحدث (محذوف). تعرض طريقة list الأحداث الملغاة فقط في المزامنة التزايدية (عند تحديد syncToken أو updatedMin) أو في حال ضبط علامة showDeleted على true. وتعرض طريقة get دائمًا هذه القيم.

    تمثّل الحالة "تم الإلغاء" حالتَين مختلفتَين استنادًا إلى نوع الحدث:

    1. تشير الاستثناءات الملغاة لحدث متكرّر لم يتم إلغاؤه إلى أنّه يجب عدم تقديم هذا المثيل للمستخدم بعد ذلك. وعلى العملاء تخزين هذه الأحداث طوال فترة الحدث الرئيسي المتكرّر.

      يمكن أن تضمن الاستثناءات المُلغاة فقط تعبئة قيم الحقول id وrecurringEventId وoriginalStartTime. وقد تكون الحقول الأخرى فارغة.

    2. أما جميع الأحداث الأخرى المُلغاة، فتمثل أحداثًا محذوفة. وعلى العملاء إزالة النُسخ التي تمت مزامنتها محليًا. ستختفي هذه الأحداث الملغاة في النهاية، لذا لا تعتمد على إتاحتها إلى أجل غير مسمى.

      يمكن ضمان تعبئة الحقل id فقط للأحداث المحذوفة.

    في تقويم المنظِّم، تستمر الأحداث المُلغاة في عرض تفاصيل الحدث (الملخص والموقع الجغرافي وما إلى ذلك) حتى يمكن استعادتها (إلغاء حذفها). وبالمثل، تستمر الأحداث التي تمت دعوة المستخدم إليها والتي تمت إزالتها يدويًا في تقديم التفاصيل. ومع ذلك، لن تعرض طلبات المزامنة المتزايدة عند ضبط showDeleted على "خطأ" هذه التفاصيل.

    في حال تغيير منظِّم الحدث (من خلال عملية النقل مثلاً) ولم يكن المنظِّم الأصلي مدرَجًا في قائمة الضيوف، سيترك حدثًا ملغيًا حيث يمكن ضمان تعبئة الحقل id فقط.

قابل للكتابة
summary string تمثل هذه الخاصية عنوان الفعالية. قابل للكتابة
transparency string ما إذا كان الحدث سيحظر الوقت في التقويم اختياريّ. القيم المتاحة:
  • "opaque" - القيمة التلقائية يحظر الحدث وقتًا في التقويم. يعادل ذلك إعداد عرض كـ على مشغول في واجهة مستخدم التقويم.
  • "transparent": لا يحظر الحدث وقتًا في التقويم. يعادل ذلك ضبط عرضي كـ على متاح في واجهة مستخدم "تقويم Google".
 قابل للكتابة
visibility string مستوى رؤية الحدث. اختياريّ. القيم المتاحة:
  • "default" - يستخدم مستوى الرؤية التلقائي للأحداث في التقويم. هذه هي القيمة الافتراضية.
  • "public" - الحدث علني وتفاصيل الحدث مرئية لجميع برامج قراءة التقويم.
  • "private" - الحدث خاص ويمكن لضيوف الحدث فقط الاطّلاع على تفاصيله.
  • "confidential" - الحدث خاص. يتم توفير هذه القيمة لأسباب تتعلق بالتوافق.
 قابل للكتابة

الإجابة

في حال نجاح هذا الإجراء، تعرِض هذه الطريقة مورد الأحداث في نص الاستجابة.

أمثلة

ملاحظة: إنّ الأمثلة المرتبطة بالرموز والمتوفرة لهذه الطريقة لا تمثّل كل لغات البرمجة المتوافقة (يُرجى مراجعة صفحة مكتبات البرامج للاطّلاع على قائمة باللغات المتوافقة).

Java

تستخدم مكتبة عملاء Java.

import com.google.api.services.calendar.Calendar;
import com.google.api.services.calendar.model.Event;
import com.google.api.services.calendar.model.EventAttendee;
import com.google.api.services.calendar.model.EventDateTime;
import com.google.api.client.util.DateTime;

import java.util.Date;
// ...

// Initialize Calendar service with valid OAuth credentials
Calendar service = new Calendar.Builder(httpTransport, jsonFactory, credentials)
    .setApplicationName("applicationName").build();

// Create and initialize a new event (could also retrieve an existing event)
Event event = new Event();
event.setICalUID("originalUID");

Event.Organizer organizer = new Event.Organizer();
organizer.setEmail("organizerEmail");
organizer.setDisplayName("organizerDisplayName");
event.setOrganizer(organizer);

ArrayList<EventAttendee> attendees = new ArrayList<EventAttendee>();
attendees.add(new EventAttendee().setEmail("attendeeEmail"));
// ...
event.setAttendees(attendees);

Date startDate = new Date();
Date endDate = new Date(startDate.getTime() + 3600000);
DateTime start = new DateTime(startDate, TimeZone.getTimeZone("UTC"));
event.setStart(new EventDateTime().setDateTime(start));
DateTime end = new DateTime(endDate, TimeZone.getTimeZone("UTC"));
event.setEnd(new EventDateTime().setDateTime(end));

// Import the event into a calendar
Event importedEvent = service.events().calendarImport('primary', event).execute();

System.out.println(importedEvent.getId());

Python

تستخدم مكتبة برامج Python.

event = {
  'summary': 'Appointment',
  'location': 'Somewhere',
  'organizer': {
    'email': 'organizerEmail',
    'displayName': 'organizerDisplayName'
  },
  'start': {
    'dateTime': '2011-06-03T10:00:00.000-07:00'
  },
  'end': {
    'dateTime': '2011-06-03T10:25:00.000-07:00'
  },
  'attendees': [
    {
      'email': 'attendeeEmail',
      'displayName': 'attendeeDisplayName',
    },
    # ...
  ],
  'iCalUID': 'originalUID'
}

imported_event = service.events().import_(calendarId='primary', body=event).execute()

print imported_event['id']

PHP

تستخدم مكتبة برامج PHP.

$event = new Google_Service_Calendar_Event();
$event->setSummary('Appointment');
$event->setLocation('Somewhere');
$start = new Google_Service_Calendar_EventDateTime();
$start->setDateTime('2011-06-03T10:00:00.000-07:00');
$event->setStart($start);
$end = new Google_Service_Calendar_EventDateTime();
$end->setDateTime('2011-06-03T10:25:00.000-07:00');
$event->setEnd($end);
$attendee1 = new Google_Service_Calendar_EventAttendee();
$attendee1->setEmail('attendeeEmail');
// ...
$attendees = array($attendee1,
                   // ...,
                  );
$event->attendees = $attendees;
$organizer = new Google_Service_Calendar_EventOrganizer();
$organizer->setEmail('organizerEmail');
$organizer->setDisplayName('organizerDisplayName');
$event->setOrganizer($organizer);
$event->setICalUID('originalUID');
$importedEvent = $service->events->import('primary', $event);

echo $importedEvent->getId();

Ruby

تستخدم مكتبة برامج Ruby.

event = Google::Apis::CalendarV3::Event.new(
  summary: 'Appointment',
  location: 'Somewhere',
  organizer: {
    email: 'organizerEmail',
    display_name: 'organizerDisplayName'
  },
  start: {
    date_time: '2011-06-03T10:00:00.000-07:00'
  },
  end: {
    date_time: '2011-06-03T10:25:00.000-07:00'
  },
  attendees: [
    {
      email: 'attendeeEmail',
      display_name: 'attendeeDisplayName',
    },
    # ...
  ],
  i_cal_uid: 'originalUID'
)
result = client.import_event('primary', event)
print result.id

تجربة

استخدِم مستكشف واجهات برمجة التطبيقات أدناه لطلب هذه الطريقة على البيانات المباشرة والاطّلاع على الردّ.