boîte aux lettresmailbox

Office.context. mailboxOffice.context. mailbox

Permet d’accéder au modèle objet du complément Outlook pour Microsoft Outlook et Microsoft Outlook sur le web.Provides access to the Outlook add-in object model for Microsoft Outlook and Microsoft Outlook on the web.

Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1.01.0
Niveau d’autorisation minimalMinimum permission level RestreinteRestricted
Mode Outlook applicableApplicable Outlook mode Composition ou lectureCompose or read
Membres et méthodesMembers and methods
MembreMember TypeType
ewsUrlewsUrl MembreMember
restUrlrestUrl MembreMember
addHandlerAsyncaddHandlerAsync MéthodeMethod
convertToEwsIdconvertToEwsId MéthodeMethod
convertToLocalClientTimeconvertToLocalClientTime MéthodeMethod
convertToRestIdconvertToRestId MéthodeMethod
convertToUtcClientTimeconvertToUtcClientTime MéthodeMethod
displayAppointmentFormdisplayAppointmentForm MéthodeMethod
displayMessageFormdisplayMessageForm MéthodeMethod
displayNewAppointmentFormdisplayNewAppointmentForm MéthodeMethod
displayNewMessageFormdisplayNewMessageForm MéthodeMethod
getCallbackTokenAsyncgetCallbackTokenAsync MéthodeMethod
getCallbackTokenAsyncgetCallbackTokenAsync MéthodeMethod
getUserIdentityTokenAsyncgetUserIdentityTokenAsync MéthodeMethod
makeEwsRequestAsyncmakeEwsRequestAsync MéthodeMethod
removeHandlerAsyncremoveHandlerAsync MéthodeMethod

Espaces de nomsNamespaces

diagnostics : Fournit des informations de diagnostic à un complément Outlook.diagnostics: Provides diagnostic information to an Outlook add-in.

item : Fournit des méthodes et des propriétés pour accéder à un message ou un rendez-vous dans un complément Outlook.item: Provides methods and properties for accessing a message or appointment in an Outlook add-in.

userProfile : Fournit des informations sur l’utilisateur dans un complément Outlook.userProfile: Provides information about the user in an Outlook add-in.

MembresMembers

ewsUrl :StringewsUrl :String

Obtient l’URL du point de terminaison des services Web Exchange (EWS) pour ce compte de messagerie. Mode lecture uniquement.Gets the URL of the Exchange Web Services (EWS) endpoint for this email account. Read mode only.

Note

Ce membre n’est pas pris en charge dans Outlook pour iOS ou Outlook pour Android.This member is not supported in Outlook for iOS or Outlook for Android.

La valeur ewsUrl peut être utilisée par un service distant pour émettre des appels EWS vers la boîte aux lettres de l’utilisateur. Par exemple, vous pouvez créer un service distant pour obtenir des pièces jointes à partir de l’élément sélectionné.The ewsUrl value can be used by a remote service to make EWS calls to the user's mailbox. For example, you can create a remote service to get attachments from the selected item.

Votre application doit avoir l’autorisation ReadItem spécifiée dans son manifeste pour pouvoir appeler le membre ewsUrl en mode de lecture.Your app must have the ReadItem permission specified in its manifest to call the ewsUrl member in read mode.

En mode composition, vous devez appeler la méthode saveAsync avant de pouvoir utiliser le membre ewsUrl. Votre application doit disposer des autorisations ReadWriteItem pour appeler la méthode saveAsync.In compose mode you must call the saveAsync method before you can use the ewsUrl member. Your app must have ReadWriteItem permissions to call the saveAsync method.

Type :Type:
  • ChaîneString
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1.01.0
Niveau d’autorisation minimalMinimum permission level ReadItemReadItem
Mode Outlook applicableApplicable Outlook mode Composition ou lectureCompose or read

restUrl :StringrestUrl :String

obtient l’URL du point de terminaison REST de ce compte de messagerie.Gets the URL of the REST endpoint for this email account.

La valeur restUrl peut être utilisée pour que l’API REST appelle la boîte aux lettres de l’utilisateur.The restUrl value can be used to make REST API calls to the user's mailbox.

L’autorisation ReadItem doit être spécifiée dans le manifeste de votre application pour appeler le membre restUrl en mode lecture.Your app must have the ReadItem permission specified in its manifest to call the restUrl member in read mode.

En mode composition, vous devez appeler la méthode saveAsync avant de pouvoir utiliser le membre restUrl. Votre application doit disposer des autorisations ReadWriteItem pour appeler la méthode saveAsync.In compose mode you must call the saveAsync method before you can use the restUrl member. Your app must have ReadWriteItem permissions to call the saveAsync method.

Type :Type:
  • ChaîneString
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1,51.5
Niveau d’autorisation minimalMinimum permission level ReadItemReadItem
Mode Outlook applicableApplicable Outlook mode Composition ou lectureCompose or read

MéthodesMethods

addHandlerAsync(eventType, handler, [options], [callback])addHandlerAsync(eventType, handler, [options], [callback])

Ajoute un gestionnaire d’événements pour un événement pris en charge.Adds an event handler for a supported event.

Actuellement, seul le type d’événement Office.EventType.ItemChanged est pris en charge.Currently, the only supported event type is Office.EventType.ItemChanged.

