Habilitar pastas compartilhadas e cenários de caixa de correio compartilhada em um suplemento do Outlook

Este artigo descreve como habilitar pastas compartilhadas (também conhecidas como acesso de delegado) e cenários de caixa de correio compartilhada no suplemento do Outlook, incluindo quais permissões a API JavaScript do Office dá suporte.

Observação

O suporte à pasta compartilhada foi introduzido no conjunto de requisitos 1.8, enquanto o suporte de caixa de correio compartilhada foi introduzido no conjunto de requisitos 1.13. Para obter informações sobre o suporte ao cliente para esses recursos, consulte Clientes e plataformas com suporte.

Clientes e plataformas com suporte

A tabela a seguir mostra combinações cliente-servidor com suporte para esse recurso, incluindo a atualização cumulativa mínima necessária, quando aplicável. Não há suporte para combinações excluídas.

Cliente	Exchange Online	Exchange 2019 local (Atualização cumulativa 1 ou posterior)	Exchange 2016 local (Atualização cumulativa 6 ou posterior)	Exchange 2013 local
Windows Pastas compartilhadas: versão 1910 (Build 12130.20272) ou posterior Caixas de correio compartilhadas: versão 2304 (Build 16327.20248) ou posterior	Com suporte	Suportado*	Suportado*	Suportado*
Mac Compilar 16.47 ou posterior	Com suporte	Com suporte	Com suporte	Com suporte
Navegador da Web (interface do usuário moderna do Outlook)	Com suporte	Não aplicável	Não aplicável	Não aplicável
Navegador da Web (interface do usuário clássica do Outlook)	Não aplicável	Não aplicável	Não aplicável	Não aplicável

Observação

* O suporte para esse recurso em um ambiente local do Exchange está disponível a partir do Outlook na Versão 2206 do Windows (Build 15330.20000) para o Canal Atual e a Versão 2207 (Build 15427.20000) para o Canal Da Empresa Mensal.

Configurações com suporte

As seções a seguir descrevem configurações com suporte para caixas de correio compartilhadas e pastas compartilhadas. As APIs do recurso podem não funcionar conforme o esperado em outras configurações. Selecione a plataforma que você gostaria de aprender a configurar.

Windows

Pastas compartilhadas

O proprietário da caixa de correio deve primeiro fornecer acesso a um delegado usando uma das seguintes opções.

• Configure o acesso de delegado da caixa de correio no Outlook no Windows. Para saber mais, confira Permitir que outra pessoa gerencie seu email e calendário.

• Configure o acesso de delegado do Centro de administração do Microsoft 365. Essa opção só pode ser concluída pelos administradores. Para saber mais, confira Dar permissões de caixa de correio a outro usuário do Microsoft 365.

• Configure o acesso de delegado do centro de administração do Exchange. Essa opção só pode ser concluída pelos administradores. Para saber mais, confira Gerenciar permissões para destinatários.

Depois que o acesso for fornecido, o delegado deverá seguir as instruções descritas na seção "Adicionar a caixa de correio de outra pessoa ao seu perfil" do artigo Gerenciar itens de calendário e email de outra pessoa.

Caixas de correio compartilhadas

Os administradores do exchange server podem criar e gerenciar caixas de correio compartilhadas para conjuntos de usuários acessarem. Exchange Online e ambientes locais do Exchange têm suporte.

Um recurso de Exchange Server conhecido como "automação" está ativado por padrão, o que significa que, posteriormente, a caixa de correio compartilhada deve aparecer automaticamente no aplicativo outlook de um usuário depois que o Outlook tiver sido fechado e reaberto. No entanto, se um administrador desativar a automação, o usuário deverá seguir as etapas manuais descritas na seção "Adicionar uma caixa de correio compartilhada ao Outlook" do artigo Abrir e usar uma caixa de correio compartilhada no Outlook.

Aviso

NÃO entre na caixa de correio compartilhada com uma senha. As APIs de recurso não funcionarão nesse caso.

