Office. Mailbox interface

MessageCompose, MessageRead, AppointmentCompose, AppointmentRead

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

Important:

Votre application doit disposer de l’autorisation d’élément de lecture spécifiée dans son manifeste pour appeler le ewsUrl membre en mode lecture.
En mode composition, vous devez appeler la saveAsync méthode avant de pouvoir utiliser le ewsUrl membre . Votre application doit disposer d’autorisations d’élément en lecture/écriture pour appeler la saveAsync méthode .
Cette propriété n’est pas prise en charge dans Outlook sur Android ou sur iOS. Pour plus d’informations sur les API prises en charge dans Outlook Mobile, consultez API JavaScript Outlook prises en charge dans Outlook sur les appareils mobiles.
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é.

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml

console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

item

Élément de boîte aux lettres. Selon le contexte dans lequel le complément s’est ouvert, le type d’élément peut varier. Si vous souhaitez voir IntelliSense uniquement pour un type ou un mode spécifique, convertissez cet élément en l’un des éléments suivants :

Important : item peut avoir la valeur Null si votre complément prend en charge l’épinglage du volet Office. Pour plus d’informations sur la façon de gérer, voir Implémenter un volet Office épinglé dans Outlook.

item?: Item & ItemCompose & ItemRead & Message & MessageCompose & MessageRead & Appointment & AppointmentCompose & AppointmentRead;

Valeur de propriété

Office.Item & Office.ItemCompose & Office.ItemRead & Office.Message & Office.MessageCompose & Office.MessageRead & Office.Appointment & Office.AppointmentCompose & Office.AppointmentRead

masterCategories

Obtient un objet qui fournit des méthodes pour gérer les catégories master liste associée à une boîte aux lettres.

masterCategories: MasterCategories;

Valeur de propriété

Office.MasterCategories

Remarques

[ Ensemble d’API : Boîte aux lettres 1.8 ]

Niveau d’autorisation minimal : boîte aux lettres en lecture/écriture

Mode Outlook applicable : Rédiger ou Lire

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-master-categories.yaml

Office.context.mailbox.masterCategories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const categories = asyncResult.value;
    if (categories && categories.length > 0) {
      console.log("Master categories:");
      console.log(JSON.stringify(categories));
    } else {
      console.log("There are no categories in the master list.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

const masterCategoriesToAdd = [
  {
    displayName: "TestCategory",
    color: Office.MailboxEnums.CategoryColor.Preset0
  }
];

Office.context.mailbox.masterCategories.addAsync(masterCategoriesToAdd, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully added categories to master list");
  } else {
    console.log("masterCategories.addAsync call failed with error: " + asyncResult.error.message);
  }
});

...

const masterCategoriesToRemove = ["TestCategory"];

Office.context.mailbox.masterCategories.removeAsync(masterCategoriesToRemove, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully removed categories from master list");
  } else {
    console.log("masterCategories.removeAsync call failed with error: " + asyncResult.error.message);
  }
});

restUrl

obtient l’URL du point de terminaison REST de ce compte de messagerie.

Votre application doit disposer de l’autorisation d’élément de lecture spécifiée dans son manifeste pour appeler le restUrl membre en mode lecture.

En mode composition, vous devez appeler la méthode saveAsync avant de pouvoir utiliser le membre restUrl. Votre application doit disposer d’autorisations d’élément en lecture/écriture pour appeler la saveAsync méthode .

Toutefois, dans les scénarios délégués ou partagés, vous devez utiliser plutôt la targetRestUrl propriété de l’objet SharedProperties (introduite dans l’ensemble de conditions requises 1.8). Pour plus d’informations, consultez l’article Dossiers partagés et boîte aux lettres partagées .

restUrl: string;

Valeur de propriété

string

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

La valeur restUrl peut être utilisée pour que l’API REST appelle la boîte aux lettres de l’utilisateur.

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/basic-rest-cors.yaml

Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function (result) {
    const ewsId = Office.context.mailbox.item.itemId;
    const token = result.value;
    const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
    const getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
            
    const xhr = new XMLHttpRequest();
    xhr.open('GET', getMessageUrl);
    xhr.setRequestHeader("Authorization", "Bearer " + token);
    xhr.onload = function (e) {
        console.log(this.response);
    }
    xhr.send();
});

...

console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

userProfile

Informations sur l’utilisateur associé à la boîte aux lettres. Cela inclut le type de compte, le nom d’affichage, l’adresse e-mail et le fuseau horaire.

Pour plus d’informations, consultez Office.UserProfile.

userProfile: UserProfile;

Valeur de propriété

Office.UserProfile

Détails de la méthode

addHandlerAsync(eventType, handler, options, callback)

ajoute un gestionnaire d’événements pour un événement pris en charge. Remarque : les événements sont disponibles uniquement avec l’implémentation du volet Office.

Pour les événements pris en charge, reportez-vous à la section Événements du modèle objet boîte aux lettres.

addHandlerAsync(eventType: Office.EventType | string, handler: any, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Paramètres

eventType: Office.EventType | string

Événement qui doit appeler le gestionnaire.

handler: any

Fonction qui gère l’événement. Cette fonction doit accepter un seul paramètre, qui est un littéral d’objet. La type propriété sur le paramètre correspond au eventType paramètre passé à addHandlerAsync.

options: Office.AsyncContextOptions

Fournit une option permettant de conserver les données de contexte de tout type, inchangées, pour une utilisation dans un rappel.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre de type Office.AsyncResult.

Retours

void

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

Exemples

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) {
    const item = Office.context.mailbox.item;

    // Check that item is not null.
    if (item !== null) {
        // Work with item, e.g., define and call function that
        // loads the properties of the newly selected item.
        loadProps(item);
    }
}