Paramètres :Parameters:
NomName TypeType AttributsAttributes DescriptionDescription
eventType Office.EventTypeOffice.EventType Événement qui doit appeler le gestionnaire.The event that should invoke the handler.
handler FonctionFunction Fonction qui gère l’événement. Cette fonction doit accepter un seul paramètre, qui est un littéral d’objet. La propriété type sur le paramètre correspond au paramètre eventType transmis à addHandlerAsync.The function to handle the event. The function must accept a single parameter, which is an object literal. The type property on the parameter will match the eventType parameter passed to addHandlerAsync.
options ObjetObject <optional><optional> Littéral d’objet contenant une ou plusieurs des propriétés suivantes.An object literal that contains one or more of the following properties.
options.asyncContext ObjetObject <optional><optional> Les développeurs peuvent indiquer un objet auquel ils souhaitent accéder dans la méthode de rappel.Developers can provide any object they wish to access in the callback method.
callback fonctionfunction <optional><optional> Une fois la méthode exécutée, la fonction transmise au paramètre callback est appelée avec un seul paramètre, asyncResult, qui est un objet AsyncResult.When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object.
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1,51.5
Niveau d’autorisation minimalMinimum permission level ReadItemReadItem
Mode Outlook applicableApplicable Outlook mode Composition ou lectureCompose or read
ExempleExample
Office.initialize = function (reason) {
  $(document).ready(function () {
    Office.context.mailbox.addHandlerAsync(Office.EventType.ItemChanged, loadNewItem, function (result) {
      if (result.status === Office.AsyncResultStatus.Failed) {
        // Handle error
      }
    });
  });
};

function loadNewItem(eventArgs) {
  // Load the properties of the newly selected item
  loadProps(Office.context.mailbox.item);
};

convertToEwsId(itemId, restVersion) → {String}convertToEwsId(itemId, restVersion) → {String}

Convertit un ID d’élément mis en forme pour REST au format EWS.Converts an item ID formatted for REST into EWS format.

Note

Cette méthode n’est pas prise en charge dans Outlook pour iOS ou Outlook pour Android.This method is not supported in Outlook for iOS or Outlook for Android.

Les ID d’élément extraits via une API REST (telle que l’API Courrier Outlook ou Microsoft Graph) utilisent un format différent de celui employé par les services web Exchange (EWS). La méthode convertToEwsId convertit un ID mis en forme pour REST au format approprié pour EWS.Item IDs retrieved via a REST API (such as the Outlook Mail API or the Microsoft Graph) use a different format than the format used by Exchange Web Services (EWS). The convertToEwsId method converts a REST-formatted ID into the proper format for EWS.

Paramètres :Parameters:
NomName TypeType DescriptionDescription
itemId StringString ID d’élément mis en forme pour les API REST OutlookAn item ID formatted for the Outlook REST APIs
restVersion Office.MailboxEnums.RestVersionOffice.MailboxEnums.RestVersion Valeur indiquant la version de l’API REST Outlook utilisée pour récupérer l’ID d’élément.A value indicating the version of the Outlook REST API used to retrieve the item ID.
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1.31.3
Niveau d’autorisation minimalMinimum permission level RestreinteRestricted
Mode Outlook applicableApplicable Outlook mode Composition ou lectureCompose or read
Renvoie :Returns:

Type : StringType: String

ExempleExample
// Get an item's ID from a REST API
var restId = 'AAMkAGVlOTZjNTM3LW...';

// Treat restId as coming from the v2.0 version of the
// Outlook Mail API
var ewsId = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);

convertToLocalClientTime(timeValue) → {LocalClientTime}convertToLocalClientTime(timeValue) → {LocalClientTime}

Obtient un dictionnaire contenant les informations d’heure dans l’heure locale du client.Gets a dictionary containing time information in local client time.

Les dates et heures utilisées par une application de messagerie pour Outlook ou Outlook Web App peuvent utiliser des fuseaux horaires différents. Outlook utilise le fuseau horaire de l’ordinateur ; Outlook Web App utilise le fuseau horaire défini dans le Centre d’administration Exchange (CAE). Vous devez gérer les valeurs de date et d’heure afin que les valeurs que vous affichez sur l’interface utilisateur soient toujours cohérentes avec le fuseau horaire attendu par l’utilisateur.The dates and times used by a mail app for Outlook or Outlook Web App can use different time zones. Outlook uses the client computer time zone; Outlook Web App uses the time zone set on the Exchange Admin Center (EAC). You should handle date and time values so that the values you display on the user interface are always consistent with the time zone that the user expects.

Si l’application de messagerie est en cours d’exécution dans Outlook, la méthode convertToLocalClientTime renvoie un objet de dictionnaire dont les valeurs sont définies pour le fuseau horaire de l’ordinateur client. Si l’application de messagerie est en cours d’exécution dans Outlook Web App, la méthode convertToLocalClientTime renvoie un objet de dictionnaire dont les valeurs sont définies pour le fuseau horaire spécifié dans le CAE.If the mail app is running in Outlook, the convertToLocalClientTime method will return a dictionary object with the values set to the client computer time zone. If the mail app is running in Outlook Web App, the convertToLocalClientTime method will return a dictionary object with the values set to the time zone specified in the EAC.

Paramètres :Parameters:
NomName TypeType DescriptionDescription
timeValue DateDate Objet DateA Date object
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1.01.0
Niveau d’autorisation minimalMinimum permission level ReadItemReadItem
Mode Outlook applicableApplicable Outlook mode Composition ou lectureCompose or read
Renvoie :Returns:

Type : LocalClientTimeType: LocalClientTime

convertToRestId(itemId, restVersion) → {String}convertToRestId(itemId, restVersion) → {String}

Convertit un ID d’élément mis en forme pour EWS au format REST.Converts an item ID formatted for EWS into REST format.

