Office.Mailbox interface

Fournit des informations de diagnostic à un complément Outlook.

Contient les membres suivants.

• hostName (string) : chaîne qui représente le nom de l’application Office. Il doit s’agir de l’une des valeurs suivantes : Outlook,newOutlookWindows , OutlookWebApp, OutlookIOSou .OutlookAndroid Remarque : La valeur « Outlook » est retournée pour Outlook sur Windows (classique) et sur Mac.

• hostVersion(string) : chaîne qui représente la version de l’application Office ou du Exchange Server (par exemple, « 15.0.468.0 »). Si le complément de messagerie est en cours d’exécution dans Outlook sur Windows (classique), sur Mac ou sur des appareils mobiles, la hostVersion propriété renvoie la version du client Outlook. Dans Outlook sur le web et outlook sur Windows, la propriété retourne la version du Exchange Server.

• OWAView(MailboxEnums.OWAView ou string) : enum (ou littéral de chaîne) qui représente l’affichage actuel de Outlook sur le web. Si l’application n’est pas Outlook sur le web, l’accès à cette propriété n’est pas défini. Outlook sur le web a trois affichages (OneColumn - affichés lorsque l’écran est étroit, TwoColumns - affiché lorsque l’écran est plus large et ThreeColumns - affiché lorsque l’écran est large) qui correspondent à la largeur de l’écran et de la fenêtre, ainsi qu’au nombre de colonnes qui peuvent être affichées.

Pour plus d’informations, consultez Office.Diagnostics.

diagnostics: Diagnostics;

Valeur de propriété

Remarques

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

Mode Outlook applicable : Rédiger ou Lire

À compter de l’ensemble de conditions requises pour la boîte aux lettres 1.5, vous pouvez également utiliser la propriété Office.context.diagnostics pour obtenir des informations similaires.

Exemples

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

// This function gets a mailbox's diagnostic information, such as Outlook client and version, and logs it to the console.
const diagnostics = Office.context.mailbox.diagnostics;
console.log(`Client application: ${diagnostics.hostName}`);
console.log(`Client version: ${diagnostics.hostVersion}`);

switch (diagnostics.OWAView) {
  case undefined:
    console.log("Current view (Outlook on the web only): Not applicable. An Outlook desktop client is in use.");
    break;
  case Office.MailboxEnums.OWAView.OneColumnNarrow:
    console.log("Current view (Outlook on the web only): Viewed from an older generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.OneColumn:
    console.log("Current view (Outlook on the web only): Viewed from a newer generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.TwoColumns:
    console.log("Current view (Outlook on the web only): Viewed from a tablet");
    break;
  case Office.MailboxEnums.OWAView.ThreeColumns:
    console.log("Current view (Outlook on the web only): Viewed from a desktop computer");
    break;
}

Obtient l’URL du point de terminaison des services Web Exchange (EWS) pour ce compte de messagerie.

ewsUrl: string;

Valeur de propriété

Remarques

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

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

// Get the EWS URL and EWS item ID.
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);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

É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 :

MessageCompose, MessageRead, AppointmentCompose, AppointmentRead

Important:

• Lorsque vous appelez Office.context.mailbox.item un message, notez que le volet de lecture dans le client Outlook doit être activé. Pour obtenir des conseils sur la configuration du volet de lecture, consultez Utiliser et configurer le volet de lecture pour afficher un aperçu des messages.

• 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é

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

restUrl: string;

Valeur de propriété

Remarques

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

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

Mode Outlook applicable : Rédiger ou Lire

Important:

• Les points de terminaison REST v2.0 et bêta d’Outlook sont désormais déconseillés. Toutefois, les compléments publiés en privé et hébergés par AppSource peuvent utiliser le service REST jusqu’à la fin du support étendu pour Outlook 2019 le 14 octobre 2025. Le trafic de ces compléments est automatiquement identifié pour l’exemption. Cette exemption s’applique également aux nouveaux compléments développés après le 31 mars 2024. Bien que les compléments puissent utiliser le service REST jusqu’en 2025, nous vous encourageons vivement à migrer vos compléments pour utiliser Microsoft Graph. Pour obtenir des conseils, consultez Comparer les points de terminaison de l’API REST Microsoft Graph et Outlook.

• Votre complément 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 complément doit disposer des 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 .

Exemples

// Get the URL of the REST endpoint.
const restUrl = Office.context.mailbox.restUrl;
console.log(`REST API URL: ${restUrl}`);

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é

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

Retours

Remarques

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

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

Mode Outlook applicable : Rédiger ou Lire

Exemples

Office.onReady(() => {
    document.addEventListener('DOMContentLoaded', () => {
        // Get a reference to the mailbox and use it to add an event handler.
        const mailbox = Office.context.mailbox;
        mailbox.addHandlerAsync(Office.EventType.ItemChanged, loadNewItem, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                // Handle error.
            }
        });
    });
});

