إنشاء أحداث

تخيل تطبيقًا يساعد المستخدمين في العثور على أفضل مسارات المشي لمسافات طويلة. من خلال إضافة خطة المشي كحدث في التقويم، يحصل المستخدمون على الكثير من المساعدة في الحفاظ على اتّباعهم لجدول زمني منظم تلقائيًا. يساعد "تقويم Google" في مشاركة الخطة ويذكّرهم بها كي يتمكّنوا من الاستعداد بدون أي قلق. بالإضافة إلى ذلك، بفضل دمج منتجات Google بسلاسة، يرسل تطبيق Google Now إشعارًا إلى المستخدمين لإعلامهم بالوقت المناسب للانطلاق، وتنقلهم "خرائط Google" إلى مكان الاجتماع في الوقت المحدّد.

توضِّح هذه المقالة كيفية إنشاء أحداث التقويم وإضافتها إلى تقويمات المستخدمين.

إضافة حدث

لإنشاء حدث، استخدِم الأسلوب events.insert() مع تقديم على الأقلّ المَعلمات التالية:

• calendarId هو معرّف التقويم ويمكن أن يكون عنوان البريد الإلكتروني للتقويم الذي سيتم إنشاء الحدث فيه أو كلمة رئيسية خاصة 'primary' ستستخدم التقويم الأساسي للمستخدم الذي سجّل الدخول. إذا لم تكن تعرف عنوان البريد الإلكتروني للتقويم الذي تريد استخدامه، يمكنك الاطّلاع عليه في إعدادات التقويم في واجهة مستخدم الويب في "تقويم Google" (في قسم "عنوان التقويم") أو يمكنك البحث عنه في نتيجة مكالمة calendarList.list().
• event هو الحدث المطلوب إنشاؤه مع جميع التفاصيل اللازمة، مثل بدء وانتهاء. الحقلان الوحيدان المطلوبان هما وقتا start وend. اطّلِع على مرجع event للاطّلاع على المجموعة الكاملة من ملفّات تعريف الأحداث.
  حدِّد الأحداث الموقّتة باستخدام الحقلَين start.dateTime وend.dateTime. بالنسبة إلى الأحداث التي تستمر على مدار اليوم، استخدِم start.date وend.date بدلاً من ذلك.

لإنشاء الأحداث بنجاح، عليك إجراء ما يلي:

• اضبط نطاق OAuth على https://www.googleapis.com/auth/calendar حتى تتمكّن من الوصول إلى إذن التعديل في تقويم المستخدم.
• تأكَّد من أنّ المستخدم الذي تمّت المصادقة عليه لديه إذن بالكتابة في التقويم باستخدام calendarId الذي قدّمته (على سبيل المثال، من خلال الاتصال calendarList.get() بشأن calendarId والتحقّق من accessRole).

إضافة بيانات وصفية للحدث

يمكنك اختياريًا إضافة بيانات وصفية للحدث عند إنشاء حدث في التقويم. إذا اختَرت عدم إضافة بيانات وصفية أثناء الإنشاء، يمكنك تعديل العديد من الحقول باستخدام الإجراء events.update(). ومع ذلك، لا يمكن ضبط بعض الحقول، مثل رقم تعريف الحدث، إلا أثناء عملية events.insert().

الموقع الجغرافي

تؤدي إضافة عنوان إلى حقل الموقع الجغرافي إلى تفعيل ميزات مثل

"حان وقت المغادرة" أو عرض خريطة تتضمّن الاتجاهات

رقم تعريف الحدث

عند إنشاء حدث، يمكنك اختيار إنشاء رقم تعريف الحدث الخاص بك.

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

الحضور

يظهر الحدث الذي تنشئه في جميع التقاويم الأساسية على "تقويم Google" الخاصة

الضيوف الذين أدرجتهم باستخدام معرّف الحدث نفسه في حال ضبط قيمة sendNotifications على true في طلب الإدراج، سيتلقّى المدعوين أيضًا إشعارًا عبر البريد الإلكتروني بشأن الحدث. اطّلِع على دليل الفعاليات التي تضم مشاركين متعدّدين للحصول على مزيد من المعلومات.