Note

Cette méthode n’est pas prise en charge dans Outlook pour iOS ou Outlook pour Android.This method is not supported in Outlook for iOS or Outlook for Android.

Les ID d’élément récupérés via EWS ou la propriété itemId utilisent un format différent de celui employé par les API REST (telles que l’API Courrier Outlook ou Microsoft Graph). La méthode convertToRestId convertit un ID mis en forme pour EWS au format approprié pour REST.Item IDs retrieved via EWS or via the itemId property use a different format than the format used by REST APIs (such as the Outlook Mail API or the Microsoft Graph). The convertToRestId method converts an EWS-formatted ID into the proper format for REST.

Paramètres :Parameters:
NomName TypeType DescriptionDescription
itemId StringString ID d’élément mis en forme pour les services web Exchange (EWS)An item ID formatted for Exchange Web Services (EWS)
restVersion Office.MailboxEnums.RestVersionOffice.MailboxEnums.RestVersion Valeur indiquant la version de l’API REST Outlook avec laquelle l’ID converti sera utilisé.A value indicating the version of the Outlook REST API that the converted ID will be used with.
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1.31.3
Niveau d’autorisation minimalMinimum permission level RestreinteRestricted
Mode Outlook applicableApplicable Outlook mode Composition ou lectureCompose or read
Renvoie :Returns:

Type : StringType: String

ExempleExample
// Get the currently selected item's ID
var ewsId = Office.context.mailbox.item.itemId;

// Convert to a REST ID for the v2.0 version of the
// Outlook Mail API
var restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);

convertToUtcClientTime(input) → {Date}convertToUtcClientTime(input) → {Date}

Obtient un objet Date à partir d’un dictionnaire contenant des informations d’heure.Gets a Date object from a dictionary containing time information.

La méthode convertToUtcClientTime convertit un dictionnaire contenant une date et une heure locales en objet Date avec les valeurs appropriées pour la date et l’heure locales.The convertToUtcClientTime method converts a dictionary containing a local date and time to a Date object with the correct values for the local date and time.

Paramètres :Parameters:
NomName TypeType DescriptionDescription
input LocalClientTimeLocalClientTime Valeur de l’heure locale à convertir.The local time value to convert.
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1.01.0
Niveau d’autorisation minimalMinimum permission level ReadItemReadItem
Mode Outlook applicableApplicable Outlook mode Composition ou lectureCompose or read
Renvoie :Returns:

Objet Date avec l’heure exprimée au format UTC.A Date object with the time expressed in UTC.

Type
Type
DateDate

displayAppointmentForm(itemId)displayAppointmentForm(itemId)

Affiche un rendez-vous de calendrier existant.Displays an existing calendar appointment.

Note

Cette méthode n’est pas prise en charge dans Outlook pour iOS ou Outlook pour Android.This method is not supported in Outlook for iOS or Outlook for Android.

La méthode displayAppointmentForm ouvre un rendez-vous du calendrier existant dans une nouvelle fenêtre du Bureau ou dans une boîte de dialogue sur les appareils mobiles.The displayAppointmentForm method opens an existing calendar appointment in a new window on the desktop or in a dialog box on mobile devices.

Dans Outlook pour Mac, vous pouvez utiliser cette méthode pour afficher un seul rendez-vous qui ne fait pas partie d’une série périodique, ou le rendez-vous principal d’une série périodique, mais vous ne pouvez pas afficher une instance de la série. En effet, dans Outlook pour Mac, vous ne pouvez pas accéder aux propriétés (notamment l’ID d’élément) des instances d’une série périodique.In Outlook for Mac, you can use this method to display a single appointment that is not part of a recurring series, or the master appointment of a recurring series, but you cannot display an instance of the series. This is because in Outlook for Mac, you cannot access the properties (including the item ID) of instances of a recurring series.

Dans Outlook Web App, cette méthode ouvre le formulaire spécifié uniquement si le corps du formulaire comprend 32 Ko de caractères maximum.In Outlook Web App, this method opens the specified form only if the body of the form is less than or equal to 32KB number of characters.

Si l’identificateur de l’élément spécifié n’identifie aucun rendez-vous existant, un volet vierge s’ouvre sur l’ordinateur ou l’appareil client. Par ailleurs, aucun message d’erreur n’est retourné.If the specified item identifier does not identify an existing appointment, a blank pane opens on the client computer or device, and no error message will be returned.

Paramètres :Parameters:
NomName TypeType DescriptionDescription
itemId StringString Identificateur des services web Exchange pour un rendez-vous du calendrier existant.The Exchange Web Services (EWS) identifier for an existing calendar appointment.
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1.01.0
Niveau d’autorisation minimalMinimum permission level ReadItemReadItem
Mode Outlook applicableApplicable Outlook mode Composition ou lectureCompose or read
ExempleExample
Office.context.mailbox.displayAppointmentForm(appointmentId);

displayMessageForm(itemId)displayMessageForm(itemId)

Affiche un message existant.Displays an existing message.

Note

Cette méthode n’est pas prise en charge dans Outlook pour iOS ou Outlook pour Android.This method is not supported in Outlook for iOS or Outlook for Android.

La méthode displayMessageForm ouvre un message existant dans une nouvelle fenêtre du Bureau ou dans une boîte de dialogue sur les appareils mobiles.The displayMessageForm method opens an existing message in a new window on the desktop or in a dialog box on mobile devices.

Dans Outlook Web App, cette méthode ouvre le formulaire indiqué uniquement si le corps du formulaire comprend 32 Ko de caractères maximum.In Outlook Web App, this method opens the specified form only if the body of the form is less than or equal to 32 KB number of characters.