addHandlerAsync(eventType, handler, callback)

ajoute un gestionnaire d’événements pour un événement pris en charge. Remarque : les événements sont disponibles uniquement avec l’implémentation du volet Office.

Pour les événements pris en charge, reportez-vous à la section Événements du modèle objet boîte aux lettres.

addHandlerAsync(eventType: Office.EventType | string, handler: any, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Paramètres

eventType: Office.EventType | string

Événement qui doit appeler le gestionnaire.

handler: any

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre de type Office.AsyncResult.

Retours

void

Remarques

[ Ensemble d’API : Boîte aux lettres 1.3 ]

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

convertToEwsId(id, restVersion)

Convertit un ID pris en charge au format EWS (Exchange Web Services).

convertToEwsId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

Paramètres

id: string

ID à convertir au format EWS. Cette chaîne peut être un ID d’élément mis en forme pour les API REST Outlook ou un ID de conversation récupéré à partir de Office.context.mailbox.item.conversationId.

restVersion: Office.MailboxEnums.RestVersion | string

Valeur indiquant la version de l’API REST Outlook utilisée pour récupérer l’ID d’élément.

Retours

string

Remarques

Niveau d’autorisation minimal : restreint

Mode Outlook applicable : Rédiger ou Lire

Important:

Cette méthode n’est pas prise en charge dans Outlook sur Android ou sur iOS. Pour plus d’informations sur les API prises en charge dans Outlook Mobile, consultez API JavaScript Outlook prises en charge dans Outlook sur les appareils mobiles.
Les ID d’élément récupérés via une API REST (telle que l’API de messagerie Outlook ou Microsoft Graph) utilisent un format différent de celui utilisé par EWS. La méthode convertToEwsId convertit un ID mis en forme pour REST au format approprié pour EWS.

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml

console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToLocalClientTime(timeValue)

Obtient un dictionnaire contenant les informations d’heure dans l’heure locale du client.

Les dates et heures utilisées par une application de messagerie pour les clients Outlook sur le web ou de bureau peuvent utiliser différents fuseaux horaires. Outlook utilise le fuseau horaire de l’ordinateur client ; Outlook sur le web utilise le fuseau horaire défini sur le Centre Administration Exchange (EAC). 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.

Si l’application de messagerie s’exécute dans Outlook sur des clients de bureau, la convertToLocalClientTime méthode renvoie un objet de dictionnaire avec les valeurs définies sur le fuseau horaire de l’ordinateur client. Si l’application de messagerie s’exécute dans Outlook sur le web, la convertToLocalClientTime méthode renvoie un objet dictionnaire avec les valeurs définies sur le fuseau horaire spécifié dans le CENTRE d’administration Exchange.

convertToLocalClientTime(timeValue: Date): LocalClientTime;

Paramètres

timeValue: Date

Objet Date.

Retours

Office.LocalClientTime

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

convertToRestId(id, restVersion)

Convertit un ID pris en charge au format REST.

convertToRestId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

Paramètres

id: string

ID à convertir au format REST. Cette chaîne peut être un ID d’élément mis en forme pour EWS qui est généralement récupéré à partir de Office.context.mailbox.item.itemId, d’un ID de conversation récupéré à partir deOffice.context.mailbox.item.conversationId ou d’un ID de série récupéré à partir deOffice.context.mailbox.item.seriesId .

restVersion: Office.MailboxEnums.RestVersion | string

Valeur indiquant la version de l’API REST Outlook utilisée avec l’ID converti.

Retours

string

Remarques

[ Ensemble d’API : Boîte aux lettres 1.3 ]

Niveau d’autorisation minimal : restreint

Mode Outlook applicable : Rédiger ou Lire

Important:

Cette méthode n’est pas prise en charge dans Outlook sur Android ou sur iOS. Pour plus d’informations sur les API prises en charge dans Outlook Mobile, consultez API JavaScript Outlook prises en charge dans Outlook sur les appareils mobiles.
Les ID d’élément récupérés via les services Web Exchange (EWS) ou via la itemId propriété utilisent un format différent de celui utilisé par les API REST (telles que l’API de messagerie Outlook ou Microsoft Graph). La méthode convertToRestId convertit un ID mis en forme pour EWS au format approprié pour REST.

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/basic-rest-cors.yaml

Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function (result) {
    const ewsId = Office.context.mailbox.item.itemId;
    const token = result.value;
    const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
    const getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
            
    const xhr = new XMLHttpRequest();
    xhr.open('GET', getMessageUrl);
    xhr.setRequestHeader("Authorization", "Bearer " + token);
    xhr.onload = function (e) {
        console.log(this.response);
    }
    xhr.send();
});

...

console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToUtcClientTime(input)

Obtient un Date objet à partir d’un dictionnaire contenant des informations d’heure.

La convertToUtcClientTime méthode convertit un dictionnaire contenant une date et une heure locales en objet Date avec les valeurs correctes pour la date et l’heure locales.

convertToUtcClientTime(input: LocalClientTime): Date;

Paramètres

input: Office.LocalClientTime

Valeur de l’heure locale à convertir.

Retours

Date

Objet Date avec l’heure exprimée au format UTC.

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

Exemples

// Represents 3:37 PM PDT on Monday, August 26, 2019.
const input = {
    date: 26,
    hours: 15,
    milliseconds: 2,
    minutes: 37,
    month: 7,
    seconds: 2,
    timezoneOffset: -420,
    year: 2019
};

// result should be a Date object.
const result = Office.context.mailbox.convertToUtcClientTime(input);

// Output should be "2019-08-26T22:37:02.002Z".
console.log(result.toISOString());

displayAppointmentForm(itemId)

Affiche un rendez-vous de calendrier existant.