توضِّح الأمثلة التالية كيفية إنشاء حدث وضبط بياناته الوصفية:

انتقال

// Refer to the Go quickstart on how to setup the environment:
// https://developers.google.com/calendar/quickstart/go
// Change the scope to calendar.CalendarScope and delete any stored credentials.

event := &calendar.Event{
  Summary: "Google I/O 2015",
  Location: "800 Howard St., San Francisco, CA 94103",
  Description: "A chance to hear more about Google's developer products.",
  Start: &calendar.EventDateTime{
    DateTime: "2015-05-28T09:00:00-07:00",
    TimeZone: "America/Los_Angeles",
  },
  End: &calendar.EventDateTime{
    DateTime: "2015-05-28T17:00:00-07:00",
    TimeZone: "America/Los_Angeles",
  },
  Recurrence: []string{"RRULE:FREQ=DAILY;COUNT=2"},
  Attendees: []*calendar.EventAttendee{
    &calendar.EventAttendee{Email:"[e-mail]"},
    &calendar.EventAttendee{Email:"[e-mail]"},
  },
}

calendarId := "primary"
event, err = srv.Events.Insert(calendarId, event).Do()
if err != nil {
  log.Fatalf("Unable to create event. %v\n", err)
}
fmt.Printf("Event created: %s\n", event.HtmlLink)

Java

// Refer to the Java quickstart on how to setup the environment:
// https://developers.google.com/calendar/quickstart/java
// Change the scope to CalendarScopes.CALENDAR and delete any stored
// credentials.

Event event = new Event()
    .setSummary("Google I/O 2015")
    .setLocation("800 Howard St., San Francisco, CA 94103")
    .setDescription("A chance to hear more about Google's developer products.");

DateTime startDateTime = new DateTime("2015-05-28T09:00:00-07:00");
EventDateTime start = new EventDateTime()
    .setDateTime(startDateTime)
    .setTimeZone("America/Los_Angeles");
event.setStart(start);

DateTime endDateTime = new DateTime("2015-05-28T17:00:00-07:00");
EventDateTime end = new EventDateTime()
    .setDateTime(endDateTime)
    .setTimeZone("America/Los_Angeles");
event.setEnd(end);

String[] recurrence = new String[] {"RRULE:FREQ=DAILY;COUNT=2"};
event.setRecurrence(Arrays.asList(recurrence));

EventAttendee[] attendees = new EventAttendee[] {
    new EventAttendee().setEmail("[e-mail]"),
    new EventAttendee().setEmail("[e-mail]"),
};
event.setAttendees(Arrays.asList(attendees));

EventReminder[] reminderOverrides = new EventReminder[] {
    new EventReminder().setMethod("email").setMinutes(24 * 60),
    new EventReminder().setMethod("popup").setMinutes(10),
};
Event.Reminders reminders = new Event.Reminders()
    .setUseDefault(false)
    .setOverrides(Arrays.asList(reminderOverrides));
event.setReminders(reminders);

String calendarId = "primary";
event = service.events().insert(calendarId, event).execute();
System.out.printf("Event created: %s\n", event.getHtmlLink());

JavaScript

// Refer to the JavaScript quickstart on how to setup the environment:
// https://developers.google.com/calendar/quickstart/js
// Change the scope to 'https://www.googleapis.com/auth/calendar' and delete any
// stored credentials.

const event = {
  'summary': 'Google I/O 2015',
  'location': '800 Howard St., San Francisco, CA 94103',
  'description': 'A chance to hear more about Google\'s developer products.',
  'start': {
    'dateTime': '2015-05-28T09:00:00-07:00',
    'timeZone': 'America/Los_Angeles'
  },
  'end': {
    'dateTime': '2015-05-28T17:00:00-07:00',
    'timeZone': 'America/Los_Angeles'
  },
  'recurrence': [
    'RRULE:FREQ=DAILY;COUNT=2'
  ],
  'attendees': [
    {'email': '[e-mail]'},
    {'email': '[e-mail]'}
  ],
  'reminders': {
    'useDefault': false,
    'overrides': [
      {'method': 'email', 'minutes': 24 * 60},
      {'method': 'popup', 'minutes': 10}
    ]
  }
};