Si l’identificateur de l’élément spécifié n’identifie aucun message existant, aucun message ne s’affiche sur l’ordinateur client. Par ailleurs, aucun message d’erreur n’est retourné.If the specified item identifier does not identify an existing message, no message will be displayed on the client computer, and no error message will be returned.

N’utilisez pas la méthode displayMessageForm ayant une valeur itemId qui représente un rendez-vous. Utilisez la méthode displayAppointmentForm pour afficher un rendez-vous existant, et displayNewAppointmentForm pour afficher un formulaire afin de créer un nouveau rendez-vous.Do not use the displayMessageForm with an itemId that represents an appointment. Use the displayAppointmentForm method to display an existing appointment, and displayNewAppointmentForm to display a form to create a new appointment.

Paramètres :Parameters:
NomName TypeType DescriptionDescription
itemId StringString Identificateur des services web Exchange pour un message existant.The Exchange Web Services (EWS) identifier for an existing message.
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1.01.0
Niveau d’autorisation minimalMinimum permission level ReadItemReadItem
Mode Outlook applicableApplicable Outlook mode Composition ou lectureCompose or read
ExempleExample
Office.context.mailbox.displayMessageForm(messageId);

displayNewAppointmentForm(parameters)displayNewAppointmentForm(parameters)

Affiche un formulaire permettant de créer un rendez-vous du calendrier.Displays a form for creating a new calendar appointment.

Note

Cette méthode n’est pas prise en charge dans Outlook pour iOS ou Outlook pour Android.This method is not supported in Outlook for iOS or Outlook for Android.

La méthode displayNewAppointmentForm ouvre un formulaire qui permet à l’utilisateur de créer un rendez-vous ou une réunion. Si des paramètres sont spécifiés, les champs du formulaire de rendez-vous sont remplis automatiquement avec le contenu des paramètres.The displayNewAppointmentForm method opens a form that enables the user to create a new appointment or meeting. If parameters are specified, the appointment form fields are automatically populated with the contents of the parameters.

Dans Outlook Web App et OWA pour les périphériques, cette méthode affiche toujours un formulaire contenant un champ Participants. Si vous ne spécifiez pas de participants comme arguments d’entrée, la méthode affiche un formulaire contenant le bouton Enregistrer. Si vous avez spécifié des participants, le formulaire inclut ces derniers, en plus du bouton Envoyer.In Outlook Web App and OWA for Devices, this method always displays a form with an attendees field. If you do not specify any attendees as input arguments, the method displays a form with a Save button. If you have specified attendees, the form would include the attendees and a Send button.

Dans le client riche Outlook et Outlook RT, si vous indiquez des participants ou des ressources dans le paramètre requiredAttendees, optionalAttendees, ou resources, cette méthode affiche un formulaire de réunion comportant un bouton Envoyer. Si vous ne spécifiez aucun destinataire, cette méthode affiche un formulaire de rendez-vous avec un bouton Enregistrer et fermer.In the Outlook rich client and Outlook RT, if you specify any attendees or resources in the requiredAttendees, optionalAttendees, or resources parameter, this method displays a meeting form with a Send button. If you don't specify any recipients, this method displays an appointment form with a Save & Close button.

Si l’un des paramètres dépasse les limites définies en matière de taille ou si un nom de paramètre inconnu est spécifié, une exception est levée.If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown.

Paramètres :Parameters:

Note

Tous les paramètres sont facultatifs.All parameters are optional.

NomName TypeType DescriptionDescription
parameters ObjectObject Dictionnaire de paramètres décrivant le nouveau rendez-vous.A dictionary of parameters describing the new appointment.
parameters.requiredAttendees Array.<String> | Array.<EmailAddressDetails>Array.<String> | Array.<EmailAddressDetails> Tableau de chaînes contenant les adresses de messagerie ou tableau contenant un objet EmailAddressDetails pour chacun des participants requis du rendez-vous. Le tableau est limité à 100 entrées maximum.An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the required attendees for the appointment. The array is limited to a maximum of 100 entries.
parameters.optionalAttendees Array.<String> | Array.<EmailAddressDetails>Array.<String> | Array.<EmailAddressDetails> Tableau de chaînes contenant les adresses de messagerie ou tableau contenant un objet EmailAddressDetails pour chacun des participants facultatifs du rendez-vous. Le tableau est limité à 100 entrées maximum.An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the optional attendees for the appointment. The array is limited to a maximum of 100 entries.
parameters.start DateDate Objet Date spécifiant la date et l’heure de début du rendez-vous.A Date object specifying the start date and time of the appointment.
parameters.end DateDate Objet Date spécifiant la date et l’heure de fin du rendez-vous.A Date object specifying the end date and time of the appointment.
parameters.location StringString Chaîne contenant l’emplacement du rendez-vous. La chaîne est limitée à 255 caractères maximum.A string containing the location of the appointment. The string is limited to a maximum of 255 characters.
parameters.resources Array.<String>Array.<String> Tableau de chaînes contenant les ressources requises pour le rendez-vous. Le tableau est limité à 100 entrées maximum.An array of strings containing the resources required for the appointment. The array is limited to a maximum of 100 entries.
parameters.subject StringString Chaîne contenant l’objet du rendez-vous. La chaîne est limitée à 255 caractères maximum.A string containing the subject of the appointment. The string is limited to a maximum of 255 characters.
parameters.body StringString Corps du rendez-vous. La taille du corps du message est limitée à 32 Ko.The body of the appointment. The body content is limited to a maximum size of 32 KB.
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1.01.0
Niveau d’autorisation minimalMinimum permission level ReadItemReadItem
Mode Outlook applicableApplicable Outlook mode LectureRead
ExempleExample
var start = new Date();
var end = new Date();
end.setHours(start.getHours() + 1);