La displayAppointmentForm méthode ouvre un rendez-vous de calendrier existant dans une nouvelle fenêtre sur le Bureau.

Dans Outlook sur 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 master rendez-vous d’une série périodique. Toutefois, vous ne pouvez pas afficher un instance de la série, car 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.

Dans Outlook sur le web, cette méthode ouvre le formulaire spécifié uniquement si le corps du formulaire est inférieur ou égal à 32 000 caractères.

Si l’identificateur d’élément spécifié n’identifie pas un rendez-vous existant, un volet vide s’ouvre sur l’ordinateur ou l’appareil client et aucun message d’erreur n’est retourné.

displayAppointmentForm(itemId: string): void;

Paramètres

itemId: string

Identificateur des services web Exchange pour un rendez-vous du calendrier existant.

Retours

void

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

Important : cette méthode n’est pas prise en charge dans Outlook sur Android ou sur iOS. Pour plus d’informations sur les API prises en charge dans Outlook Mobile, consultez API JavaScript Outlook prises en charge dans Outlook sur les appareils mobiles.

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml

const itemId = $("#itemId").val();
Office.context.mailbox.displayAppointmentForm(itemId);

displayAppointmentFormAsync(itemId, options, callback)

Affiche un rendez-vous de calendrier existant.

La méthode displayAppointmentFormAsync 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.

Dans Outlook sur le web, cette méthode ouvre le formulaire spécifié uniquement si le corps du formulaire est inférieur ou égal à 32 000 caractères.

Remarque : cette méthode n’est pas prise en charge dans Outlook sur iOS ou Android.

