إنشاء أحداث

تخيل تطبيقًا يساعد المستخدمين في العثور على أفضل مسارات المشي لمسافات طويلة. من خلال إضافة خطة المشي كحدث في التقويم، يحصل المستخدمون على الكثير من المساعدة في البقاء منظمًا تلقائيًا. يساعدهم تقويم 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، عادةً باستخدام طريقة files.get().
2. يمكنك إنشاء حدث أو تعديله باستخدام الحقلَين 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 على 1.

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

1. Hangouts للمستهلكين (eventHangout)
2. تطبيق Hangouts الكلاسيكي لمستخدمي Google Workspace (متوقّف نهائيًا، 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 لإجراء تعديلات الأحداث) عند إضافة ميزة دعم مكالمات الفيديو إلى تطبيقك الحالي الذي يخزِّن الأحداث محليًا. في حال عدم إجراء المزامنة أولاً، قد تتم إزالة المؤتمرات الحالية من فعاليات المستخدمين بدون قصد.