تخيل تطبيقًا يساعد المستخدمين في العثور على أفضل مسارات المشي لمسافات طويلة. من خلال إضافة خطة المشي كحدث في التقويم، يحصل المستخدمون على الكثير من المساعدة في البقاء منظمين تلقائيًا. يساعدهم تقويم 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 بحدث هما:
- احصل على عنوان URL للملف
alternateLink
وtitle
وmimeType
من مرجع ملفات واجهة برمجة تطبيقات Drive، عادةً باستخدام الطريقةfiles.get()
. - يمكنك إنشاء أو تعديل حدث باستخدام حقول
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
:
- Hangouts للمستهلكين (
eventHangout
) - تطبيق Hangouts الكلاسيكي Google Workspace للمستخدمين
(متوقّف نهائيًا،
eventNamedHangout
) - 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
بالكامل من حدث إلى آخر.
يكون النسخ مفيدًا في مواقف معينة. على سبيل المثال، افترض أنك تعمل على إعداد تطبيق للتوظيف ينشئ أحداثًا منفصلة للمرشح ومجري المقابلة - فأنت تريد حماية هوية مجري المقابلة، ولكنك تريد أيضًا التأكد من انضمام جميع المشاركين إلى نفس المكالمة الجماعية.