const request = gapi.client.calendar.events.insert({
  'calendarId': 'primary',
  'resource': event
});

request.execute(function(event) {
  appendPre('Event created: ' + event.htmlLink);
});

Node.js

// Refer to the Node.js quickstart on how to setup the environment:
// https://developers.google.com/calendar/quickstart/node
// Change the scope to 'https://www.googleapis.com/auth/calendar' and delete any
// stored credentials.

const event = {
  'summary': 'Google I/O 2015',
  'location': '800 Howard St., San Francisco, CA 94103',
  'description': 'A chance to hear more about Google\'s developer products.',
  'start': {
    'dateTime': '2015-05-28T09:00:00-07:00',
    'timeZone': 'America/Los_Angeles',
  },
  'end': {
    'dateTime': '2015-05-28T17:00:00-07:00',
    'timeZone': 'America/Los_Angeles',
  },
  'recurrence': [
    'RRULE:FREQ=DAILY;COUNT=2'
  ],
  'attendees': [
    {'email': '[e-mail]'},
    {'email': '[e-mail]'},
  ],
  'reminders': {
    'useDefault': false,
    'overrides': [
      {'method': 'email', 'minutes': 24 * 60},
      {'method': 'popup', 'minutes': 10},
    ],
  },
};

calendar.events.insert({
  auth: auth,
  calendarId: 'primary',
  resource: event,
}, function(err, event) {
  if (err) {
    console.log('There was an error contacting the Calendar service: ' + err);
    return;
  }
  console.log('Event created: %s', event.htmlLink);
});

PHP

$event = new Google_Service_Calendar_Event(array(
  'summary' => 'Google I/O 2015',
  'location' => '800 Howard St., San Francisco, CA 94103',
  'description' => 'A chance to hear more about Google\'s developer products.',
  'start' => array(
    'dateTime' => '2015-05-28T09:00:00-07:00',
    'timeZone' => 'America/Los_Angeles',
  ),
  'end' => array(
    'dateTime' => '2015-05-28T17:00:00-07:00',
    'timeZone' => 'America/Los_Angeles',
  ),
  'recurrence' => array(
    'RRULE:FREQ=DAILY;COUNT=2'
  ),
  'attendees' => array(
    array('email' => '[e-mail]'),
    array('email' => '[e-mail]'),
  ),
  'reminders' => array(
    'useDefault' => FALSE,
    'overrides' => array(
      array('method' => 'email', 'minutes' => 24 * 60),
      array('method' => 'popup', 'minutes' => 10),
    ),
  ),
));

$calendarId = 'primary';
$event = $service->events->insert($calendarId, $event);
printf('Event created: %s\n', $event->htmlLink);

Python

# Refer to the Python quickstart on how to setup the environment:
# https://developers.google.com/calendar/quickstart/python
# Change the scope to 'https://www.googleapis.com/auth/calendar' and delete any
# stored credentials.

event = {
  'summary': 'Google I/O 2015',
  'location': '800 Howard St., San Francisco, CA 94103',
  'description': 'A chance to hear more about Google\'s developer products.',
  'start': {
    'dateTime': '2015-05-28T09:00:00-07:00',
    'timeZone': 'America/Los_Angeles',
  },
  'end': {
    'dateTime': '2015-05-28T17:00:00-07:00',
    'timeZone': 'America/Los_Angeles',
  },
  'recurrence': [
    'RRULE:FREQ=DAILY;COUNT=2'
  ],
  'attendees': [
    {'email': '[e-mail]'},
    {'email': '[e-mail]'},
  ],
  'reminders': {
    'useDefault': False,
    'overrides': [
      {'method': 'email', 'minutes': 24 * 60},
      {'method': 'popup', 'minutes': 10},
    ],
  },
}

event = service.events().insert(calendarId='primary', body=event).execute()
print 'Event created: %s' % (event.get('htmlLink'))

Ruby

