Activer les dossiers partagés et les scénarios de boîte aux lettres partagées dans un complément Outlook

Cet article explique comment activer les dossiers partagés (également appelés accès délégué) et les scénarios de boîte aux lettres partagées dans votre complément Outlook, notamment les autorisations que l’API JavaScript Office prend en charge.

Clients et plateformes pris en charge

Le tableau suivant présente les combinaisons client-serveur prises en charge pour cette fonctionnalité, y compris la mise à jour cumulative minimale requise, le cas échéant. Les combinaisons exclues ne sont pas prises en charge.

Configurations prises en charge

Les sections suivantes décrivent les configurations prises en charge pour les boîtes aux lettres partagées et les dossiers partagés. Les API de fonctionnalité peuvent ne pas fonctionner comme prévu dans d’autres configurations. Sélectionnez la plateforme que vous souhaitez apprendre à configurer.

Pour en savoir plus sur l’endroit où les compléments s’activent et ne s’activent pas en général, reportez-vous à la section Éléments de boîte aux lettres disponibles pour les compléments de la page vue d’ensemble des compléments Outlook.

Autorisations prises en charge

Le tableau suivant décrit les autorisations que l’API JavaScript Office prend en charge pour les délégués et les utilisateurs de boîtes aux lettres partagées.

L’objet DelegatePermissions est implémenté à l’aide d’un masque de bits pour indiquer les autorisations. Chaque position dans le masque de bits représente une autorisation particulière et si elle est définie sur 1 , l’utilisateur dispose de l’autorisation correspondante. Par exemple, si le deuxième bit de droite est 1, l’utilisateur dispose de l’autorisation Écriture . Vous pouvez voir un exemple de vérification d’une autorisation spécifique dans la section Effectuer une opération en tant qu’utilisateur de boîte aux lettres déléguée ou partagée plus loin dans cet article.

Synchroniser entre les clients de dossiers partagés

Les mises à jour d’un délégué dans la boîte aux lettres du propriétaire sont généralement synchronisées immédiatement entre les boîtes aux lettres.

Toutefois, si des opérations REST ou EWS (Exchange Web Services) ont été utilisées pour définir une propriété étendue sur un élément, la synchronisation de ces modifications peut prendre quelques heures. Nous vous recommandons plutôt d’utiliser l’objet CustomProperties et les API associées pour éviter un tel délai. Pour en savoir plus, consultez la section propriétés personnalisées de l’article « Obtenir et définir des métadonnées dans un complément Outlook ».

Configurer le manifeste

Pour activer les dossiers partagés et les scénarios de boîte aux lettres partagées dans votre complément, vous devez activer les autorisations requises dans le manifeste.

Tout d’abord, pour prendre en charge les appels REST d’un délégué, le complément doit demander l’autorisation de boîte aux lettres en lecture/écriture . Le balisage varie en fonction du type de manifeste.

• Manifeste du complément uniquement : définissez l’élément Permissions> sur<ReadWriteMailbox.
• Manifeste unifié pour Microsoft 365 : définissez la propriété « name » d’un objet dans le tableau « authorization.permissions.resourceSpecific » sur « Mailbox.ReadWrite.User ».

Ensuite, activez la prise en charge des dossiers partagés. Le balisage varie en fonction du type de manifeste.

"authorization": {
  "permissions": {
    "resourceSpecific": [
      ...
      {
        "name": "Mailbox.SharedFolder",
        "type": "Delegated"
      },
    ]
  }
},

...
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    ...
    <Hosts>
      <Host xsi:type="MailHost">
        <DesktopFormFactor>
          <SupportsSharedFolders>true</SupportsSharedFolders>
          <FunctionFile resid="residDesktopFuncUrl" />
          <ExtensionPoint xsi:type="MessageReadCommandSurface">
            <!-- configure selected extension point -->
          </ExtensionPoint>

          <!-- You can define more than one ExtensionPoint element as needed -->

        </DesktopFormFactor>
      </Host>
    </Hosts>
    ...
  </VersionOverrides>
</VersionOverrides>
...

Effectuer une opération en tant qu’utilisateur délégué ou utilisateur de boîte aux lettres partagée

Vous pouvez obtenir les propriétés partagées d’un élément en mode Compose ou Lecture en appelant la méthode item.getSharedPropertiesAsync . Cela renvoie un objet SharedProperties qui fournit actuellement les autorisations de l’utilisateur, l’adresse e-mail du propriétaire, l’URL de base de l’API REST et la boîte aux lettres cible.

L’exemple suivant montre comment obtenir les propriétés partagées d’un message ou d’un rendez-vous, vérifier si le délégué ou l’utilisateur de boîte aux lettres partagée dispose de l’autorisation Écriture et effectuer un appel REST.

