إنشاء أحداث

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

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

إضافة حدث

لإنشاء حدث، يمكنك استدعاء طريقة events.insert() التي تقدّم المَعلمات التالية على الأقل:

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

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

  • اضبط نطاق 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:"lpage@example.com"},
    &calendar.EventAttendee{Email:"sbrin@example.com"},
  },
}

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("lpage@example.com"),
    new EventAttendee().setEmail("sbrin@example.com"),
};
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': 'lpage@example.com'},
    {'email': 'sbrin@example.com'}
  ],
  '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': 'lpage@example.com'},
    {'email': 'sbrin@example.com'},
  ],
  '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' => 'lpage@example.com'),
    array('email' => 'sbrin@example.com'),
  ),
  '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': 'lpage@example.com'},
    {'email': 'sbrin@example.com'},
  ],
  '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: 'lpage@example.com'
    ),
    Google::Apis::CalendarV3::EventAttendee.new(
      email: 'sbrin@example.com'
    )
  ],
  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()

إضافة مؤتمرات الفيديو والهاتف إلى الأحداث

يمكنك ربط الأحداث بالمؤتمرات على 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 بالكامل من حدث إلى آخر.

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