Office.context.mailbox.displayNewAppointmentForm(
  {
    requiredAttendees: ['bob@contoso.com'],
    optionalAttendees: ['sam@contoso.com'],
    start: start,
    end: end,
    location: 'Home',
    resources: ['projector@contoso.com'],
    subject: 'meeting',
    body: 'Hello World!'
  });

displayNewMessageForm(parameters)displayNewMessageForm(parameters)

Affiche un formulaire permettant de créer un message.Displays a form for creating a new message.

La méthode displayNewMessageForm ouvre un formulaire qui permet à l’utilisateur de créer un message.The displayNewMessageForm method opens a form that enables the user to create a new message. Si des paramètres sont spécifiés, les champs du formulaire de message sont remplis automatiquement avec le contenu des paramètres.If parameters are specified, the message form fields are automatically populated with the contents of the parameters.

Si l’un des paramètres dépasse les limites définies en matière de taille ou si un nom de paramètre inconnu est spécifié, une exception est levée.If any of the parameters exceed the specified size limits, or if an unknown parameter name is specified, an exception is thrown.

Paramètres :Parameters:

Note

Tous les paramètres sont facultatifs.All parameters are optional.

NomName TypeType DescriptionDescription
parameters ObjetObject Dictionnaire de paramètres décrivant le nouveau message.A dictionary of parameters describing the new message.
parameters.toRecipients Array.<String> | Array.<EmailAddressDetails>Array.<String> | Array.<EmailAddressDetails> Tableau de chaînes contenant les adresses de messagerie ou tableau contenant un objet EmailAddressDetails pour chacun des destinataires de la ligne À.An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the recipients on the To line. Le tableau est limité à 100 entrées maximum.The array is limited to a maximum of 100 entries.
parameters.ccRecipients Array.<String> | Array.<EmailAddressDetails>Array.<String> | Array.<EmailAddressDetails> Tableau de chaînes contenant les adresses de messagerie ou tableau contenant un objet EmailAddressDetails pour chacun des destinataires de la ligne Cc.An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the recipients on the Cc line. Le tableau est limité à 100 entrées maximum.The array is limited to a maximum of 100 entries.
parameters.bccRecipients Array.<String> | Array.<EmailAddressDetails>Array.<String> | Array.<EmailAddressDetails> Tableau de chaînes contenant les adresses de messagerie ou tableau contenant un objet EmailAddressDetails pour chacun des destinataires de la ligne Cci.An array of strings containing the email addresses or an array containing an EmailAddressDetails object for each of the recipients on the Bcc line. Le tableau est limité à 100 entrées maximum.The array is limited to a maximum of 100 entries.
parameters.subject StringString Chaîne contenant l’objet du message.A string containing the subject of the message. La chaîne est limitée à 255 caractères maximum.The string is limited to a maximum of 255 characters.
parameters.htmlBody StringString Corps du message HTML.The HTML body of the message. La taille du corps du message est limitée à 32 Ko.The body content is limited to a maximum size of 32 KB.
parameters.attachments Array.<Object>Array.<Object> Tableau d’objets JSON qui sont des pièces jointes de fichier ou d’élément.An array of JSON objects that are either file or item attachments.
parameters.attachments.type StringString Indique le type de pièce jointe. Doit être file pour une pièce jointe de fichier ou item pour une pièce jointe d’élément.Indicates the type of attachment. Must be file for a file attachment or item for an item attachment.
parameters.attachments.name StringString Chaîne qui contient le nom de la pièce jointe et comporte jusqu'à 255 caractères.A string that contains the name of the attachment, up to 255 characters in length.
parameters.attachments.url StringString Utilisé uniquement si type est défini sur file. Il s’agit de l’URI de l’emplacement du fichier.Only used if type is set to file. The URI of the location for the file.
parameters.attachments.isInline BooleanBoolean Utilisé uniquement si type est défini sur file. Si elle est définie sur true, cette valeur indique que la pièce jointe est incorporée dans le corps du message et qu’elle ne doit pas figurer dans la liste des pièces jointes.Only used if type is set to file. If true, indicates that the attachment will be shown inline in the message body, and should not be displayed in the attachment list.
parameters.attachments.itemId StringString Utilisé uniquement si type est défini sur item.Only used if type is set to item. ID d’élément EWS du courrier électronique existant à joindre au nouveau message.The EWS item id of the existing e-mail you want to attach to the new message. Il s’agit d’une chaîne comportant un maximum de 100 caractères.This is a string up to 100 characters.
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1.61.6
Niveau d’autorisation minimalMinimum permission level ReadItemReadItem
Mode Outlook applicableApplicable Outlook mode LectureRead
ExempleExample
Office.context.mailbox.displayNewMessageForm(
  {
    toRecipients: Office.context.mailbox.item.to, // Copy the To line from current item
    ccRecipients: ['sam@contoso.com'],
    subject: 'Outlook add-ins are cool!',
    htmlBody: 'Hello <b>World</b>!<br/><img src="cid:image.png"></i>',
    attachments: [
      {
        type: 'file',
        name: 'image.png',
        url: 'http://contoso.com/image.png',
        isInline: true
      }
    ]
  });

