Solicitar permissões para uso da API em suplementos

Este artigo descreve os diferentes níveis de permissão que declara no manifesto do suplemento para especificar o nível de acesso da API JavaScript que o suplemento necessita para as respetivas funcionalidades.

Importante

Este artigo aplica-se apenas a suplementos que não são do Outlook. Para saber mais sobre os níveis de permissão para suplementos do Outlook, veja Modelo de permissões do Outlook.

Modelo de permissões

Um modelo de permissões de acesso da API JavaScript de cinco níveis fornece a base para privacidade e segurança para os utilizadores dos seus suplementos. A figura seguinte mostra os cinco níveis de permissões de API que pode declarar no manifesto do suplemento.

Estas permissões especificam o subconjunto da API que o runtime do suplemento permite que o suplemento utilize quando um utilizador insere e, em seguida, ativa (confia) o seu suplemento. Para declarar o nível de permissão necessário para o suplemento, especifique um dos valores de permissão no manifesto. A marcação varia consoante o tipo de manifesto.

• Manifesto unificado para o Microsoft 365: utilize a propriedade "authorization.permissions.resourceSpecific". O exemplo seguinte pede a permissão de escrita do documento , que permite apenas métodos que podem escrever no documento (mas não ler).

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

  Observação

  O manifesto unificado do Microsoft 365 pode ser utilizado nos suplementos de produção do Outlook. Está disponível apenas como uma pré-visualização para suplementos do Excel, PowerPoint e Word.

• Manifesto apenas de suplemento: utilize o elemento Permissões do manifesto. O exemplo seguinte pede a permissão de escrita do documento , que permite apenas métodos que podem escrever no documento (mas não ler).

  <Permissions>WriteDocument</Permissions>
  

Como melhor prática, deve pedir permissões com base no princípio do menor privilégio. Ou seja, você deve solicitar permissão para acessar apenas o subconjunto mínimo da API que o suplemento requer para funcionar corretamente. Por exemplo, se o seu suplemento precisar apenas de ler dados no documento de um utilizador para as respetivas funcionalidades, não deve pedir mais do que a permissão de leitura do documento .

A tabela seguinte descreve os subconjuntos das APIs JavaScript comuns e específicas da aplicação que são ativadas por cada nível de permissão.

Nome canónico da permissão	Nome do manifesto apenas do suplemento	Nome do manifesto unificado	Subconjunto ativado das APIs específicas da aplicação	Subconjunto ativado das APIs Comuns
restrito	Restricted	Document.Restricted.User	Nenhum	Os métodos do objeto Definições e o método Document.getActiveViewAsync . Este é o nível mínimo de permissão que pode ser pedido por um suplemento.
ler documento	ReadDocument	Document.Read.User	Todas as APIs e apenas que leem o documento ou as respetivas propriedades.	Além da API permitida pela permissão restrita , adiciona acesso aos membros da API necessários para ler o documento e gerir enlaces. Isto inclui a utilização de: O método Document.getSelectedDataAsync para obter o texto selecionado, HTML (Word apenas) ou os dados tabulares, mas não o código do Open Office XML (OOXML) subjacente que contém todos os dados no documento. O método Document.getFileAsync para obter todo o texto no documento, mas não a cópia binária OOXML subjacente do documento Método Binding.getDataAsync para a leitura dos dados associados no documento. Os métodos addFromNamedItemAsync, addFromPromptAsync e addFromSelectionAsync do objeto Bindings para criar enlaces no documento. Métodos getAllAsync, getByIdAsync e releaseByIdAsync do objeto Bindings para acessar e remover as associações no documento. Método Document.getFilePropertiesAsync para acessar as propriedades de arquivo do documento, como a URL do documento. Método Document.goToByIdAsync para navegar até os objetos nomeados e locais no documento. Para os suplementos do painel de tarefas do Project, todos os métodos "get" do objeto ProjectDocument.
ler todo o documento	ReadAllDocument	Document.ReadAll.User	O mesmo que o documento lido.	Além da API permitida pelas permissões restritas e de leitura de documentos , permite o seguinte acesso adicional aos dados do documento. Os métodos Document.getSelectedDataAsync e Document.getFileAsync podem acessar o código OOXML subjacente do documento (que, além de texto, pode conter formatação, links, gráficos incorporados, comentários, revisões, etc.).
escrever documento	WriteDocument	Document.Write.User	Todas as APIs e apenas que escrevem no documento ou nas respetivas propriedades.	Além da API permitida pela permissão restrita , adiciona acesso aos seguintes membros da API. Método Document.setSelectedDataAsync para gravar na seleção do usuário no documento.
ler/escrever documento	ReadWriteDocument	Document.ReadWrite.User	Todas as APIs de especificação de aplicação, incluindo as que subscrevem eventos.	Além da API permitida pelo documento restrito de leitura, leitura de todos os documentos e permissões de escrita de documentos , inclui o acesso a toda a API restante suportada por suplementos, incluindo métodos para subscrever eventos. Tem de declarar a permissão de leitura/escrita do documento para aceder a estes membros adicionais da API: O método Binding.setDataAsync para escrever em regiões vinculadas do documento Método TableBinding.addRowsAsync para adicionar linhas às tabelas associadas. Método TableBinding.addColumnsAsync para adicionar colunas às tabelas associadas. Método TableBinding.deleteAllDataValuesAsync para excluir todos os dados em uma tabela associada. Métodos setFormatsAsync, clearFormatsAsync e setTableOptionsAsync do objeto TableBinding para definir a formatação e as opções nas tabelas associadas. Todos os membros dos objetos CustomXmlNode, CustomXmlPart, CustomXmlParts e CustomXmlPrefixMappings Todos os métodos para subscrever os eventos suportados pelos suplementos, especificamente os addHandlerAsync métodos e removeHandlerAsync dos objetos Binding, CustomXmlPart, Document, ProjectDocument e Settings .

Confira também

• Privacidade e segurança para Suplementos do Office