Partager via

Demande d’autorisations d’utilisation de l’API dans des compléments

  • Article

Cet article décrit les différents niveaux d’autorisation que vous déclarez dans le manifeste de votre complément pour spécifier le niveau d’accès à l’API JavaScript requis par votre complément pour ses fonctionnalités.

Importante

Cet article s’applique uniquement aux compléments non-Outlook. Pour en savoir plus sur les niveaux d’autorisation pour les compléments Outlook, consultez Modèle d’autorisations Outlook.

Modèle d’autorisations

Un modèle d’autorisations d’accès à l’API JavaScript à cinq niveaux fournit la base de la confidentialité et de la sécurité pour les utilisateurs de vos compléments. La figure suivante montre les cinq niveaux d’autorisations d’API que vous pouvez déclarer dans le manifeste de votre complément.

Niveaux d’autorisations pour les compléments.

Ces autorisations spécifient le sous-ensemble de l’API que le runtime de complément permet à votre complément d’utiliser lorsqu’un utilisateur insère, puis active (approuve) votre complément. Pour déclarer le niveau d’autorisation requis par votre complément, spécifiez l’une des valeurs d’autorisation dans le manifeste. Le balisage varie en fonction du type de manifeste.

  • Manifeste unifié pour Microsoft 365 : utilisez la propriété « authorization.permissions.resourceSpecific ». L’exemple suivant demande l’autorisation d’écrire un document , qui autorise uniquement les méthodes qui peuvent écrire dans (mais pas lire) le document.

    "authorization": {
    "permissions": {
      "resourceSpecific": [
        ...
        {
          "name": "Document.Write.User",
          "type": "Delegated"
        },
      ]
    }  
},

    Remarque

    Le manifeste unifié pour Microsoft 365 peut être utilisé dans les compléments Outlook de production. Il est disponible uniquement en préversion pour les compléments Excel, PowerPoint et Word.

  • Manifeste de complément uniquement : utilisez l’élément Permissions du manifeste. L’exemple suivant demande l’autorisation d’écrire un document , qui autorise uniquement les méthodes qui peuvent écrire dans (mais pas lire) le document.

    <Permissions>WriteDocument</Permissions>

Il est recommandé de toujours demander les autorisations sur la base du principe d’autorisation minimum. Autrement dit, vous ne devez demander l’autorisation d’accès qu’au sous-ensemble minimal de l’API que votre complément requiert pour fonctionner correctement. Par exemple, si votre complément doit uniquement lire les données du document d’un utilisateur pour ses fonctionnalités, vous ne devez pas demander plus que l’autorisation de lecture du document .

Le tableau suivant décrit les sous-ensembles des API JavaScript communes et spécifiques à l’application qui sont activées par chaque niveau d’autorisation.

Nom canonique de l’autorisation Nom du manifeste du complément uniquement Nom du manifeste unifié Sous-ensemble activé des API spécifiques à l’application Sous-ensemble activé des API communes
restreint Restreint Document.Restricted.User Aucun Les méthodes de l’objet Settings et la méthode Document.getActiveViewAsync. Il s’agit du niveau d’autorisation minimal qui peut être demandé par un complément.
lire le document ReadDocument Document.Read.User Toutes et uniquement les API qui lisent le document ou ses propriétés. En plus de l’API autorisée par l’autorisation restreinte , ajoute l’accès aux membres de l’API nécessaires pour lire le document et gérer les liaisons. Cela inclut l’utilisation des éléments suivants :
lire tout le document ReadAllDocument Document.ReadAll.User Identique à lire le document. En plus de l’API autorisée par les autorisations restreintes et de lecture de document , autorise l’accès supplémentaire suivant aux données du document.

  • Les méthodes Document.getSelectedDataAsync et Document.getFileAsync pour accéder au code OOXML sous-jacent du document (qui peut inclure une mise en forme, des liens, des graphiques incorporés, des commentaires, des révisions, etc. en plus du texte).
écrire un document WriteDocument Document.Write.User Toutes et uniquement les API qui écrivent dans le document ou ses propriétés. En plus de l’API autorisée par l’autorisation restreinte , ajoute l’accès aux membres d’API suivants.
lire/écrire un document ReadWriteDocument Document.ReadWrite.User Toutes les API specfic d’application, y compris celles qui s’abonnent à des événements. En plus de l’API autorisée par les autorisations restreintes, lire le document, lire tout le document et écrire un document , inclut l’accès à toutes les API restantes prises en charge par les compléments, y compris les méthodes d’abonnement aux événements. Vous devez déclarer l’autorisation de lecture/écriture de document pour accéder à ces membres d’API supplémentaires :

Voir aussi