Navegador da Web – Outlook moderno

Pastas compartilhadas

O proprietário da caixa de correio deve primeiro fornecer acesso a um delegado.

• Para fornecer acesso ao gerenciamento de reuniões e respostas de reunião em nome do proprietário da caixa de correio, consulte Delegação do Calendário em Outlook na Web.

• Para fornecer acesso para gerenciar a caixa de entrada e o calendário em nome do proprietário da caixa de correio, o acesso deve ser configurado por meio de uma das opções a seguir.

  • O proprietário da caixa de correio pode configurar o acesso por meio do Outlook no Windows. Para saber mais, confira Permitir que outra pessoa gerencie seu email e calendário.

  • Um administrador pode configurar o acesso por meio do Centro de administração do Microsoft 365. Para saber mais, confira Dar permissões de caixa de correio a outro usuário do Microsoft 365.

  • Um administrador pode configurar o acesso por meio do centro de administração do Exchange. Para saber mais, confira Gerenciar permissões para destinatários.

Depois que o acesso for fornecido, o delegado deverá seguir as instruções descritas na seção "Adicionar a caixa de correio de outra pessoa à lista de pastas em Outlook Web App" do artigo Acessar a caixa de correio de outra pessoa.

Caixas de correio compartilhadas

Uma caixa de correio compartilhada permite que um grupo de usuários monitore e envie facilmente mensagens e convites de reunião usando um endereço de email compartilhado. Em Outlook na Web, uma caixa de correio compartilhada pode ser aberta no mesmo painel que a caixa de correio primária de um usuário ou em uma guia ou janela separada do navegador. Para obter diretrizes, consulte Abrir e usar uma caixa de correio compartilhada em Outlook na Web.

Quando uma caixa de correio compartilhada é aberta no mesmo painel que a caixa de correio primária de um usuário, o tipo de suplementos acessíveis da caixa de correio compartilhada difere entre os modos de composição e leitura.

• No modo de composição, todos os suplementos implantados pelo administrador de uma organização estão disponíveis para uso na caixa de correio compartilhada.
• No modo de leitura, somente suplementos configurados no manifesto para dar suporte a arquivos compartilhados estão disponíveis para uso na caixa de correio compartilhada. Para obter instruções sobre como fazer isso para o manifesto XML ou o manifesto unificado, consulte a seção Configurar o manifesto .

Quando uma caixa de correio compartilhada é aberta em uma guia ou janela separada do navegador, somente os suplementos que atendem aos seguintes critérios estão disponíveis para uso na caixa de correio compartilhada.

• O suplemento configurado no manifesto para dar suporte a arquivos compartilhados. Para obter instruções sobre como fazer isso para o manifesto XML ou o manifesto unificado, consulte a seção Configurar o manifesto .
• O suplemento é implantado na caixa de correio compartilhada e na caixa de correio do usuário que tem acesso à caixa de correio compartilhada pelo administrador de uma organização.
• O suplemento deve ser implantado usando o método de Implantação Centralizada Fixa ou Opcional. Para obter mais informações sobre os métodos de implantação, consulte Perguntas frequentes sobre implantação centralizada.

Mac

Caixas de correio compartilhadas

Uma caixa de correio compartilhada permite que um grupo de usuários monitore e envie facilmente mensagens e convites de reunião usando um endereço de email compartilhado. Para obter diretrizes sobre como acessar uma caixa de correio compartilhada para a qual você tem permissões no Outlook no Mac, consulte a seção "Abrir uma caixa de correio compartilhada ou delegada" da pasta Abrir um Email compartilhado, Calendário ou Pessoas em Outlook para Mac.

Usuários com permissões para uma caixa de correio compartilhada podem ativar suplementos configurados para cenários de caixa de correio compartilhada em modos de leitura e composição de mensagens e compromissos.

Pastas compartilhadas

Se a pasta Caixa de Entrada for compartilhada com um delegado, os suplementos estarão disponíveis para o delegado no modo de leitura da mensagem.

