Imaginez une application qui aide les utilisateurs à trouver les meilleurs itinéraires de randonnée. En ajoutant le programme de randonnée en tant qu'événement d'agenda, les utilisateurs obtiennent beaucoup d'aide pour rester organisés automatiquement. Google Agenda les aide à partager le plan et leur rappelle celui-ci pour qu'ils puissent se préparer sans stress. De plus, grâce à l'intégration parfaite des produits Google, Google Now les pingue pour indiquer l'heure de départ et Google Maps les oriente vers le lieu du rendez-vous à l'heure.
Cet article explique comment créer des événements d'agenda et les ajouter aux agendas de vos utilisateurs.
Ajouter un événement
Pour créer un événement, appelez la méthode events.insert()
en fournissant au moins les paramètres suivants:
calendarId
est l'identifiant de l'agenda. Il peut s'agir de l'adresse e-mail de l'agenda sur lequel créer l'événement ou d'un mot clé spécial'primary'
qui utilisera l'agenda principal de l'utilisateur connecté. Si vous ne connaissez pas l'adresse e-mail de l'agenda que vous souhaitez utiliser, vous pouvez la vérifier dans les paramètres de l'agenda dans l'UI Web de Google Agenda (dans la section "Adresse de l'agenda") ou la rechercher dans le résultat de l'appelcalendarList.list()
.event
est l'événement à créer avec tous les détails nécessaires, tels que le début et la fin. Les deux seuls champs obligatoires sont les champsstart
etend
. Consultez la documentation de référence surevent
pour obtenir l'ensemble complet des champs d'événement.
Pour pouvoir créer des événements, vous devez:
- Définissez le champ d'application OAuth sur
https://www.googleapis.com/auth/calendar
pour être autorisé à modifier l'agenda de l'utilisateur. - Assurez-vous que l'utilisateur authentifié dispose d'un accès en écriture à l'agenda avec le
calendarId
que vous avez fourni (par exemple, en appelantcalendarList.get()
pourcalendarId
et en vérifiant leaccessRole
).
Ajouter des métadonnées d'événement
Vous pouvez éventuellement ajouter des métadonnées d'événement lorsque vous créez un événement d'agenda. Si vous choisissez de ne pas ajouter de métadonnées lors de la création, vous pouvez mettre à jour de nombreux champs à l'aide de events.update()
. Toutefois, certains champs, tels que l'ID de l'événement, ne peuvent être définis que lors d'une opération events.insert()
.
- Lieu
L'ajout d'une adresse dans le champ "Emplacement" permet d'utiliser des fonctionnalités telles que
"il est l'heure de partir" ou afficher l'itinéraire sur une carte.
- ID de l'événement
Lorsque vous créez un événement, vous pouvez choisir de générer votre propre ID d'événement
qui respecte nos exigences de format. Cela vous permet de synchroniser les entités de votre base de données locale avec les événements de Google Agenda. Cela empêche également la création d'événements en double si l'opération échoue à un moment donné après son exécution dans le backend d'Agenda. Si aucun ID d'événement n'est fourni, le serveur en génère un pour vous. Pour en savoir plus, consultez la documentation de référence sur les ID d'événement.
- Participants
L'événement que vous créez apparaît dans tous les agendas Google principaux de
les participants que vous avez inclus avec le même ID d'événement. Si vous définissez
sendNotifications
surtrue
dans votre requête d'insertion, les participants recevront également une notification par e-mail pour votre événement. Pour en savoir plus, consultez le guide sur les événements avec plusieurs participants.
Les exemples suivants illustrent la création d'un événement et la définition de ses métadonnées:
Go
// 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}"
Ajouter des pièces jointes Drive à des événements
Vous pouvez joindre à vos événements d'agenda des fichiers Google Drive tels que des notes de réunion dans Docs, des budgets dans Sheets, des présentations dans Slides ou tout autre fichier Google Drive pertinent. Vous pouvez ajouter la pièce jointe lorsque vous créez un événement avec events.insert()
ou ultérieurement dans le cadre d'une mise à jour, par exemple avec events.patch()
.
L'ajout d'un fichier Google Drive à un événement se fait en deux étapes:
- Obtenez l'URL
alternateLink
,title
etmimeType
du fichier à partir de la ressource de fichiers de l'API Drive, généralement avec la méthodefiles.get()
. - Créez ou mettez à jour un événement avec les champs
attachments
définis dans le corps de la requête et le paramètresupportsAttachments
défini surtrue
.
L'exemple de code suivant montre comment mettre à jour un événement existant pour ajouter une pièce jointe:
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()
Ajouter des visioconférences et des conférences téléphoniques aux événements
Vous pouvez associer des événements à des conférences Hangouts et Google Meet pour permettre à vos utilisateurs de se réunir à distance via un appel téléphonique ou vidéo.
Le champ conferenceData
permet de lire, de copier et d'effacer les informations d'une conférence existante. Il peut également être utilisé pour demander la création de nouvelles conférences. Pour autoriser la création et la modification des détails de la conférence, définissez le paramètre de requête conferenceDataVersion
sur 1
.
Trois types de conferenceData
sont actuellement acceptés, comme indiqué par conferenceData.conferenceSolution.key.type
:
- Hangouts grand public (
eventHangout
) - Version classique de Hangouts pour Google Workspace les utilisateurs
(obsolète;
eventNamedHangout
) - Google Meet (
hangoutsMeet
)
Pour savoir quel type de conférence est compatible avec un agenda donné d'un utilisateur, consultez le conferenceProperties.allowedConferenceSolutionTypes
dans les collections calendars
et calendarList
. Vous pouvez également savoir si l'utilisateur préfère que des Hangouts soient créés pour tous ses événements nouvellement créés en vérifiant le paramètre autoAddHangouts
dans la collection settings
.
En plus de type
, conferenceSolution
fournit les champs name
et iconUri
que vous pouvez utiliser pour représenter la solution de conférence, comme indiqué ci-dessous:
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);
Vous pouvez créer une conférence pour un événement en fournissant à createRequest
un requestId
nouvellement généré qui peut être un string
aléatoire. Les conférences sont créées de manière asynchrone, mais vous pouvez toujours vérifier l'état de votre requête pour informer vos utilisateurs de ce qui se passe.
Par exemple, pour demander la génération d'une conférence pour un événement existant:
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);
});
Il est possible que la réponse immédiate à cet appel ne contienne pas encore la valeur conferenceData
complète. Cela est indiqué par le code d'état pending
dans le champ status. Le code d'état passe à success
une fois que les informations sur la conférence ont été renseignées. Le champ entryPoints
contient des informations sur les URI des vidéos et des téléphones que les utilisateurs peuvent appeler.
Si vous souhaitez planifier plusieurs événements Agenda avec les mêmes informations sur la conférence, vous pouvez copier l'intégralité de la conferenceData
d'un événement à un autre.
La copie est utile dans certaines situations. Par exemple, supposons que vous développiez une application de recrutement qui configure des événements distincts pour le candidat et l'interviewer. Vous souhaitez protéger l'identité de l'intervieweur tout en vous assurant que tous les participants participent à la même conférence téléphonique.