Office.Mailbox interface

Référence

Paquet:: outlook

Fournit l’accès au modèle objet de complément Microsoft Outlook.

Propriétés de clé :

diagnostics : fournit des informations de diagnostic à un complément Outlook.
item : fournit des méthodes et des propriétés pour accéder à un message ou à un rendez-vous dans un complément Outlook.
userProfile : fournit des informations sur l’utilisateur dans un complément Outlook.

Remarques

Niveau d’autorisation minimal : restreint

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

Propriétés

diagnostics	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`, `OutlookIOS`ou .`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.
ewsUrl	Obtient l’URL du point de terminaison des services Web Exchange (EWS) pour ce compte de messagerie.
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 : 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.
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.

Méthodes

convertToLocalClientTime(timeValue)	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.
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.
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 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é.
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 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é.
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 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 `requiredAttendees`paramètre , `optionalAttendees`ou `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.
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. 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é .
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é .
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.

Détails de la propriété

diagnostics

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é

Office.Diagnostics

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

ewsUrl

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

ewsUrl: string;

Valeur de propriété

string

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

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 :

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é

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

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

convertToLocalClientTime(timeValue)

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

timeValue: Date

Objet Date.

Retours

Office.LocalClientTime

Remarques

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

Mode Outlook applicable : Rédiger ou Lire

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

itemId: string

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

Retours

void

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

displayMessageForm(itemId)

Affiche un message existant.

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

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

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

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

parameters: Office.AppointmentForm

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

Retours

void

Remarques

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

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

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.

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

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.

userContext: any

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

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

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

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 (nouveau et classique (à partir de la version 2303, build 16225.10000)) et sur Mac (à partir 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 d’Outlook sur Windows (classique) et sur Mac, 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

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

Partager via

Office.Mailbox interface

Remarques

Exemples

Propriétés

Méthodes

Détails de la propriété

diagnostics

Valeur de propriété

Remarques

Exemples

ewsUrl

Valeur de propriété

Remarques

Exemples

item

Valeur de propriété

userProfile

Valeur de propriété

Détails de la méthode

convertToLocalClientTime(timeValue)

Paramètres

Retours

Remarques

convertToUtcClientTime(input)

Paramètres

Retours

Remarques

Exemples

displayAppointmentForm(itemId)

Paramètres

Retours

Remarques

Exemples

displayMessageForm(itemId)

Paramètres

Retours

Remarques

Exemples

displayNewAppointmentForm(parameters)

Paramètres

Retours

Remarques

Exemples

getCallbackTokenAsync(callback, userContext)

Paramètres

Retours

Remarques

getUserIdentityTokenAsync(callback, userContext)

Paramètres

Retours

Remarques

Exemples

makeEwsRequestAsync(data, callback, userContext)

Paramètres

Retours

Remarques

Exemples

Ressources supplémentaires