Se a pasta Rascunhos também for compartilhada com o delegado, os suplementos estarão disponíveis no modo de composição.

Calendário compartilhado local (novo modelo)

Se o proprietário do calendário compartilhou explicitamente seu calendário com um delegado (toda a caixa de correio pode não ser compartilhada), os suplementos estarão disponíveis para o delegado nos modos de leitura e composição de compromisso.

Calendário compartilhado remoto (modelo anterior)

Se o proprietário do calendário concedeu amplo acesso ao seu calendário (por exemplo, tornou-o editável para uma DL específica ou toda a organização), os usuários poderão ter permissão indireta ou implícita e os suplementos estarão disponíveis para esses usuários nos modos de leitura e composição de compromisso.

Para saber mais sobre onde os suplementos fazem e não são ativados em geral, consulte os itens da caixa de correio disponíveis para a seção suplementos da página de visão geral dos suplementos do Outlook.

Permissões com suporte

A tabela a seguir descreve as permissões que a API JavaScript do Office dá suporte para delegados e usuários de caixas de correio compartilhadas.

Permissão	Valor	Descrição
Leitura	1 (000001)	Pode ler itens.
Gravar	2 (000010)	Pode criar itens.
DeleteOwn	4 (000100)	Pode excluir apenas os itens que eles criaram.
DeleteAll	8 (001000)	Pode excluir todos os itens.
EditOwn	16 (010000)	Pode editar apenas os itens que eles criaram.
EditArAll	32 (100000)	Pode editar quaisquer itens.

Observação

Atualmente, a API dá suporte à obtenção de permissões existentes, mas não à configuração de permissões.

O objeto DelegatePermissions é implementado usando 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 ela estiver definida como 1 , o usuário terá a respectiva permissão. Por exemplo, se o segundo bit da direita for 1, o usuário terá permissão Write . Você pode ver um exemplo de como marcar para obter uma permissão específica na seção Executar uma operação como delegado ou usuário de caixa de correio compartilhada mais adiante neste artigo.

Sincronizar entre clientes de pasta compartilhada

As atualizações de um delegado para a caixa de correio do proprietário geralmente são sincronizadas entre caixas de correio imediatamente.

No entanto, se as operações REST ou Exchange Web Services (EWS) foram usadas para definir uma propriedade estendida em um item, essas alterações poderão levar algumas horas para serem sincronizadas. Em vez disso, recomendamos que você use o objeto CustomProperties e APIs relacionadas para evitar esse atraso. Para saber mais, confira a seção propriedades personalizadas do artigo "Obter e definir metadados em um suplemento do Outlook".

Importante

Em um cenário de delegado, você não pode usar o EWS com os tokens fornecidos atualmente por office.js API.

Configurar o manifesto

Para habilitar pastas compartilhadas e cenários de caixa de correio compartilhada em seu suplemento, você deve habilitar as permissões necessárias no manifesto.

Primeiro, para dar suporte a chamadas REST de um delegado, o suplemento deve solicitar a permissão de caixa de correio de leitura/gravação . A marcação varia dependendo do tipo de manifesto.

• Manifesto XML: defina o <elemento Permissions> como ReadWriteMailbox.
• Manifesto unificado para o Microsoft 365 (versão prévia): defina a propriedade "name" de um objeto na matriz "authorization.permissions.resourceSpecific" como "Mailbox.ReadWrite.User".

Em segundo lugar, habilite o suporte para pastas compartilhadas. A marcação varia dependendo do tipo de manifesto.

Manifesto unificado para o Microsoft 365 (versão prévia do desenvolvedor)

Adicione um objeto adicional à matriz "authorization.permissions.resourceSpecific" e defina sua propriedade "name" como "Mailbox.SharedFolder".

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

Manifesto XML

Defina o elemento SupportsSharedFolders como true no manifesto no elemento DesktopFormFactorpai . No momento, não há suporte para outros fatores de formulário.

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

Executar uma operação como representante ou usuário de caixa de correio compartilhada