event = Google::Apis::CalendarV3::Event.new(
  summary: 'Google I/O 2015',
  location: '800 Howard St., San Francisco, CA 94103',
  description: 'A chance to hear more about Google\'s developer products.',
  start: Google::Apis::CalendarV3::EventDateTime.new(
    date_time: '2015-05-28T09:00:00-07:00',
    time_zone: 'America/Los_Angeles'
  ),
  end: Google::Apis::CalendarV3::EventDateTime.new(
    date_time: '2015-05-28T17:00:00-07:00',
    time_zone: 'America/Los_Angeles'
  ),
  recurrence: [
    'RRULE:FREQ=DAILY;COUNT=2'
  ],
  attendees: [
    Google::Apis::CalendarV3::EventAttendee.new(
      email: '[e-mail]'
    ),
    Google::Apis::CalendarV3::EventAttendee.new(
      email: '[e-mail]'
    )
  ],
  reminders: Google::Apis::CalendarV3::Event::Reminders.new(
    use_default: false,
    overrides: [
      Google::Apis::CalendarV3::EventReminder.new(
        reminder_method: 'email',
        minutes: 24 * 60
      ),
      Google::Apis::CalendarV3::EventReminder.new(
        reminder_method: 'popup',
        minutes: 10
      )
    ]
  )
)

result = client.insert_event('primary', event)
puts "Event created: #{result.html_link}"

إضافة مرفقات Drive إلى الأحداث

يمكنك إرفاق ملفات Google Drive مثل ملاحظات الاجتماعات في "مستندات Google" أو الميزانيات في "جداول بيانات Google" أو العروض التقديمية في "العروض التقديمية من Google" أو أي ملفات أخرى ذات صلة في Google Drive بأحداث التقويم. يمكنك إضافة المرفق عند إنشاء حدث باستخدام events.insert() أو إصدار أحدث كجزء من تعديل، مثل events.patch().

إليك الجزءان من إرفاق ملف Google Drive بحدث:

1. احصل على عنوان URL للملف alternateLink وtitle وmimeType من مصدر ملفات Drive API، عادةً باستخدام الأسلوب files.get().
2. أنشئ حدثًا أو عدِّله باستخدام حقول attachments التي تم ضبطها في ملف attachments الطلب ومَعلمة supportsAttachments التي تم ضبطها على true.

يوضّح مثال الرمز البرمجي التالي كيفية تعديل حدث حالي لإضافة مرفق:

Java

public static void addAttachment(Calendar calendarService, Drive driveService, String calendarId,
    String eventId, String fileId) throws IOException {
  File file = driveService.files().get(fileId).execute();
  Event event = calendarService.events().get(calendarId, eventId).execute();

  List<EventAttachment> attachments = event.getAttachments();
  if (attachments == null) {
    attachments = new ArrayList<EventAttachment>();
  }
  attachments.add(new EventAttachment()
      .setFileUrl(file.getAlternateLink())
      .setMimeType(file.getMimeType())
      .setTitle(file.getTitle()));

  Event changes = new Event()
      .setAttachments(attachments);
  calendarService.events().patch(calendarId, eventId, changes)
      .setSupportsAttachments(true)
      .execute();
}

PHP

function addAttachment($calendarService, $driveService, $calendarId, $eventId, $fileId) {
  $file = $driveService->files->get($fileId);
  $event = $calendarService->events->get($calendarId, $eventId);
  $attachments = $event->attachments;

  $attachments[] = array(
    'fileUrl' => $file->alternateLink,
    'mimeType' => $file->mimeType,
    'title' => $file->title
  );
  $changes = new Google_Service_Calendar_Event(array(
    'attachments' => $attachments
  ));

  $calendarService->events->patch($calendarId, $eventId, $changes, array(
    'supportsAttachments' => TRUE
  ));
}

Python