getCallbackTokenAsync([options], callback)getCallbackTokenAsync([options], callback)

Obtient une chaîne contenant un jeton utilisé pour appeler les API REST ou les services web Exchange.Gets a string that contains a token used to call REST APIs or Exchange Web Services.

La méthode getCallbackTokenAsync émet un appel asynchrone pour obtenir un jeton opaque à partir du serveur Exchange qui héberge la boîte aux lettres de l’utilisateur. La durée de vie du jeton de rappel est de 5 minutes.The getCallbackTokenAsync method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. The lifetime of the callback token is 5 minutes.

Note

Les compléments devraient, dans la mesure du possible, utiliser les API REST à la place des services web Exchange.It is recommended that add-ins use the REST APIs instead of Exchange Web Services whenever possible.

Jetons RESTREST Tokens

Quand un jeton REST est demandé (options.isRest = true), le jeton fourni ne permet pas d’authentifier les appels des services web Exchange. Le jeton peut uniquement accéder en lecture seule à l’élément actif et à ses pièces jointes, sauf si l’autorisation ReadWriteMailbox est spécifiée dans le manifeste du complément. Si l’autorisation ReadWriteMailbox est spécifiée, le jeton fourni accorde un accès en lecture/écriture au courrier, au calendrier et aux contacts, ainsi que la possibilité d’envoyer des messages.When a REST token is requested (options.isRest = true), the resulting token will not work to authenticate Exchange Web Services calls. The token will be limited in scope to read-only access to the current item and its attachments, unless the add-in has specified the ReadWriteMailbox permission in its manifest. If the ReadWriteMailbox permission is specified, the resulting token will grant read/write access to mail, calendar, and contacts, including the ability to send mail.

Le complément doit utiliser la propriété restUrl pour déterminer l’URL à utiliser pendant les appels de l’API REST.The add-in should use the restUrl property to determine the correct URL to use when making REST API calls.

Jetons EWSEWS Tokens

Quand un jeton EWS est demandé (options.isRest = false), le jeton fourni ne permet pas d’authentifier les appels de l’API REST. Le jeton peut uniquement accéder à l’élément actif.When an EWS token is requested (options.isRest = false), the resulting token will not work to authenticate REST API calls. The token will be limited in scope to accessing the current item.

Le complément doit utiliser la propriété ewsUrl pour déterminer l’URL à utiliser pendant les appels EWS.The add-in should use the ewsUrl property to determine the correct URL to use when making EWS calls.

Paramètres :Parameters:
NomName TypeType AttributsAttributes DescriptionDescription
options ObjetObject <optional><optional> Littéral d’objet contenant une ou plusieurs des propriétés suivantes.An object literal that contains one or more of the following properties.
options.isRest BooleanBoolean <optional><optional> Détermine si le jeton fourni est utilisé pour les API REST Outlook ou les services web Exchange. La valeur par défaut est false.Determines if the token provided will be used for the Outlook REST APIs or Exchange Web Services. Default value is false.
options.asyncContext ObjetObject <optional><optional> Données d’état transmises à la méthode asynchrone.Any state data that is passed to the asynchronous method.
callback fonctionfunction Une fois la méthode exécutée, la fonction transmise au paramètre callback est appelée avec un seul paramètre, asyncResult, qui est un objet AsyncResult. Le jeton est fourni sous forme de chaîne dans la propriété asyncResult.value.When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. The token is provided as a string in the asyncResult.value property.
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1,51.5
Niveau d’autorisation minimalMinimum permission level ReadItemReadItem
Mode Outlook applicableApplicable Outlook mode Composition et lectureCompose and read
ExempleExample
function getCallbackToken() {
  var options = {
    isRest: true,
    asyncContext: { message: 'Hello World!' }
  };

  Office.context.mailbox.getCallbackTokenAsync(options, cb);
}

function cb(asyncResult) {
  var token = asyncResult.value;
}

getCallbackTokenAsync(callback, [userContext])getCallbackTokenAsync(callback, [userContext])

Obtient une chaîne qui contient un jeton servant à obtenir une pièce jointe ou un élément à partir d’un serveur Exchange.Gets a string that contains a token used to get an attachment or item from an Exchange Server.

La méthode getCallbackTokenAsync émet un appel asynchrone pour obtenir un jeton opaque à partir du serveur Exchange qui héberge la boîte aux lettres de l’utilisateur. La durée de vie du jeton de rappel est de 5 minutes.The getCallbackTokenAsync method makes an asynchronous call to get an opaque token from the Exchange Server that hosts the user's mailbox. The lifetime of the callback token is 5 minutes.

Vous pouvez passer le jeton et un identificateur de pièce jointe ou d’élément à un système tiers. Celui-ci utilise le jeton en tant que jeton d’autorisation de support pour appeler l’opération GetAttachment ou GetItem des services web Exchange (EWS) afin de retourner une pièce jointe ou un élément. Par exemple, vous pouvez créer un service distant pour obtenir des pièces jointes à partir de l’élément sélectionné.You can pass the token and an attachment identifier or item identifier to a third-party system. The third-party system uses the token as a bearer authorization token to call the Exchange Web Services (EWS) GetAttachment or GetItem operation to return an attachment or item. For example, you can create a remote service to get attachments from the selected item.

Votre application doit disposer de l’autorisation ReadItem spécifiée dans son manifeste pour pouvoir appeler la méthode getCallbackTokenAsync en mode de lecture.Your app must have the ReadItem permission specified in its manifest to call the getCallbackTokenAsync method in read mode.