Você pode obter as propriedades compartilhadas de um item no modo Compose ou Read chamando o método item.getSharedPropertiesAsync . Isso retorna um objeto SharedProperties que atualmente fornece as permissões do usuário, o endereço de email do proprietário, a URL base da API REST e a caixa de correio de destino.

O exemplo a seguir mostra como obter as propriedades compartilhadas de uma mensagem ou compromisso, marcar se o representante ou usuário da caixa de correio compartilhada tiver permissão Write e fazer uma chamada 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");
                }
              );
            }
          }
        );
      }
    }
  );
}

Dica

Como delegado, você pode usar REST para obter o conteúdo de uma mensagem do Outlook anexada a um item ou postagem de grupo do Outlook.

Manipular a chamada REST em itens compartilhados e não compartilhados

Se você quiser chamar uma operação REST em um item, se o item é compartilhado ou não, você pode usar a getSharedPropertiesAsync API para determinar se o item é compartilhado. Depois disso, você pode construir a URL REST para a operação usando o objeto apropriado.

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

Limitações

Dependendo dos cenários do suplemento, há algumas limitações a serem consideradas ao lidar com situações de pasta compartilhada ou caixa de correio compartilhada.

Modo de composição de mensagens

No modo Compose de Mensagem, getSharedPropertiesAsync não tem suporte em Outlook na Web ou no Windows, a menos que as seguintes condições sejam atendidas.

a. Delegar acesso/pastas compartilhadas

1. O proprietário da caixa de correio inicia uma mensagem. Isso pode ser uma nova mensagem, uma resposta ou um encaminhamento.
2. Eles salvam a mensagem e, em seguida, movem-na de sua própria pasta Rascunhos para uma pasta compartilhada com o delegado.
3. O delegado abre o rascunho da pasta compartilhada e continua compondo.

b. Caixa de correio compartilhada (aplica-se apenas ao Outlook no Windows)

1. Um usuário de caixa de correio compartilhada inicia uma mensagem. Isso pode ser uma nova mensagem, uma resposta ou um encaminhamento.
2. Eles salvam a mensagem e, em seguida, movem-na de sua própria pasta Rascunhos para uma pasta na caixa de correio compartilhada.
3. Outro usuário de caixa de correio compartilhada abre o rascunho da caixa de correio compartilhada e continua compondo.

A mensagem agora está em um contexto compartilhado e suplementos que dão suporte a esses cenários compartilhados podem obter as propriedades compartilhadas do item. Depois que a mensagem é enviada, ela geralmente é encontrada na pasta Itens Enviados do remetente.

REST e EWS

Seu suplemento pode usar REST. Para habilitar o acesso REST à caixa de correio do proprietário ou à caixa de correio compartilhada conforme aplicável, o suplemento deve solicitar a permissão de caixa de correio de leitura/gravação no manifesto. A marcação varia dependendo do tipo de manifesto.

• Manifesto XML: defina o <elemento Permissions> como ReadWriteMailbox.
• Manifesto unificado para o Microsoft 365 (versão prévia): defina a propriedade "name" de um objeto na matriz "authorization.permissions.resourceSpecific" como "Mailbox.ReadWrite.User".

O EWS não tem suporte.

Caixa de correio compartilhada ou usuário oculta de uma lista de endereços

Se um administrador escondeu um usuário ou um endereço de caixa de correio compartilhado de uma lista de endereços como a GAL (lista de endereços global), os itens de email foram abertos no relatório Office.context.mailbox.item da caixa de correio como nulos. Por exemplo, se o usuário abrir um item de email em uma caixa de correio compartilhada oculta da GAL, Office.context.mailbox.item representar esse item de email será nulo.

Confira também

• Permitir que outra pessoa gerencie seu e-mail e seu calendário
• Compartilhamento de calendário no Microsoft 365
• Adicionar uma caixa de correio compartilhada ao Outlook
• Como ordenar elementos de manifesto
• Máscara (computação)
• Operadores bits JavaScript