Implementar pastas partilhadas e cenários de caixas de correio partilhadas num suplemento do Outlook
Este artigo descreve como implementar pastas partilhadas (também conhecidas como acesso delegado) e cenários de caixas de correio partilhadas no seu suplemento do Outlook, incluindo as permissões suportadas pela API JavaScript do Office.
Observação
O suporte de pastas partilhadas foi introduzido no conjunto de requisitos 1.8, enquanto o suporte de caixa de correio partilhada foi introduzido no requisito definido 1.13. Para obter informações sobre o suporte de cliente para estas funcionalidades, veja Supported clients and platforms (Clientes e plataformas suportados).
Clientes e plataformas suportados
A tabela seguinte mostra as combinações de cliente/servidor suportadas para esta funcionalidade, incluindo a Atualização Cumulativa mínima necessária, quando aplicável. As combinações excluídas não são suportadas.
| Cliente | Exchange Online | Exchange 2019 no local (Atualização Cumulativa 1 ou posterior) |
Exchange 2016 no local (Atualização Cumulativa 6 ou posterior) |
|---|---|---|---|
| Browser (IU moderna do Outlook) | Com suporte | Não aplicável | Não aplicável |
| Browser (IU clássica do Outlook) | Não aplicável | Não aplicável | Não aplicável |
| novo Outlook no Windows | Com suporte | Não aplicável | Não aplicável |
|
Windows (clássico) Pastas partilhadas: Versão 1910 (Compilação 12130.20272) ou posterior Caixas de correio partilhadas: Versão 2304 (Compilação 16327.20248) ou posterior |
Com suporte | Suportado* | Suportado* |
|
Mac Versão 16.47 ou posterior |
Com suporte | Com suporte | Com suporte |
Observação
* O suporte para esta funcionalidade num ambiente do Exchange no local está disponível a partir do Outlook clássico na Versão 2206 do Windows (Compilação 15330.20000) para o Canal Atual e a Versão 2207 (Compilação 15427.20000) para o Canal Empresarial Mensal.
Configurações suportadas
As secções seguintes descrevem as configurações suportadas para caixas de correio partilhadas e pastas partilhadas. As APIs de funcionalidade podem não funcionar conforme esperado noutras configurações. Selecione a plataforma que pretende aprender a configurar.
Pastas compartilhadas
O proprietário da caixa de correio tem primeiro de fornecer acesso a um delegado.
Para fornecer acesso para gerir reuniões e respostas a reuniões em nome do proprietário da caixa de correio, consulte Delegação de calendário no Outlook na Web.
Para fornecer acesso para gerir a caixa de entrada e o calendário em nome do proprietário da caixa de correio, o acesso tem de ser configurado através de uma das seguintes opções.
O proprietário da caixa de correio pode configurar o acesso através do Outlook clássico no Windows. Para saber mais, consulte Permitir que outra pessoa faça a gestão do seu correio e calendário.
Um administrador pode configurar o acesso através do Centro de administração do Microsoft 365. Para saber mais, consulte Conceder permissões de caixa de correio a outro utilizador do Microsoft 365.
Um administrador pode configurar o acesso através do centro de administração do Exchange. Para saber mais, veja Gerir permissões para destinatários.
Assim que o acesso for fornecido, o delegado tem de seguir as instruções descritas na secção "Adicionar a caixa de correio de outra pessoa à sua lista de pastas no Outlook Web App" do artigo Aceder à caixa de correio de outra pessoa.
Caixas de correio compartilhadas
Uma caixa de correio partilhada permite que um grupo de utilizadores monitorize e envie facilmente mensagens e convites para reuniões através de um endereço de e-mail partilhado.
No Outlook na Web, uma caixa de correio partilhada pode ser aberta no mesmo painel que a caixa de correio principal de um utilizador ou num separador ou janela separador do browser. Para obter orientações, consulte Abrir e utilizar uma caixa de correio partilhada no Outlook na Web.
Observação
No Outlook na Web, se abrir uma caixa de correio partilhada num separador ou janela separador do browser utilizando a opção Abrir outra caixa de correio, poderá encontrar problemas ao aceder a suplementos a partir da caixa de correio. Recomendamos que abra a caixa de correio no mesmo painel que a sua caixa de correio principal. Isto garante que os suplementos funcionam conforme esperado na sua caixa de correio partilhada.
Se preferir abrir a caixa de correio partilhada com a opção Abrir outra caixa de correio , recomendamos que implemente o suplemento nas caixas de correio partilhadas e do utilizador principal.
No novo Outlook no Windows, é adicionada uma caixa de correio partilhada à secção Partilhado comigo do painel de pastas. Para obter orientações, consulte Abrir e utilizar uma caixa de correio partilhada no Outlook.
Para saber mais sobre onde os suplementos fazem e não são ativados em geral, consulte a secção Itens da Caixa de Correio disponíveis para suplementos da página de descrição geral dos suplementos do Outlook.
Configurar o manifesto
Para implementar pastas partilhadas e cenários de caixas de correio partilhadas no seu suplemento, primeiro tem de configurar o suporte para a funcionalidade no seu manifesto. A marcação varia consoante o tipo de manifesto utilizado pelo suplemento.
Adicione um objeto adicional à matriz "authorization.permissions.resourceSpecific" e defina a respetiva propriedade "name" como "Mailbox.SharedFolder".
"authorization": {
"permissions": {
"resourceSpecific": [
...
{
"name": "Mailbox.SharedFolder",
"type": "Delegated"
},
]
}
},
Identificar se uma pasta ou caixa de correio é partilhada
Antes de poder executar operações numa pasta partilhada ou numa caixa de correio partilhada, primeiro tem de identificar se a pasta ou caixa de correio atual é partilhada. Para determinar isto, ligue para Office.context.mailbox.item.getSharedPropertiesAsync numa mensagem ou compromisso no modo de composição ou leitura. Se o item estiver numa pasta partilhada ou numa caixa de correio partilhada, o método devolve um objeto SharedProperties que fornece as permissões do utilizador, o endereço de e-mail do proprietário, o URL base da API REST e a localização da caixa de correio de destino.
O exemplo seguinte chama o getSharedPropertiesAsync método para identificar o proprietário da caixa de correio e as permissões do utilizador delegado ou da caixa de correio partilhada.
Office.context.mailbox.item.getSharedPropertiesAsync((result) => {
if (result.status === Office.AsyncResultStatus.Failed) {
console.error("The current folder or mailbox isn't shared.");
return;
}
const sharedProperties = result.value;
console.log(`Owner: ${sharedProperties.owner}`);
console.log(`Permissions: ${sharedProperties.delegatePermissions} `);
});
Permissões suportadas
A tabela seguinte descreve as permissões suportadas getSharedPropertiesAsync para delegados e utilizadores de caixas de correio partilhadas.
| Permissão | Valor | Descrição |
|---|---|---|
| Leitura | 1 (000001) | Pode ler itens. |
| Gravar | 2 (000010) | Pode criar itens. |
| DeleteOwn | 4 (000100) | Só é possível eliminar os itens que criaram. |
| DeleteAll | 8 (001000) | Pode eliminar quaisquer itens. |
| EditArNuar | 16 (010000) | Só é possível editar os itens que criaram. |
| EditarTodos | 32 (100000) | Pode editar quaisquer itens. |
Observação
Atualmente, a API suporta a obtenção de permissões existentes, mas não a definição de permissões.
A enumeração DelegatePermissions devolvida pela propriedade delegatePermissions é implementada com uma máscara de bits para indicar as permissões. Cada posição na máscara de bits representa uma permissão específica e, se estiver definida como 1, o utilizador tem a respetiva permissão. Por exemplo, se o segundo bit da direita for 1, o utilizador tem permissão de Escrita .
Executar uma operação como delegado ou utilizador de caixa de correio partilhada
Depois de identificar que o item de correio atual está numa pasta partilhada ou numa caixa de correio partilhada, o seu suplemento pode executar as operações necessárias no item no ambiente partilhado. Para executar operações num item num contexto partilhado, primeiro tem de configurar a permissão do suplemento no manifesto. Em seguida, utilize o Microsoft Graph para concluir as operações.
Observação
Os Serviços Web exchange (EWS) não são suportados em cenários de pastas partilhadas e caixas de correio partilhadas.
Configurar as permissões do suplemento
Para utilizar os serviços do Microsoft Graph, um suplemento tem de configurar a permissão de caixa de correio de leitura/escrita no respetivo manifesto. A marcação varia consoante o tipo de manifesto utilizado pelo suplemento.
- Manifesto unificado para o Microsoft 365: defina a propriedade "name" de um objeto na matriz "authorization.permissions.resourceSpecific" como "Mailbox.ReadWrite.User".
- Manifesto apenas de suplemento: defina o elemento Permissões como ReadWriteMailbox.
Usar o Microsoft Graph
Para implementar os seus cenários de pastas partilhadas e caixas de correio partilhadas, utilize o Microsoft Graph para aceder a recursos e informações adicionais da caixa de correio. Por exemplo, pode utilizar o Microsoft Graph para obter o conteúdo de uma mensagem do Outlook anexada a uma mensagem numa caixa de correio onde um utilizador tem acesso delegado. Para obter orientações sobre como utilizar o Microsoft Graph, consulte Descrição geral do Microsoft Graph e da API de correio do Outlook no Microsoft Graph.
Dica
Para aceder às APIs do Microsoft Graph a partir do seu suplemento, utilize MSAL.js autenticação de aplicações aninhadas (NAA). Para saber mais, consulte Ativar o SSO num Suplemento do Office através da autenticação de aplicações aninhadas (pré-visualização).
Limitações
Consoante os cenários do suplemento, existem algumas limitações a ter em conta ao processar pastas partilhadas ou situações de caixas de correio partilhadas.
Modo de Compose de mensagens
No modo Compose mensagem, getSharedPropertiesAsync não é suportado no Outlook na Web ou no Windows (novo e clássico), a menos que sejam cumpridas as seguintes condições.
Delegar acesso/Pastas partilhadas
- O proprietário da caixa de correio inicia uma mensagem. Pode ser uma nova mensagem, uma resposta ou um reencaminhamento.
- Guardam a mensagem e, em seguida, movem-na da sua própria pasta Rascunhos para uma pasta partilhada com o delegado.
- O delegado abre o rascunho a partir da pasta partilhada e, em seguida, continua a compor.
Caixa de correio partilhada (aplica-se apenas ao Outlook clássico no Windows)
- Um utilizador de caixa de correio partilhada inicia uma mensagem. Pode ser uma nova mensagem, uma resposta ou um reencaminhamento.
- Guardam a mensagem e, em seguida, movem-na da sua própria pasta Rascunhos para uma pasta na caixa de correio partilhada.
- Outro utilizador da caixa de correio partilhada abre o rascunho da caixa de correio partilhada e, em seguida, continua a compor.
Assim que estas condições forem cumpridas, a mensagem fica disponível num contexto partilhado e os suplementos que suportam estes cenários partilhados podem obter as propriedades partilhadas do item. Depois de a mensagem ser enviada, normalmente encontra-se na pasta Itens Enviados da caixa de correio pessoal do remetente.
Caixa de correio partilhada ou utilizador oculta de uma lista de endereços
Se um administrador escondeu um endereço de caixa de correio partilhado ou de um utilizador de uma lista de endereços, como a lista de endereços global (GAL), os itens de correio afetados abertos no relatório Office.context.mailbox.item da caixa de correio são nulos. Por exemplo, se o utilizador abrir um item de correio numa caixa de correio partilhada ocultada da GAL, Office.context.mailbox.item representar que o item de correio é nulo.
Sincronizar entre clientes de pastas partilhadas
Normalmente, as atualizações de um delegado à caixa de correio do proprietário são sincronizadas entre caixas de correio imediatamente. No entanto, se as operações do Microsoft Graph fossem utilizadas para definir uma propriedade expandida num item, essas alterações poderiam demorar algum tempo a sincronizar. Para evitar um atraso, recomendamos que utilize o objeto CustomProperties e as APIs relacionadas. Para saber mais, consulte a secção "Dados personalizados por item numa caixa de correio: propriedades personalizadas" de Obter e definir metadados num suplemento do Outlook.