En mode composition, vous devez appeler la méthode saveAsync permettant d’obtenir un identificateur de l’élément à transmettre à la méthode getCallbackTokenAsync. Votre application doit disposer des autorisations ReadWriteItem pour appeler la méthode saveAsync.In compose mode you must call the saveAsync method to get an item identifier to pass to the getCallbackTokenAsync method. Your app must have ReadWriteItem permissions to call the saveAsync method.

Paramètres :Parameters:
NomName TypeType AttributsAttributes DescriptionDescription
callback functionfunction Une fois la méthode exécutée, la fonction transmise au paramètre callback est appelée avec un seul paramètre, asyncResult, qui est un objet AsyncResult. Le jeton est fourni sous forme de chaîne dans la propriété asyncResult.value.When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object. The token is provided as a string in the asyncResult.value property.
userContext ObjetObject <optional><optional> Données d’état transmises à la méthode asynchrone.Any state data that is passed to the asynchronous method.
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1.31.3
Niveau d’autorisation minimalMinimum permission level ReadItemReadItem
Mode Outlook applicableApplicable Outlook mode Composition et lectureCompose and read
ExempleExample
function getCallbackToken() {
  Office.context.mailbox.getCallbackTokenAsync(cb);
}

function cb(asyncResult) {
  var token = asyncResult.value;
}

getUserIdentityTokenAsync(callback, [userContext])getUserIdentityTokenAsync(callback, [userContext])

Obtient un jeton qui identifie l’utilisateur et le complément Office.Gets a token identifying the user and the Office Add-in.

La méthode getUserIdentityTokenAsync renvoie un jeton qui vous permet d’identifier et d’authentifier le complément et l’utilisateur à l’aide d’un système tiers.The getUserIdentityTokenAsync method returns a token that you can use to identify and authenticate the add-in and user with a third-party system.

Paramètres :Parameters:
NomName TypeType AttributsAttributes DescriptionDescription
callback functionfunction Une fois la méthode exécutée, la fonction transmise au paramètre callback est appelée avec un seul paramètre, asyncResult, qui est un objet AsyncResult.When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object.

Le jeton est fourni sous forme de chaîne dans la propriété asyncResult.value.The token is provided as a string in the asyncResult.value property.
userContext ObjectObject <optional><optional> Données d’état transmises à la méthode asynchrone.Any state data that is passed to the asynchronous method.
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1.01.0
Niveau d’autorisation minimalMinimum permission level ReadItemReadItem
Mode Outlook applicableApplicable Outlook mode Composition ou lectureCompose or read
ExempleExample
function getIdentityToken() {
  Office.context.mailbox.getUserIdentityTokenAsync(cb);
}

function cb(asyncResult) {
  var token = asyncResult.value;
}

makeEwsRequestAsync(data, callback, [userContext])makeEwsRequestAsync(data, callback, [userContext])

Envoie une demande asynchrone à un des services web Exchange (EWS) sur le serveur Exchange qui héberge la boîte aux lettres de l’utilisateur.Makes an asynchronous request to an Exchange Web Services (EWS) service on the Exchange server that hosts the user’s mailbox.

Note

Cette méthode n’est pas prise en charge dans les cas suivants :This method is not supported in the following scenarios.

  • dans Outlook pour iOS ou Outlook pour Android ;In Outlook for iOS or Outlook for Android
  • quand le complément est chargé dans une boîte aux lettres Gmail.When the add-in is loaded in a Gmail mailbox

Dans ces cas de figure, les compléments doivent utiliser les API REST pour accéder à la boîte aux lettres de l’utilisateur.In these cases, add-ins should use REST APIs to access the user's mailbox instead.

La méthode makeEwsRequestAsync envoie une demande EWS à Exchange de la part du complément.The makeEwsRequestAsync method sends an EWS request on behalf of the add-in to Exchange. Pour obtenir la liste des opérations EWS prises en charge, reportez-vous à l’article Appeler des services web à partir d’un complément Outlook.See Call web services from an Outlook add-in for a list of the supported EWS operations.

Vous ne pouvez pas demander des éléments associés à un dossier avec la méthode makeEwsRequestAsync.You cannot request Folder Associated Items with the makeEwsRequestAsync method.

La demande XML doit spécifier l’encodage UTF-8.The XML request must specify UTF-8 encoding.

<?xml version="1.0" encoding="utf-8"?>

Votre complément doit disposer de l’autorisation ReadWriteMailbox pour utiliser la méthode makeEwsRequestAsync. Pour plus d’informations sur l’utilisation de l’autorisation ReadWriteMailbox et des opérations EWS que vous pouvez appeler avec la méthode makeEwsRequestAsync, consultez la page relative aux autorisations du complément de messagerie pour accéder à la boîte aux lettres de l’utilisateur.Your add-in must have the ReadWriteMailbox permission to use the makeEwsRequestAsync method. For information about using the ReadWriteMailbox permission and the EWS operations that you can call with the makeEwsRequestAsync method, see Specify permissions for mail add-in access to the user's mailbox.

Note

L’administrateur serveur doit définir OAuthAuthentication sur true dans le répertoire EWS du serveur d’accès client pour permettre à la méthode makeEwsRequestAsync d’effectuer des demandes EWS.The server administrator must set OAuthAuthentication to true on the Client Access Server EWS directory to enable the makeEwsRequestAsync method to make EWS requests.

Différences entre les versionsVersion differences