def add_attachment(calendarService, driveService, calendarId, eventId, fileId):
    file = driveService.files().get(fileId=fileId).execute()
    event = calendarService.events().get(calendarId=calendarId,
                                         eventId=eventId).execute()

    attachments = event.get('attachments', [])
    attachments.append({
        'fileUrl': file['alternateLink'],
        'mimeType': file['mimeType'],
        'title': file['title']
    })

    changes = {
        'attachments': attachments
    }
    calendarService.events().patch(calendarId=calendarId, eventId=eventId,
                                   body=changes,
                                   supportsAttachments=True).execute()

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

إضافة اجتماعات الفيديو والمكالمات الهاتفية إلى الأحداث

يمكنك ربط الأحداث بمكالمات Hangouts ومكالمات Google Meet لسماح المستخدمين بالاجتماع عن بُعد عبر مكالمة هاتفية أو مكالمة فيديو.

يمكن استخدام الحقل conferenceData لقراءة تفاصيل المؤتمرات الحالية ونسخها ومحوها، ويمكن استخدامه أيضًا لطلب إنشاء مؤتمرات جديدة. للسماح بإنشاء تفاصيل المؤتمر وتعديلها، اضبط المَعلمة conferenceDataVersion request على 1.

هناك ثلاثة أنواع من conferenceData متوافقة حاليًا، كما هو موضّح في الرمز conferenceData.conferenceSolution.key.type:

1. Hangouts للمستهلكين (eventHangout)
2. تطبيق Hangouts الكلاسيكي لمستخدمي (تم إيقافه نهائيًا، eventNamedHangout)
3. Google Meet (hangoutsMeet)

يمكنك معرفة نوع المؤتمر المتوافق مع أي تقويم معيّن لمستخدم معيّن من خلال الاطّلاع على conferenceProperties.allowedConferenceSolutionTypes في calendars وcalendarList. يمكنك أيضًا معرفة ما إذا كان المستخدم يفضّل إنشاء مكالمات Hangouts لجميع أحداثه التي تم إنشاؤها حديثًا من خلال التحقّق من الإعداد autoAddHangouts في مجموعة settings.

بالإضافة إلى type، يوفّر conferenceSolution أيضًا الحقلين name و iconUri اللذين يمكنك استخدامهما لتمثيل حلّ المؤتمرات كما هو موضّح أدناه:

JavaScript

const solution = event.conferenceData.conferenceSolution;

const content = document.getElementById("content");
const text = document.createTextNode("Join " + solution.name);
const icon = document.createElement("img");
icon.src = solution.iconUri;

content.appendChild(icon);
content.appendChild(text);

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

على سبيل المثال، لطلب إنشاء مكالمة فيديو لحدث حالي:

JavaScript

const eventPatch = {
  conferenceData: {
    createRequest: {requestId: "7qxalsvy0e"}
  }
};

gapi.client.calendar.events.patch({
  calendarId: "primary",
  eventId: "7cbh8rpc10lrc0ckih9tafss99",
  resource: eventPatch,
  sendNotifications: true,
  conferenceDataVersion: 1
}).execute(function(event) {
  console.log("Conference created for event: %s", event.htmlLink);
});

قد لا تحتوي الاستجابة الفورية لهذا الطلب على conferenceData المعبّأة بالكامل بعد، ويُشار إلى ذلك من خلال رمز الحالة pending في حقل الحالة. يتغيّر رمز الحالة إلى success بعد تعبئة معلومات المؤتمر. يحتوي الحقل entryPoints على معلومات عن معرّفات الموارد المنتظمة (URI) المتاحة للمستخدمين للاتصال بها عبر الفيديو والهاتف.

إذا كنت تريد جدولة أحداث متعددة في "تقويم Google" باستخدام تفاصيل اجتماع الفيديو نفسها، يمكنك نسخ conferenceData بالكامل من حدث إلى حدث آخر.

يكون النسخ مفيدًا في حالات معيّنة. على سبيل المثال، لنفترض أنّك تُطوّر تطبيقًا للتوظيف يُنشئ أحداثًا منفصلة للمتقدّم والشخص الذي يجري المقابلة، وهدفك هو حماية هوية الشخص الذي يجري المقابلة، ولكنك تريد أيضًا التأكّد من انضمام جميع المشاركين إلى مكالمة الفيديو الجماعية نفسها.

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