displayAppointmentFormAsync(itemId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Paramètres

itemId: string

Identificateur des services web Exchange pour un rendez-vous du calendrier existant.

options: Office.AsyncContextOptions

Littéral d’objet qui contient une ou plusieurs des propriétés suivantes : les asyncContextdéveloppeurs peuvent fournir n’importe quel objet auquel ils souhaitent accéder dans la fonction de rappel.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre, asyncResult, qui est un Office.AsyncResult objet .

Retours

void

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml

const itemId = $("#itemId").val();

// The async version will return error 9049 if the item is not found.
// The async version is only available starting with requirement set 1.9.
Office.context.mailbox.displayAppointmentFormAsync(itemId, function(asyncResult) {
  console.log("Result: " + JSON.stringify(asyncResult));
});

displayAppointmentFormAsync(itemId, callback)

Affiche un rendez-vous de calendrier existant.

La méthode displayAppointmentFormAsync 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.

Dans Outlook sur le web, cette méthode ouvre le formulaire spécifié uniquement si le corps du formulaire est inférieur ou égal à 32 000 caractères.

Remarque : cette méthode n’est pas prise en charge dans Outlook sur iOS ou Android.

displayAppointmentFormAsync(itemId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Paramètres

itemId: string

Identificateur des services web Exchange pour un rendez-vous du calendrier existant.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre, asyncResult, qui est un Office.AsyncResult objet .

Retours

void

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

displayMessageForm(itemId)

Affiche un message existant.

La displayMessageForm méthode ouvre un message existant dans une nouvelle fenêtre sur le bureau.

Dans Outlook sur le web, cette méthode ouvre le formulaire spécifié uniquement si le corps du formulaire est inférieur ou égal à 32 000 caractères.

Si l’identificateur d’élément spécifié n’identifie pas un message existant, aucun message n’est affiché sur l’ordinateur client et aucun message d’erreur n’est retourné.

displayMessageForm(itemId: string): void;

Paramètres

itemId: string

Identificateur des services web Exchange pour un message existant.

Retours

void

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

Important:

Cette méthode n’est pas prise en charge dans Outlook sur Android ou sur iOS. Pour plus d’informations sur les API prises en charge dans Outlook Mobile, consultez API JavaScript Outlook prises en charge dans Outlook sur les appareils mobiles.
N’utilisez pas avec displayMessageForm 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 afin de créer un nouveau rendez-vous.

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml

const itemId = $("#itemId").val();
Office.context.mailbox.displayMessageForm(itemId);

displayMessageFormAsync(itemId, options, callback)

Affiche un message existant.

La méthode displayMessageFormAsync ouvre un message existant dans une nouvelle fenêtre du Bureau ou dans une boîte de dialogue sur les appareils mobiles.

Dans Outlook sur le web, cette méthode ouvre le formulaire spécifié uniquement si le corps du formulaire est inférieur ou égal à 32 000 caractères.

Si l’identificateur d’élément spécifié n’identifie pas un message existant, aucun message ne s’affiche sur l’ordinateur client et aucun message d’erreur n’est retourné.

N’utilisez pas la displayMessageForm méthode ou displayMessageFormAsync avec un itemId qui représente un rendez-vous. Utilisez la displayAppointmentForm méthode ou displayAppointmentFormAsync pour afficher un rendez-vous existant et displayNewAppointmentForm ou displayNewAppointmentFormAsync pour afficher un formulaire pour créer un rendez-vous.

Remarque : cette méthode n’est pas prise en charge dans Outlook sur iOS ou Android.

displayMessageFormAsync(itemId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Paramètres

itemId: string

Identificateur des services web Exchange pour un message existant.

options: Office.AsyncContextOptions

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre, asyncResult, qui est un Office.AsyncResult objet .

Retours

void

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml

const itemId = $("#itemId").val();

// The async version will return error 9049 if the item is not found.
// The async version is only available starting with requirement set 1.9.
Office.context.mailbox.displayMessageFormAsync(itemId, function (asyncResult) {
 console.log("Result: " + JSON.stringify(asyncResult));
});

displayMessageFormAsync(itemId, callback)

Affiche un message existant.

La méthode displayMessageFormAsync ouvre un message existant dans une nouvelle fenêtre du Bureau ou dans une boîte de dialogue sur les appareils mobiles.

Dans Outlook sur le web, cette méthode ouvre le formulaire spécifié uniquement si le corps du formulaire est inférieur ou égal à 32 000 caractères.

Si l’identificateur d’élément spécifié n’identifie pas un message existant, aucun message ne s’affiche sur l’ordinateur client et aucun message d’erreur n’est retourné.

Remarque : cette méthode n’est pas prise en charge dans Outlook sur iOS ou Android.

displayMessageFormAsync(itemId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Paramètres

itemId: string

Identificateur des services web Exchange pour un message existant.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre, asyncResult, qui est un Office.AsyncResult objet .

Retours

void

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

displayNewAppointmentForm(parameters)

Affiche un formulaire permettant de créer un rendez-vous du calendrier.

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.

Dans Outlook sur le web, cette méthode affiche toujours un formulaire avec un champ participants. Si vous ne spécifiez aucun participant comme argument d’entrée, la méthode affiche un formulaire avec un bouton Enregistrer . Si vous avez spécifié des participants, le formulaire inclut ces derniers, en plus du bouton Envoyer.

Dans le client riche Outlook et Outlook RT, si vous spécifiez des participants ou des ressources dans le requiredAttendeesparamètre , optionalAttendeesou resources , cette méthode affiche un formulaire de réunion avec 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.

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.

displayNewAppointmentForm(parameters: AppointmentForm): void;

Paramètres

parameters: Office.AppointmentForm

AppointmentForm décrivant le nouveau rendez-vous. Toutes les propriétés sont facultatives.

Retours

void

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Lecture

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml

const start = new Date();
const 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",
  subject: "meeting",
  resources: ["projector@contoso.com"],
  body: "Hello World!"
});

displayNewAppointmentFormAsync(parameters, options, callback)

Affiche un formulaire permettant de créer un rendez-vous du calendrier.

La méthode displayNewAppointmentFormAsync 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.

Dans Outlook sur le web, cette méthode affiche toujours un formulaire avec 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.

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.

Remarque : cette méthode n’est pas prise en charge dans Outlook sur iOS ou Android.

displayNewAppointmentFormAsync(parameters: AppointmentForm, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Paramètres

parameters: Office.AppointmentForm

AppointmentForm décrivant le nouveau rendez-vous. Toutes les propriétés sont facultatives.

options: Office.AsyncContextOptions

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre, asyncResult, qui est un Office.AsyncResult objet .

Retours

void

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Lecture

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml

const start = new Date();
const end = new Date();
end.setHours(start.getHours() + 1);

// The async version is only available starting with requirement set 1.9,
// and provides a callback when the new appointment form has been created.
Office.context.mailbox.displayNewAppointmentFormAsync(
  {
    requiredAttendees: ["bob@contoso.com"],
    optionalAttendees: ["sam@contoso.com"],
    start: start,
    end: end,
    location: "Home",
    subject: "meeting",
    resources: ["projector@contoso.com"],
    body: "Hello World!"
  },
  function(asyncResult) {
    console.log(JSON.stringify(asyncResult));
  }
);

displayNewAppointmentFormAsync(parameters, callback)

Affiche un formulaire permettant de créer un rendez-vous du calendrier.

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.

Remarque : cette méthode n’est pas prise en charge dans Outlook sur iOS ou Android.

displayNewAppointmentFormAsync(parameters: AppointmentForm, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Paramètres

parameters: Office.AppointmentForm

AppointmentForm décrivant le nouveau rendez-vous. Toutes les propriétés sont facultatives.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre, asyncResult, qui est un Office.AsyncResult objet .

Retours

void

Remarques

[ Ensemble d’API : Boîte aux lettres 1.6 ]

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Lecture

displayNewMessageForm(parameters)

Affiche un formulaire pour la création d’un message.

La displayNewMessageForm méthode ouvre un formulaire qui permet à l’utilisateur de créer un message. Si des paramètres sont spécifiés, les champs de formulaire de message sont automatiquement renseignés avec le contenu des paramètres.

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.

displayNewMessageForm(parameters: any): void;

Paramètres

parameters: any

Dictionnaire contenant toutes les valeurs à renseigner pour l’utilisateur dans le nouveau formulaire. Tous les paramètres sont facultatifs.

toRecipients: tableau de chaînes contenant les adresses e-mail ou tableau contenant un objet EmailAddressDetails pour chacun des destinataires de la ligne À . Le tableau est limité à 100 entrées maximum.

ccRecipients: tableau de chaînes contenant les adresses e-mail ou tableau contenant un objet EmailAddressDetails pour chacun des destinataires sur la ligne Cc . Le tableau est limité à 100 entrées maximum.

bccRecipients: tableau de chaînes contenant les adresses e-mail ou tableau contenant un objet EmailAddressDetails pour chacun des destinataires sur la ligne Cci . Le tableau est limité à 100 entrées maximum.

subject: chaîne contenant l’objet du message. La chaîne est limitée à 255 caractères maximum.

htmlBody: corps HTML du message. La taille du corps du message est limitée à 32 Ko.

attachments: tableau d’objets JSON qui sont des pièces jointes de fichier ou d’élément.

attachments.type: indique le type de pièce jointe. Doit être un fichier pour une pièce jointe ou un élément pour une pièce jointe d’élément.

attachments.name: chaîne qui contient le nom de la pièce jointe, d’une longueur maximale de 255 caractères.

attachments.url: utilisé uniquement si type est défini sur fichier. Il s’agit de l’URI de l’emplacement du fichier. Important : ce lien doit être accessible publiquement, sans avoir besoin d’une authentification par Exchange Online serveurs. Toutefois, avec Exchange local, la liaison peut être accessible sur un réseau privé tant qu’elle n’a pas besoin d’une authentification supplémentaire.

attachments.isInline: utilisé uniquement si type est défini sur fichier. Si la valeur est true, indique que la pièce jointe sera affichée inline dans le corps du message et ne doit pas être affichée dans la liste des pièces jointes.

attachments.itemId: utilisé uniquement si type est défini sur item. ID d’élément EWS de l’e-mail existant que vous souhaitez joindre au nouveau message. Il s’agit d’une chaîne comportant un maximum de 100 caractères.

Retours

void

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Lecture

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-message.yaml

Office.context.mailbox.displayNewMessageForm({
  toRecipients: Office.context.mailbox.item.to, // Copies 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://www.cutestpaw.com/wp-content/uploads/2011/11/Cute-Black-Dogs-s.jpg",
      isInline: true
    }
  ]
});

displayNewMessageFormAsync(parameters, options, callback)

Affiche un formulaire pour la création d’un message.

La displayNewMessageFormAsync méthode ouvre un formulaire qui permet à l’utilisateur de créer un message. Si des paramètres sont spécifiés, les champs de formulaire de message sont automatiquement renseignés avec le contenu des paramètres.

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.

displayNewMessageFormAsync(parameters: any, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Paramètres

parameters: any

Dictionnaire contenant toutes les valeurs à renseigner pour l’utilisateur dans le nouveau formulaire. Tous les paramètres sont facultatifs.

subject: chaîne contenant l’objet du message. La chaîne est limitée à 255 caractères maximum.

htmlBody: corps HTML du message. La taille du corps du message est limitée à 32 Ko.

attachments: tableau d’objets JSON qui sont des pièces jointes de fichier ou d’élément.

attachments.type: indique le type de pièce jointe. Doit être un fichier pour une pièce jointe ou un élément pour une pièce jointe d’élément.

attachments.name: chaîne qui contient le nom de la pièce jointe, d’une longueur maximale de 255 caractères.

options: Office.AsyncContextOptions

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre, asyncResult, qui est un Office.AsyncResult objet .

Retours

void

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Lecture

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-message.yaml

// The async version is only available starting with requirement set 1.9,
// and provides a callback when the new message form has been created.
Office.context.mailbox.displayNewMessageFormAsync(
  {
    toRecipients: Office.context.mailbox.item.to, // Copies 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://www.cutestpaw.com/wp-content/uploads/2011/11/Cute-Black-Dogs-s.jpg",
        isInline: true
      }
    ]
  },
  function(asyncResult) {
    console.log(JSON.stringify(asyncResult));
  }
);

displayNewMessageFormAsync(parameters, callback)

Affiche un formulaire pour la création d’un message.

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.

displayNewMessageFormAsync(parameters: any, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Paramètres

parameters: any

Dictionnaire contenant toutes les valeurs à renseigner pour l’utilisateur dans le nouveau formulaire. Tous les paramètres sont facultatifs.

subject: chaîne contenant l’objet du message. La chaîne est limitée à 255 caractères maximum.

htmlBody: corps HTML du message. La taille du corps du message est limitée à 32 Ko.

attachments: tableau d’objets JSON qui sont des pièces jointes de fichier ou d’élément.

attachments.type: indique le type de pièce jointe. Doit être un fichier pour une pièce jointe ou un élément pour une pièce jointe d’élément.

attachments.name: chaîne qui contient le nom de la pièce jointe, d’une longueur maximale de 255 caractères.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre, asyncResult, qui est un Office.AsyncResult objet .

Retours

void

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Lecture

getCallbackTokenAsync(options, callback)

Obtient une chaîne qui contient un jeton utilisé pour appeler des API REST ou des services web Exchange (EWS).

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.

Le jeton est retourné sous forme de chaîne dans la asyncResult.value propriété .

getCallbackTokenAsync(options: Office.AsyncContextOptions & { isRest?: boolean }, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

Paramètres

options: Office.AsyncContextOptions & { isRest?: boolean }

Littéral d’objet qui contient une ou plusieurs des propriétés suivantes :- isRest: détermine si le jeton fourni sera utilisé pour les API REST Outlook ou les services web Exchange. La valeur par défaut est false. asyncContext: toutes les données d’état passées à la méthode asynchrone.

callback: (asyncResult: Office.AsyncResult<string>) => void

Une fois la méthode terminée, la fonction passée dans le paramètre de rappel est appelée avec un seul paramètre de type Office.AsyncResult. Le jeton est retourné sous forme de chaîne dans la asyncResult.value propriété . En cas d’erreur, les propriétés asyncResult.error et asyncResult.diagnostics peuvent fournir des informations supplémentaires.

Retours

void

Remarques

[ Ensemble d’API : tous prennent en charge le mode lecture ; Boîte aux lettres 1.3 introduit la prise en charge du mode composition ]

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

Important:

En octobre 2024, les jetons de rappel et d’identité d’utilisateur Exchange hérités seront désactivés par défaut pour tous les locataires Exchange Online. Cela fait partie de l’initiative Avenir sécurisé de Microsoft, qui fournit aux organisations les outils nécessaires pour répondre au paysage actuel des menaces. Les jetons d’identité utilisateur Exchange fonctionnent toujours pour Exchange en local. L’authentification d’application imbriquée est l’approche recommandée pour les jetons à l’avenir. Pour plus d’informations, consultez notre billet de blog et notre page FAQ.
Cette méthode est uniquement prise en charge en mode lecture dans Outlook sur Android et iOS. Pour plus d’informations sur les API prises en charge dans Outlook Mobile, consultez API JavaScript Outlook prises en charge dans Outlook sur les appareils mobiles.
Les opérations EWS ne sont pas prises en charge dans les compléments exécutés dans Outlook sur iOS et android. Un jeton REST est toujours retourné dans les clients mobiles Outlook, même si options.isRest a la valeur false.
L’appel de la getCallbackTokenAsync méthode en mode lecture nécessite un niveau d’autorisation minimal d’élément de lecture.
L’appel de la getCallbackTokenAsync méthode en mode composition nécessite que vous ayez enregistré l’élément. La saveAsync méthode nécessite un niveau d’autorisation minimal d’élément en lecture/écriture.
Pour obtenir des conseils sur les scénarios délégués ou partagés, consultez l’article Dossiers partagés et boîte aux lettres partagées .

Jetons REST

Lorsqu’un jeton REST est demandé (options.isRest = true), le jeton obtenu ne fonctionne pas pour authentifier les appels EWS. L’étendue du jeton est limitée à l’accès en lecture seule à l’élément actuel et à ses pièces jointes, sauf si le complément a spécifié l’autorisation de boîte aux lettres en lecture/écriture dans son manifeste. Si l’autorisation de lecture/écriture de boîte aux lettres est spécifiée, le jeton résultant accorde l’accès en lecture/écriture au courrier, au calendrier et aux contacts, y compris la possibilité d’envoyer des messages.

Le complément doit utiliser la propriété restUrl pour déterminer l’URL à utiliser pendant les appels de l’API REST.

Cette API fonctionne pour les étendues suivantes.

Mail.ReadWrite
Mail.Send
Calendars.ReadWrite
Contacts.ReadWrite

Jetons EWS

Lorsqu’un jeton EWS est demandé (options.isRest = false), le jeton obtenu ne fonctionne pas pour authentifier les appels d’API REST. Le jeton peut uniquement accéder à l’élément actif.

Le complément doit utiliser la propriété ewsUrl pour déterminer l’URL à utiliser pendant les appels EWS.

Vous pouvez passer le jeton et un identificateur de pièce jointe ou d’élément à un système externe. Ce système utilise le jeton comme jeton d’autorisation du porteur pour appeler l’opération GetAttachment des services Web Exchange (EWS) ou l’opération GetItem pour renvoyer 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é.

Erreurs :

HTTPRequestFailure: la requête a échoué. Veuillez rechercher le code d’erreur HTTP dans l’objet de diagnostics.
InternalServerError: le serveur Exchange a retourné une erreur. Pour plus d’informations, veuillez consulter l’objet de diagnostics.
NetworkError: l’utilisateur n’est plus connecté au réseau. Veuillez vérifier la connexion réseau et réessayer.

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/basic-rest-cors.yaml

Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function (result) {
    const ewsId = Office.context.mailbox.item.itemId;
    const token = result.value;
    const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
    const getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
            
    const xhr = new XMLHttpRequest();
    xhr.open('GET', getMessageUrl);
    xhr.setRequestHeader("Authorization", "Bearer " + token);
    xhr.onload = function (e) {
        console.log(this.response);
    }
    xhr.send();
});

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.

Le jeton est retourné sous forme de chaîne dans la asyncResult.value propriété .

getCallbackTokenAsync(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Paramètres

callback: (asyncResult: Office.AsyncResult<string>) => void

userContext: any

Optional. Données d’état transmises à la méthode asynchrone.

Retours

void

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

Important:

En octobre 2024, les jetons de rappel et d’identité d’utilisateur Exchange hérités seront désactivés par défaut pour tous les locataires Exchange Online. Cela fait partie de l’initiative Avenir sécurisé de Microsoft, qui fournit aux organisations les outils nécessaires pour répondre au paysage actuel des menaces. Les jetons d’identité utilisateur Exchange fonctionnent toujours pour Exchange en local. L’authentification d’application imbriquée est l’approche recommandée pour les jetons à l’avenir. Pour plus d’informations, consultez notre billet de blog et notre page FAQ.
Vous pouvez passer le jeton et un identificateur de pièce jointe ou d’élément à un système externe. Ce système utilise le jeton comme jeton d’autorisation du porteur pour appeler l’opération GetAttachment ou GetItem des services Web Exchange (EWS) 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é.
L’appel de la getCallbackTokenAsync méthode en mode lecture nécessite un niveau d’autorisation minimal d’élément de lecture.
L’appel de la getCallbackTokenAsync méthode en mode composition nécessite que vous ayez enregistré l’élément. La saveAsync méthode nécessite un niveau d’autorisation minimal d’élément en lecture/écriture.
Cette méthode n’est pas prise en charge dans Outlook sur Android ou sur iOS. Les opérations EWS ne sont pas prises en charge dans les compléments exécutés sur les clients mobiles Outlook. Pour plus d’informations sur les API prises en charge dans Outlook Mobile, consultez API JavaScript Outlook prises en charge dans Outlook sur les appareils mobiles.
Pour obtenir des conseils sur les scénarios délégués ou partagés, consultez l’article Dossiers partagés et boîte aux lettres partagées .

Erreurs :

HTTPRequestFailure: la requête a échoué. Veuillez rechercher le code d’erreur HTTP dans l’objet de diagnostics.
InternalServerError: le serveur Exchange a retourné une erreur. Pour plus d’informations, veuillez consulter l’objet de diagnostics.
NetworkError: l’utilisateur n’est plus connecté au réseau. Veuillez vérifier la connexion réseau et réessayer.

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/user-callback-token.yaml

Office.context.mailbox.getCallbackTokenAsync(function (result) {
    if (result.status !== Office.AsyncResultStatus.Succeeded) {
        console.error(`Token retrieval failed with message: ${result.error.message}`);
    } else {
        console.log(result.value);
    }
});

getSelectedItemsAsync(options, callback)

Obtient les messages actuellement sélectionnés sur lesquels un complément peut activer et effectuer des opérations. Un complément peut s’activer sur un maximum de 100 messages à la fois. Pour en savoir plus sur la sélection multiple d’éléments, voir Activer votre complément Outlook sur plusieurs messages.

getSelectedItemsAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<SelectedItemDetails[]>) => void): void;

Paramètres

options: Office.AsyncContextOptions

callback: (asyncResult: Office.AsyncResult<Office.SelectedItemDetails[]>) => void

Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre, asyncResult, qui est un Office.AsyncResult objet . Les propriétés des messages sélectionnés, telles que l’ID d’élément et l’objet, sont retournées sous la forme d’un tableau d’objets SelectedItemDetails dans la asyncResult.value propriété . Les objets du tableau suivent l’ordre dans lequel les messages ont été sélectionnés.

Retours

void

Remarques

[ Ensemble d’API : Boîte aux lettres 1.13 ]

Niveau d’autorisation minimal : boîte aux lettres en lecture/écriture

Mode Outlook applicable : Composer, Lire

Important : cette méthode s’applique uniquement aux messages.

getSelectedItemsAsync(callback)

getSelectedItemsAsync(callback: (asyncResult: Office.AsyncResult<SelectedItemDetails[]>) => void): void;

Paramètres

callback: (asyncResult: Office.AsyncResult<Office.SelectedItemDetails[]>) => void

Retours

void

Remarques

[ Ensemble d’API : Boîte aux lettres 1.13 ]

Niveau d’autorisation minimal : boîte aux lettres en lecture/écriture

Mode Outlook applicable : Composer, Lire

Important : cette méthode s’applique uniquement aux messages.

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-message-properties.yaml

// Retrieves the selected messages' properties and logs them to the console.
Office.context.mailbox.getSelectedItemsAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(asyncResult.error.message);
    return;
  }

  asyncResult.value.forEach((message) => {
    console.log(`Item ID: ${message.itemId}`);
    console.log(`Subject: ${message.subject}`);
    console.log(`Item type: ${message.itemType}`);
    console.log(`Item mode: ${message.itemMode}`);
  });
});

