mailboxmailbox

Office.context. mailboxOffice.context. mailbox

Donne accès 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.

Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la boîte aux lettresMinimum mailbox requirement set version 1.01.0
Niveau d’autorisation minimalMinimum permission level RestreintRestricted
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

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 par Outlook pour iOS ou Outlook pour Android.Note: 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 effectuer des appels EWS vers la boîte aux lettres de l’utilisateur. Par exemple, vous pouvez créer un service distant pour obtenir les pièces jointes 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.

L’autorisation ReadItem doit être spécifiée dans le manifeste de votre application pour appeler le membre ewsUrl en mode 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
Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la 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 courrier.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
Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la 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.

Pour le moment, les types d’événements pris en charge sont Office.EventType.ItemChanged et Office.EventType.OfficeThemeChanged.Currently the supported event types are Office.EventType.ItemChanged, , and Office.EventType.OfficeThemeChanged

Paramètres :Parameters:
NomName TypeType AttributsAttributes DescriptionDescription
eventType Office.EventTypeOffice.EventType L’événement qui doit invoquer le gestionnaire.The event that should invoke the handler.
handler FonctionFunction La fonction permettant de gérer 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 <facultatif><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 <facultatif><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 <facultatif><optional> Quand la méthode se termine, la fonction passée dans le 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.
Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la 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.Note: This method is not supported in Outlook for iOS or Outlook for Android.

Les ID d’éléments 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 Un 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.
Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la boîte aux lettresMinimum mailbox requirement set version 1.31.3
Niveau d’autorisation minimalMinimum permission level RestreintRestricted
Mode Outlook applicableApplicable Outlook mode Composition ou lectureCompose or read
Retourne :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 des 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 client, 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 de telle sorte que les valeurs que vous affichez sur l’interface utilisateur soient toujours cohérentes avec le fuseau horaire auquel l’utilisateur s'attend.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 s'exécute dans Outlook, la méthode convertToLocalClientTime retournera un objet dictionnaire dont les valeurs seront définies pour le fuseau horaire de l’ordinateur client. Si l’application de messagerie s’exécute dans Outlook Web App, la méthode convertToLocalClientTime retournera un objet dictionnaire dont les valeurs seront 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 Un objet DateA Date object
Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la 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
Retourne :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.Note: This method is not supported in Outlook for iOS or Outlook for Android.

Les ID d’éléments récupérés via EWS ou via 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 dans un format adapté à 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 Un 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.
Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la boîte aux lettresMinimum mailbox requirement set version 1.31.3
Niveau d’autorisation minimalMinimum permission level RestreintRestricted
Mode Outlook applicableApplicable Outlook mode Composition ou lectureCompose or read
Retourne :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 correctes 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 en heure locale à convertir.The local time value to convert.
Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la 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
Retourne :Returns:

Un objet Date avec l’heure exprimée en 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.Note: This method is not supported in Outlook for iOS or Outlook for Android.

