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 إمكانية نسخ ConferenceData بالإضافة إلى إنشاء مكالمات فيديو جديدة باستخدام حقل createRequest في conferenceData. القيمة التلقائية هي 0. القيم المقبولة هي من 0 إلى 1.
supportsAttachments boolean ما إذا كان عميل واجهة برمجة التطبيقات الذي يُجري العملية يتيح مرفقات الأحداث اختياريّ. القيمة التلقائية هي False.

التفويض

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

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

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

نص الطلب

في نص الطلب، قدِّم مرجع أحداث يتضمّن السمات التالية:

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

تجدر الإشارة إلى أنّ السمتَين iCalUID وid غير متطابقتَين، ويجب تقديم سمة واحدة فقط في وقت إنشاء الحدث. يتمثل أحد الاختلافات في الدلالات في أنّه في الأحداث المتكرّرة، يكون لكلّ مرّة من مرّات حدوث حدث معيّن id مختلفة، في حين تتشارك جميعها iCalUID نفسها. لاسترداد حدث باستخدام iCalUID، يمكنك استدعاء الطريقة events.list باستخدام المَعلمة iCalUID. لاسترداد حدث باستخدام id، يمكنك استدعاء الطريقة events.get.
start nested object وقت بدء الحدث (شاملاً) بالنسبة إلى الحدث المتكرّر، يشير ذلك إلى وقت بدء النسخة الأولى.
السمات الاختيارية
anyoneCanAddSelf boolean ما إذا كان بإمكان أي مستخدم دعوة نفسه إلى الحدث (ميزة متوقّفة نهائيًا) اختياريّ. القيمة التلقائية هي False. قابلة للكتابة
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 ما إذا كان هذا الضيف اختياريًا. اختياريّ. القيمة التلقائية هي False. قابلة للكتابة
attendees[].resource boolean ما إذا كان الحاضر مورّدًا لا يمكن ضبط هذا الخيار إلا عند إضافة الضيف إلى الحدث للمرة الأولى. ويتم تجاهل التعديلات اللاحقة. اختياريّ. القيمة التلقائية هي False. قابلة للكتابة
attendees[].responseStatus string حالة ردّ الحاضر القيم المحتمَلة هي:
  • "needsAction" - لم يردّ الضيف على الدعوة (ننصح باستخدام هذا الخيار للأحداث الجديدة).
  • "declined" - رفض الحاضر الدعوة.
  • "tentative": قبِل الضيف الدعوة بشكل مبدئي.
  • "accepted" - قبِل الحاضر الدعوة.
 قابلة للكتابة
attendeesOmitted boolean ما إذا كان قد تم حذف الضيوف من تمثيل الحدث عند استرداد حدث، قد يرجع ذلك إلى قيد محدّد من خلال مَعلمة طلب البحث maxAttendee. عند تعديل حدث، يمكن استخدام هذا الحقل لتعديل ردّ المشارك فقط. اختياريّ. القيمة التلقائية هي False. قابلة للكتابة
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 ما إذا كان بإمكان الضيوف غير المُنظِم دعوة مستخدمين آخرين إلى الحدث اختياريّ. القيمة التلقائية هي True. قابلة للكتابة
guestsCanModify boolean ما إذا كان بإمكان الضيوف غير المنظِّم تعديل الحدث اختياريّ. القيمة التلقائية هي False. قابلة للكتابة
guestsCanSeeOtherGuests boolean ما إذا كان بإمكان الضيوف غير المنظِّم الاطّلاع على الضيوف المشاركين في الحدث اختياريّ. القيمة التلقائية هي True. قابلة للكتابة
location string الموقع الجغرافي للحدث بتنسيق نصي حر اختياريّ. قابلة للكتابة
organizer object منظِّم الحدث. إذا كان المنظِّم مشاركًا أيضًا، يتم الإشارة إلى ذلك من خلال إدخال منفصل في attendees مع ضبط الحقل organizer على True. لتغيير المنظِّم، استخدِم عملية نقل. للقراءة فقط، باستثناء استيراد حدث. قابلة للكتابة
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 قائمة بخطوط RRULE وEXRULE و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 الرقم التسلسلي وفقًا لتنسيق iCalendar قابلة للكتابة
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": القيمة التلقائية. يحظر الحدث وقتًا في التقويم. ويعادل ذلك ضبط إظهاري على أنّني على مشغول في واجهة مستخدم "تقويم Google".
  • "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

جرّب الآن

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