Lorsque vous utilisez la méthode makeEwsRequestAsync dans les applications de messagerie exécutées dans des versions d’Outlook inférieures à 15.0.4535.1004, vous devez définir la valeur d’encodage sur ISO-8859-1.When you use the makeEwsRequestAsync method in mail apps running in Outlook versions earlier than version 15.0.4535.1004, you should set the encoding value to ISO-8859-1.

<?xml version="1.0" encoding="iso-8859-1"?>

Lorsque votre application de messagerie s’exécute dans Outlook sur le web, vous n’avez pas à définir la valeur d’encodage. Pour déterminer si votre application de messagerie s’exécute dans Outlook ou Outlook sur le web, utilisez la propriété mailbox.diagnostics.hostName. Pour déterminer la version d’Outlook qui est exécutée, utilisez la propriété mailbox.diagnostics.hostVersion.You do not need to set the encoding value when your mail app is running in Outlook on the web. You can determine whether your mail app is running in Outlook or Outlook on the web by using the mailbox.diagnostics.hostName property. You can determine what version of Outlook is running by using the mailbox.diagnostics.hostVersion property.

Paramètres :Parameters:
NomName TypeType AttributsAttributes DescriptionDescription
data StringString Demande EWS.The EWS request.
callback functionfunction Une fois la méthode exécutée, la fonction transmise au paramètre callback est appelée avec un seul paramètre, asyncResult, qui est un objet AsyncResult.When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object.

Le résultat XML de l’appel EWS est fourni sous forme de chaîne dans la propriété asyncResult.value.The XML result of the EWS call is provided as a string in the asyncResult.value property. Si la taille du résultat est supérieure à 1 Mo, un message d’erreur est renvoyé.If the result exceeds 1 MB in size, an error message is returned instead.
userContext ObjetObject <optional><optional> Données d’état transmises à la méthode asynchrone.Any state data that is passed to the asynchronous method.
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1.01.0
Niveau d’autorisation minimalMinimum permission level ReadWriteMailboxReadWriteMailbox
Mode Outlook applicableApplicable Outlook mode Composition ou lectureCompose or read
ExempleExample

L’exemple suivant appelle la méthode makeEwsRequestAsync pour utiliser l’opération GetItem pour obtenir l’objet d’un élément.The following example calls makeEwsRequestAsync to use the GetItem operation to get the subject of an item.

function getSubjectRequest(id) {
   // Return a GetItem operation request for the subject of the specified item.
   var request =
    '<?xml version="1.0" encoding="utf-8"?>' +
    '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"' +
    '               xmlns:xsd="http://www.w3.org/2001/XMLSchema"' +
    '               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"' +
    '               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">' +
    '  <soap:Header>' +
    '    <RequestServerVersion Version="Exchange2013" xmlns="http://schemas.microsoft.com/exchange/services/2006/types" soap:mustUnderstand="0" />' +
    '  </soap:Header>' +
    '  <soap:Body>' +
    '    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">' +
    '      <ItemShape>' +
    '        <t:BaseShape>IdOnly</t:BaseShape>' +
    '        <t:AdditionalProperties>' +
    '            <t:FieldURI FieldURI="item:Subject"/>' +
    '        </t:AdditionalProperties>' +
    '      </ItemShape>' +
    '      <ItemIds><t:ItemId Id="' + id + '"/></ItemIds>' +
    '    </GetItem>' +
    '  </soap:Body>' +
    '</soap:Envelope>';

   return request;
}

function sendRequest() {
   // Create a local variable that contains the mailbox.
   Office.context.mailbox.makeEwsRequestAsync(
    getSubjectRequest(mailbox.item.itemId), callback);
}

function callback(asyncResult)  {
   var result = asyncResult.value;
   var context = asyncResult.asyncContext;

   // Process the returned response here.
}

removeHandlerAsync(eventType, handler, [options], [callback])removeHandlerAsync(eventType, handler, [options], [callback])

Retire un gestionnaire d’événements pour un événement pris en charge.Removes an event handler for a supported event.

Actuellement, seul le type d’événement Office.EventType.ItemChanged est pris en charge.Currently, the only supported event type is Office.EventType.ItemChanged.

Paramètres :Parameters:
NomName TypeType AttributsAttributes DescriptionDescription
eventType Office.EventTypeOffice.EventType Événement qui doit révoquer le gestionnaire.The event that should revoke the handler.
handler FonctionFunction Fonction qui gère l’événement. Cette fonction doit accepter un seul paramètre, qui est un littéral d’objet. La propriété type sur le paramètre correspond au paramètre eventType transmis à addHandlerAsync.The function to handle the event. The function must accept a single parameter, which is an object literal. The type property on the parameter will match the eventType parameter passed to addHandlerAsync.
options ObjetObject <optional><optional> Littéral d’objet contenant une ou plusieurs des propriétés suivantes.An object literal that contains one or more of the following properties.
options.asyncContext ObjetObject <optional><optional> Les développeurs peuvent indiquer un objet auquel ils souhaitent accéder dans la méthode de rappel.Developers can provide any object they wish to access in the callback method.
callback fonctionfunction <optional><optional> Une fois la méthode exécutée, la fonction transmise au paramètre callback est appelée avec un seul paramètre, asyncResult, qui est un objet AsyncResult.When the method completes, the function passed in the callback parameter is called with a single parameter, asyncResult, which is an AsyncResult object.
Configuration requiseRequirements
Conditions requisesRequirement ValeurValue
Version de l’ensemble minimal de conditions de boîte aux lettresMinimum mailbox requirement set version 1,51.5
Niveau d’autorisation minimalMinimum permission level ReadItemReadItem
Mode Outlook applicableApplicable Outlook mode Composition ou lectureCompose or read