La méthode displayAppointmentForm ouvre un rendez-vous de calendrier existant dans une nouvelle fenêtre sur le bureau ou dans une boîte de dialogue sur les équipements 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. Cela est dû au fait que, dans Outlook pour Mac, vous ne pouvez pas accéder aux propriétés (y compris 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é seulement si le corps du formulaire comprend un nombre de caractères inférieur ou égal à 32 Ko.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 d’élément indiqué n’identifie pas un rendez-vous existant, un volet vierge s’ouvre sur l’ordinateur ou l’appareil client, et 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 L'identificateur EWS (services web Exchange) pour un rendez-vous de calendrier existant.The Exchange Web Services (EWS) identifier for an existing calendar appointment.
Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la 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.Note: 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 sur le 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 n’ouvre le formulaire indiqué que si le corps du formulaire comprend un nombre de caractères inférieur ou égal à 32 Ko.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 d’élément indiqué n’identifie pas un message existant, aucun message ne sera affiché sur l’ordinateur client, et aucun message d’erreur ne sera 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 avec un itemId qui représente un rendez-vous. Utilisez la méthode displayAppointmentForm pour afficher un rendez-vous existant, et displayNewAppointmentForm pour afficher un formulaire pour 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 EWS (services web Exchange) pour un message existant.The Exchange Web Services (EWS) identifier for an existing message.
Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la 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 pour créer un rendez-vous de 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.Note: 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 fournis, les champs du formulaire de rendez-vous sont automatiquement remplis 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 appareils, cette méthode affiche toujours un formulaire avec un champ participants. Si vous n'indiquez aucun participant dans les arguments d’entrée, la méthode affiche un formulaire avec un bouton Enregistrer. Si vous avez indiqué des participants, le formulaire inclura les participants et un 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 les paramètres requiredAttendees, optionalAttendees, ou resources, cette méthode affiche un formulaire de réunion avec un bouton Envoyer. Si vous ne n'indiquez 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 de taille indiquées, ou si un nom de paramètre inconnu est indiqué, 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.Note: All parameters are optional.

NomName TypeType DescriptionDescription
parameters ObjetObject Un 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>
parameters.optionalAttendees Array.<String> Array.<EmailAddressDetails>Array.<String> | Array.<EmailAddressDetails>
parameters.start DateDate Un objet Date indiquant la date et l’heure du début du rendez-vous.A Date object specifying the start date and time of the appointment.
parameters.end DateDate Un objet Date indiquant la date et l’heure de la fin du rendez-vous.A Date object specifying the end date and time of the appointment.
parameters.location StringString Une chaîne contenant le lieu du rendez-vous. La chaîne est limitée à un maximum de 255 caractères.A string containing the location of the appointment. The string is limited to a maximum of 255 characters.
parameters.resources Array.<String>Array.<String> Un tableau de chaînes contenant les ressources requises pour le rendez-vous. Le tableau est limité à un maximum de 100 entrées.An array of strings containing the resources required for the appointment. The array is limited to a maximum of 100 entries.
parameters.subject StringString Une chaîne contenant l’objet du rendez-vous. La chaîne est limitée à un maximum de 255 caractères.A string containing the subject of the appointment. The string is limited to a maximum of 255 characters.
parameters.body StringString Le corps du rendez-vous. Le contenu du corps est limité à une taille maximale de 32 Ko.The body of the appointment. The body content is limited to a maximum size of 32 KB.
Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la 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 nouveau message.Displays a form for creating a new message.

La méthode displayNewMessageForm ouvre un formulaire qui permet à l’utilisateur de créer un nouveau 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 de taille indiquées, ou si un nom de paramètre inconnu est indiqué, 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.Note: 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>
parameters.ccRecipients Array.<String> Array.<EmailAddressDetails>Array.<String> | Array.<EmailAddressDetails>
parameters.bccRecipients Array.<String> Array.<EmailAddressDetails>Array.<String> | Array.<EmailAddressDetails>
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 HTML du message.The HTML body of the message. Le contenu du corps du message est limitée à une taille maximum de 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, d’une longueur maximale de 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 incluse 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. L’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.
Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la boîte aux lettresMinimum mailbox requirement set version 1.6-16
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 effectue un appel asynchrone pour obtenir un jeton opaque à partir de l’Exchange Server 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 doivent, dans la mesure du possible, utiliser les API REST plutôt que les services Web Exchange.Note: 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 seulement accéder à l’élément actif et à ses pièces jointes en lecture seule, 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

Lorsque un jeton EWS est demandé (options.isRest = false), le jeton fourni ne permet pas d’authentifier les appels de l’API REST. Le jeton à une étendue limitée à l’accès à 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 <facultatif><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 BooléenBoolean <facultatif><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 <facultatif><optional> Toute donnée d'état qui est passée à 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.
Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la 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 utilisé pour obtenir une pièce jointe ou un élément à partir d’un Exchange Server.Gets a string that contains a token used to get an attachment or item from an Exchange Server.

La méthode getCallbackTokenAsync effectue un appel asynchrone pour obtenir un jeton opaque à partir du Exchange Server 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 transmettre le jeton et un identificateur de pièce jointe ou un identificateur d’élément à un système tiers. Le système tiers utilise le jeton comme jeton d’autorisation au porteur pour appeler l’opération GetAttachment ou GetItem des services Web Exchange, pour 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 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 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.
userContext ObjetObject <facultatif><optional> Toute donnée d’état qui est passée à la méthode asynchrone.Any state data that is passed to the asynchronous method.
Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la 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 identifiant l’utilisateur et le complément Office.Gets a token identifying the user and the Office Add-in.

La méthode getUserIdentityTokenAsync retourne un jeton que vous pouvez utiliser pour identifier et authentifier le complément et l’utilisateur avec un système de 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 fonctionfunction Quand la méthode se termine, la fonction passée dans le 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 la forme d’une chaîne dans la propriété asyncResult.value.The token is provided as a string in the asyncResult.value property.
userContext ObjetObject <facultatif><optional> Toute donnée d’état qui est passée à la méthode asynchrone.Any state data that is passed to the asynchronous method.
Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la 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])

Effectue une demande asynchrone à un service Exchange Web Services (EWS) sur l'Exchange Server 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 scénarios suivants.This method is not supported in the following scenarios.

  • Dans Outlook pour iOS ou Outlook pour AndroidIn Outlook for iOS or Outlook for Android
  • Lorsque le complément est chargé dans une boîte aux lettres GmailWhen the add-in is loaded in a Gmail mailbox

Dans ces cas, les compléments doivent plutôt utiliser des 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 une liste des opérations EWS prises en charge, voir Appeler des services web depuis 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 les éléments associés au 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 sur les opérations EWS que vous pouvez appeler avec la méthode makeEwsRequestAsync, voir la page Indiquer des autorisations pour l'accès du complément de messagerie à 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 du serveur doit définir OAuthAuthentication à true dans le dossier EWS du serveur d’accès client, pour permettre à la méthode makeEwsRequestAsync d’effectuer des demandes EWS.NOTE: 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 versionsVersion differences

Lorsque vous utilisez la méthode makeEwsRequestAsync dans les applications de messagerie s'exécutant dans des versions d’Outlook antérieures à la version 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"?>

Vous n’avez pas besoin de définir la valeur d’encodage quand votre application de messagerie s’exécute dans Outlook sur le Web. Vous pouvez déterminer si votre application de messagerie s’exécute dans Outlook ou Outlook sur le Web en utilisant la propriété mailbox.diagnostics.hostName. Vous pouvez déterminer quelle version d’Outlook est exécutée en utilisant 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 La demande EWS.The EWS request.
callback fonctionfunction Quand la méthode se termine, la fonction passée dans le 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 comme une 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 le résultat dépasse une taille de 1 Mo, un message d’erreur est renvoyé.If the result exceeds 1 MB in size, an error message is returned instead.
userContext ObjetObject <facultatif><optional> Toute donnée d’état qui est passée à la méthode asynchrone.Any state data that is passed to the asynchronous method.
Conditions requisesRequirements
Condition requiseRequirement ValeurValue
Version minimale de la 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 makeEwsRequestAsync pour utiliser l’opération GetItem et 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.
}