getUserIdentityTokenAsync(callback, userContext)

Obtient un jeton qui identifie l’utilisateur et le complément Office.

Le jeton est retourné sous forme de chaîne dans la asyncResult.value propriété .

getUserIdentityTokenAsync(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Paramètres

callback: (asyncResult: Office.AsyncResult<string>) => void

userContext: any

Optional. Données d’état transmises à la méthode asynchrone.

Retours

void

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

Important:

En octobre 2024, les jetons de rappel et d’identité d’utilisateur Exchange hérités seront désactivés par défaut pour tous les locataires Exchange Online. Cela fait partie de l’initiative Avenir sécurisé de Microsoft, qui fournit aux organisations les outils nécessaires pour répondre au paysage actuel des menaces. Les jetons d’identité utilisateur Exchange fonctionnent toujours pour Exchange en local. L’authentification d’application imbriquée est l’approche recommandée pour les jetons à l’avenir. Pour plus d’informations, consultez notre billet de blog et notre page FAQ.
La getUserIdentityTokenAsync méthode retourne un jeton que vous pouvez utiliser pour identifier et authentifier le complément et l’utilisateur avec un système externe.

Erreurs :

HTTPRequestFailure: la requête a échoué. Veuillez rechercher le code d’erreur HTTP dans l’objet de diagnostics.
InternalServerError: le serveur Exchange a retourné une erreur. Pour plus d’informations, veuillez consulter l’objet de diagnostics.
NetworkError: l’utilisateur n’est plus connecté au réseau. Veuillez vérifier la connexion réseau et réessayer.

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/user-identity-token.yaml

Office.context.mailbox.getUserIdentityTokenAsync(function (result) {
    if (result.status !== Office.AsyncResultStatus.Succeeded) {
        console.error(`Token retrieval failed with message: ${result.error.message}`);
    } else {
        console.log(result.value);
    }
});

makeEwsRequestAsync(data, callback, userContext)

Effectue une requête asynchrone à un service de services Web Exchange (EWS) sur le serveur Exchange qui héberge la boîte aux lettres de l’utilisateur.

La méthode makeEwsRequestAsync envoie une demande EWS à Exchange de la part du complément.

makeEwsRequestAsync(data: any, callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Paramètres

data: any

Demande EWS.

callback: (asyncResult: Office.AsyncResult<string>) => void

Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre, asyncResult, qui est un Office.AsyncResult objet . La réponse XML de la requête EWS est fournie sous forme de chaîne dans la asyncResult.value propriété . Dans Outlook sur le web, sur Windows (à partir de la version 2303 (build 16225.10000)) et sur Mac (à compter de la version 16.73 (23042601)), si la taille de la réponse dépasse 5 Mo, un message d’erreur est retourné dans la asyncResult.error propriété . Dans les versions antérieures du client de bureau Outlook, un message d’erreur est retourné si la taille de la réponse dépasse 1 Mo.

userContext: any

Optional. Données d’état transmises à la méthode asynchrone.

Retours

void

Remarques

Niveau d’autorisation minimal : boîte aux lettres en lecture/écriture

Mode Outlook applicable : Rédiger ou Lire

Important:

En octobre 2024, les jetons de rappel et d’identité d’utilisateur Exchange hérités seront désactivés par défaut pour tous les locataires Exchange Online. Cela fait partie de l’initiative Avenir sécurisé de Microsoft, qui fournit aux organisations les outils nécessaires pour répondre au paysage actuel des menaces. Les jetons d’identité utilisateur Exchange fonctionnent toujours pour Exchange en local. L’authentification d’application imbriquée est l’approche recommandée pour les jetons à l’avenir. Pour plus d’informations, consultez notre billet de blog et notre page FAQ.
Pour permettre à la makeEwsRequestAsync méthode d’effectuer des requêtes EWS, l’administrateur du serveur doit définir OAuthAuthenticationtrue sur sur le répertoire EWS du serveur d’accès au client .
Votre complément doit disposer de l’autorisation de lecture/écriture de boîte aux lettres pour utiliser la makeEwsRequestAsync méthode . Pour plus d’informations sur l’utilisation de l’autorisation de boîte aux lettres en lecture/écriture et les opérations EWS que vous pouvez appeler avec la makeEwsRequestAsync méthode , consultez Spécifier des autorisations pour l’accès aux compléments de messagerie à la boîte aux lettres de l’utilisateur.
Si votre complément doit accéder aux éléments associés au dossier ou si sa requête XML doit spécifier l’encodage UTF-8 (\<?xml version="1.0" encoding="utf-8"?\>), il doit utiliser Microsoft Graph ou des API REST pour accéder à la boîte aux lettres de l’utilisateur à la place.
Cette méthode n’est pas prise en charge dans Outlook sur Android ou sur iOS. Pour plus d’informations sur les API prises en charge dans Outlook Mobile, consultez API JavaScript Outlook prises en charge dans Outlook sur les appareils mobiles.
Cette méthode n’est pas prise en charge lorsque le complément est chargé dans une boîte aux lettres Gmail.
Lorsque vous utilisez la makeEwsRequestAsync méthode dans les compléments qui s’exécutent dans les versions d’Outlook antérieures à la version 15.0.4535.1004, vous devez définir la valeur d’encodage sur ISO-8859-1 (<?xml version="1.0" encoding="iso-8859-1"?>). Pour déterminer la version d’un client Outlook, utilisez la mailbox.diagnostics.hostVersion propriété . Vous n’avez pas besoin de définir la valeur d’encodage lorsque votre complément s’exécute dans Outlook sur le web. Pour déterminer le client Outlook dans lequel votre complément s’exécute, utilisez la mailbox.diagnostics.hostName propriété .

Exemples

function getSubjectRequest(id) {
    // Return a GetItem operation request for the subject of the specified item.
    const 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="Exchange2016" 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)  {
    const result = asyncResult.value;
    const context = asyncResult.asyncContext;

    // Process the returned response here.
}

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/get-icaluid-as-attendee.yaml

const ewsId = Office.context.mailbox.item.itemId;
const request = `<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <soap:Header><t:RequestServerVersion Version="Exchange2013" /></soap:Header>
      <soap:Body>
        <m:GetItem>
          <m:ItemShape>
            <t:BaseShape>AllProperties</t:BaseShape>
          </m:ItemShape >
          <m:ItemIds>
            <t:ItemId Id="${ewsId}" />
          </m:ItemIds>
        </m:GetItem>
      </soap:Body>
    </soap:Envelope>`;

Office.context.mailbox.makeEwsRequestAsync(request, (result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(result.error.message);
    return;
  }

  console.log(getUID(result.value));
});

...

const request = '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">'+
    '  <soap:Header><t:RequestServerVersion Version="Exchange2010" /></soap:Header>'+
    '  <soap:Body>'+
    '    <m:CreateItem MessageDisposition="SendAndSaveCopy">'+
    '      <m:SavedItemFolderId><t:DistinguishedFolderId Id="sentitems" /></m:SavedItemFolderId>'+
    '      <m:Items>'+
    '        <t:Message>'+
    '          <t:Subject>Hello, Outlook!</t:Subject>'+
    '          <t:Body BodyType="HTML">This message was sent from a ScriptLab code sample, used from ' + Office.context.mailbox.diagnostics.hostName + ', version ' + Office.context.mailbox.diagnostics.hostVersion + '!</t:Body>'+
    '          <t:ToRecipients>'+
    '            <t:Mailbox><t:EmailAddress>' + Office.context.mailbox.userProfile.emailAddress + '</t:EmailAddress></t:Mailbox>'+
    '          </t:ToRecipients>'+
    '        </t:Message>'+
    '      </m:Items>'+
    '    </m:CreateItem>'+
    '  </soap:Body>'+
    '</soap:Envelope>';

Office.context.mailbox.makeEwsRequestAsync(request, function (result) {
    console.log(result);
});

removeHandlerAsync(eventType, options, callback)

Supprime les gestionnaires d’événements pour un type d’événement pris en charge. Remarque : les événements sont disponibles uniquement avec l’implémentation du volet Office.

Pour les événements pris en charge, reportez-vous à la section Événements du modèle objet boîte aux lettres.

removeHandlerAsync(eventType: Office.EventType | string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Paramètres

eventType: Office.EventType | string

Événement qui doit révoquer le gestionnaire.

options: Office.AsyncContextOptions

Fournit une option permettant de conserver les données de contexte de tout type, inchangées, pour une utilisation dans un rappel.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre de type Office.AsyncResult.

Retours

void

Remarques

Niveau d’autorisation minimal : élément de lecture

Mode Outlook applicable : Rédiger ou Lire

removeHandlerAsync(eventType, callback)

Supprime les gestionnaires d’événements pour un type d’événement pris en charge. Remarque : les événements sont disponibles uniquement avec l’implémentation du volet Office.

Pour les événements pris en charge, reportez-vous à la section Événements du modèle objet boîte aux lettres.

removeHandlerAsync(eventType: Office.EventType | string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Paramètres

eventType: Office.EventType | string

Événement qui doit révoquer le gestionnaire.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Une fois la méthode terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre de type Office.AsyncResult.

Retours

void

Remarques