function performOperation() {
  Office.context.mailbox.getCallbackTokenAsync({
      isRest: true
    },
    function (asyncResult) {
      if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value !== "") {
        Office.context.mailbox.item.getSharedPropertiesAsync({
            // Pass auth token along.
            asyncContext: asyncResult.value
          },
          function (asyncResult1) {
            let sharedProperties = asyncResult1.value;
            let delegatePermissions = sharedProperties.delegatePermissions;

            // Determine if user can do the expected operation.
            // E.g., do they have Write permission?
            if ((delegatePermissions & Office.MailboxEnums.DelegatePermissions.Write) != 0) {
              // Construct REST URL for your operation.
              // Update <version> placeholder with actual Outlook REST API version e.g. "v2.0".
              // Update <operation> placeholder with actual operation.
              let rest_url = sharedProperties.targetRestUrl + "/<version>/users/" + sharedProperties.targetMailbox + "/<operation>";
  
              $.ajax({
                  url: rest_url,
                  dataType: 'json',
                  headers:
                  {
                    "Authorization": "Bearer " + asyncResult1.asyncContext
                  }
                }
              ).done(
                function (response) {
                  console.log("success");
                }
              ).fail(
                function (error) {
                  console.log("error message");
                }
              );
            }
          }
        );
      }
    }
  );
}

Gérer l’appel de REST sur des éléments partagés et non partagés

Si vous souhaitez appeler une opération REST sur un élément, que l’élément soit partagé ou non, vous pouvez utiliser l’API getSharedPropertiesAsync pour déterminer si l’élément est partagé. Après cela, vous pouvez construire l’URL REST de l’opération à l’aide de l’objet approprié.

if (item.getSharedPropertiesAsync) {
  // In Windows, Mac, and the web client, this indicates a shared item so use SharedProperties properties to construct the REST URL.
  // Add-ins don't activate on shared items in mobile so no need to handle.

  // Perform operation for shared item.
} else {
  // In general, this isn't a shared item, so construct the REST URL using info from the Call REST APIs article:
  // https://learn.microsoft.com/office/dev/add-ins/outlook/use-rest-api

  // Perform operation for non-shared item.
}

Limitations

Selon les scénarios de votre complément, il existe quelques limitations à prendre en compte lors de la gestion des dossiers partagés ou des situations de boîte aux lettres partagées.

Mode de composition de messages

En mode de composition de message, getSharedPropertiesAsync n’est pas pris en charge dans Outlook sur le web ou sur Windows, sauf si les conditions suivantes sont remplies.

a. Déléguer l’accès/Dossiers partagés

1. Le propriétaire de la boîte aux lettres démarre un message. Il peut s’agir d’un nouveau message, d’une réponse ou d’un transfert.
2. Ils enregistrent le message, puis le déplacent de leur propre dossier Brouillons vers un dossier partagé avec le délégué.
3. Le délégué ouvre le brouillon à partir du dossier partagé, puis continue la composition.

b. Boîte aux lettres partagée (s’applique uniquement à Outlook classique sur Windows)

1. Un utilisateur de boîte aux lettres partagée démarre un message. Il peut s’agir d’un nouveau message, d’une réponse ou d’un transfert.
2. Ils enregistrent le message, puis le déplacent de leur propre dossier Brouillons vers un dossier dans la boîte aux lettres partagée.
3. Un autre utilisateur de boîte aux lettres partagée ouvre le brouillon à partir de la boîte aux lettres partagée, puis continue de composer.

Le message est maintenant dans un contexte partagé et les compléments qui prennent en charge ces scénarios partagés peuvent obtenir les propriétés partagées de l’élément. Une fois le message envoyé, il se trouve généralement dans le dossier Éléments envoyés de l’expéditeur.

REST et EWS

Votre complément peut utiliser REST. Pour activer l’accès REST à la boîte aux lettres du propriétaire ou à la boîte aux lettres partagée, le cas échéant, le complément doit demander l’autorisation de boîte aux lettres en lecture/écriture dans le manifeste. Le balisage varie en fonction du type de manifeste.

• Manifeste du complément uniquement : définissez l’élément Permissions> sur<ReadWriteMailbox.
• Manifeste unifié pour Microsoft 365 : définissez la propriété « name » d’un objet dans le tableau « authorization.permissions.resourceSpecific » sur « Mailbox.ReadWrite.User ».

EWS n’est pas pris en charge.

Boîte aux lettres utilisateur ou partagée masquée dans une liste d’adresses

Si un administrateur a masqué l’adresse d’un utilisateur ou d’une boîte aux lettres partagée d’une liste d’adresses telle que la liste d’adresses globale ,les éléments de courrier affectés ouverts dans le rapport Office.context.mailbox.item de boîte aux lettres ont la valeur Null. Par exemple, si l’utilisateur ouvre un élément de courrier dans une boîte aux lettres partagée qui est masquée dans la liste d’adresses, Office.context.mailbox.item ce qui représente cet élément de courrier est null.

Voir aussi

• Autoriser une autre personne à gérer votre courrier électronique et votre calendrier
• Partage de calendrier dans Microsoft 365
• Ajouter une boîte aux lettres partagée à Outlook
• Guide pratique pour trier les éléments de manifeste
• Masque (informatique)
• Opérateurs de bits JavaScript