function loadNewItem(eventArgs) {
    const item = Office.context.mailbox.item;

    // Check that item isn't null.
    if (item !== null) {
        // Work with item. For example, define and call a function that
        // loads the properties of the newly selected item.
        loadProps(item);
    }
}

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

Retours

Remarques

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

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

Mode Outlook applicable : Rédiger ou Lire

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

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

Paramètres

Retours

Remarques

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

Niveau d’autorisation minimal : restreint

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 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 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

// Get the EWS URL and EWS item ID.
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);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

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

Le fuseau horaire utilisé par le client Outlook varie selon la plateforme. Outlook sur Windows (classique) et sur Mac utilisent le fuseau horaire de l’ordinateur client. Outlook sur le web et les nouveaux Outlook sur Windows utilisent 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.

Dans Outlook sur Windows (classique) et sur Mac, la convertToLocalClientTime méthode retourne un objet dictionnaire avec les valeurs définies sur le fuseau horaire de l’ordinateur client. Dans Outlook sur le web et la nouvelle version d’Outlook sur Windows, la convertToLocalClientTime méthode retourne un objet dictionnaire avec les valeurs définies sur le fuseau horaire spécifié dans le CAE.

convertToLocalClientTime(timeValue: Date): LocalClientTime;

Paramètres

Retours

Remarques

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

Mode Outlook applicable : Rédiger ou Lire

Convertit un ID pris en charge au format REST.

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

Paramètres

Retours

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 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/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
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);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

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

Retours

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());

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 et la nouvelle version d’Outlook sur Windows, cette méthode ouvre le formulaire spécifié uniquement si le corps du formulaire est inférieur ou égal à 32 Ko 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

Retours

Remarques

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

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);

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 et la nouvelle version d’Outlook sur Windows, cette méthode ouvre le formulaire spécifié uniquement si le corps du formulaire est inférieur ou égal à 32 Ko 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

Retours

Remarques

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

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);

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 et la nouvelle version d’Outlook sur Windows, 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 Outlook sur Windows (classique) et sur Mac, 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

Retours

Remarques

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

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

Mode Outlook applicable : Lecture

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-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!"
});

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

Retours

Remarques

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

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.

• Les points de terminaison REST v2.0 et bêta d’Outlook sont désormais déconseillés. Toutefois, les compléments publiés en privé et hébergés par AppSource peuvent utiliser le service REST jusqu’à la fin du support étendu pour Outlook 2019 le 14 octobre 2025. Le trafic de ces compléments est automatiquement identifié pour l’exemption. Cette exemption s’applique également aux nouveaux compléments développés après le 31 mars 2024. Bien que les compléments puissent utiliser le service REST jusqu’en 2025, nous vous encourageons vivement à migrer vos compléments pour utiliser Microsoft Graph. Pour obtenir des conseils, consultez Comparer les points de terminaison de l’API REST Microsoft Graph et Outlook.

• Cette méthode n’est pas prise en charge si vous chargez un complément dans une boîte aux lettres Outlook.com ou Gmail.

• 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.

Obtient une chaîne qui contient un jeton servant à obtenir une pièce jointe ou un élément à partir d’un serveur Exchange.

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(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Paramètres

Retours

Remarques

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

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 dans Outlook sur les clients mobiles. 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 si vous chargez un complément dans une boîte aux lettres Outlook.com ou Gmail.

• 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((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`Token retrieval failed with message: ${result.error.message}`);
        return;
    }

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

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

Retours

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.

• Cette méthode n’est pas prise en charge si vous chargez un complément dans une boîte aux lettres Outlook.com ou Gmail.

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((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`Token retrieval failed with message: ${result.error.message}`)
        return;
    }

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

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

Retours

Remarques

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

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 ou outlook sur Windows. 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, (result) => {
    console.log(result);
});

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

Retours

Remarques

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

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

Mode Outlook applicable : Rédiger ou Lire

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

Retours

Remarques

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

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

Mode Outlook applicable : Rédiger ou Lire

Exemples

Office.context.mailbox.removeHandlerAsync(Office.EventType.OfficeThemeChanged, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.error("Failed to remove event handler: " + asyncResult.error.message);
        return;
    }

    console.log("Event handler removed successfully.");
});