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

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

Clientes e plataformas com suporte

A tabela a seguir mostra as combinações cliente-servidor compatíveis com esse recurso, incluindo a Atualização Cumulativa mínima necessária, quando aplicável.

Configurações suportadas

As seções a seguir descrevem as configurações para caixas de correio compartilhadas e pastas compartilhadas que dão suporte ao uso de suplementos. As APIs de recursos podem não funcionar conforme o esperado em outras configurações. Selecione a plataforma que você deseja saber como configurar.

Configurar o manifesto

Para implementar cenários de pasta compartilhada e caixa de correio compartilhada em seu suplemento, primeiro você deve configurar o suporte para o recurso em seu manifesto. A marcação varia de acordo com o tipo de manifesto que seu suplemento usa.

"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 the extension point. -->
          </ExtensionPoint>
          ...
        </DesktopFormFactor>
      </Host>
    </Hosts>
    ...
  </VersionOverrides>
</VersionOverrides>
...

Identificar se uma pasta ou caixa de correio é compartilhada

Antes de executar operações em uma pasta compartilhada ou caixa de correio compartilhada, você deve primeiro identificar se a pasta ou caixa de correio atual é compartilhada. Para determinar isso, chame getSharedPropertiesAsync (MessageRead, MessageCompose, AppointmentRead, AppointmentCompose) em uma mensagem ou compromisso no modo de redação ou leitura. Se o item estiver em uma pasta compartilhada ou caixa de correio compartilhada, o método retornará um objeto SharedProperties que fornece as permissões do usuário, o endereço de email do proprietário, a URL base da API REST e o local da caixa de correio de destino.

O exemplo a seguir chama o getSharedPropertiesAsync método para identificar o proprietário da caixa de correio e as permissões do representante ou do usuário da caixa de correio compartilhada.

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 com suporte

A tabela a seguir descreve as permissões para getSharedPropertiesAsync representantes e usuários de caixa de correio compartilhada.

A enumeração DelegatePermissions retornada pela propriedade delegatePermissions é implementada 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 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 tem permissão de gravação .

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

Depois de identificar que o item de email atual está em uma pasta compartilhada ou caixa de correio compartilhada, seu suplemento poderá executar as operações necessárias no item dentro do ambiente compartilhado. Para executar operações em um item em um contexto compartilhado, primeiro você deve configurar a permissão do suplemento no manifesto. Em seguida, use o Microsoft Graph para concluir as operações.

Configurar as permissões do suplemento

Para usar os serviços do Microsoft Graph, um suplemento deve configurar a permissão de caixa de correio de leitura/gravação em seu manifesto. A marcação varia de acordo com o tipo de manifesto que seu suplemento usa.

• Manifesto "authorization.permissions.resourceSpecific"unificado para Microsoft 365: defina a "name" propriedade de um objeto na matriz como "Mailbox.ReadWrite.User".
• Manifesto somente do suplemento: defina o elemento Permissions como ReadWriteMailbox.

Usar o Microsoft Graph

Para implementar seus cenários de pasta compartilhada e caixa de correio compartilhada, use o Microsoft Graph para acessar informações e recursos adicionais da caixa de correio. Por exemplo, você pode usar o Microsoft Graph para obter o conteúdo de uma mensagem do Outlook anexada a uma mensagem em uma caixa de correio em que um usuário tem acesso de representante. Para obter orientações sobre como usar o Microsoft Graph, consulte Visão geral da API de email do Microsoft Graph e do Outlook no Microsoft Graph.

Suporte a suplementos em cenários de pasta compartilhada e caixa de correio compartilhada

A disponibilidade de suplementos em uma pasta compartilhada ou caixa de correio compartilhada varia dependendo do cenário e do cliente Outlook.

Suplementos em cenários de pasta compartilhada

A tabela a seguir descreve a disponibilidade de suplementos em cenários de pasta compartilhada.

Suplementos em cenários de caixa de correio compartilhada

A tabela a seguir descreve a disponibilidade de suplementos em cenários de caixa de correio compartilhada em vários clientes do Outlook. Observe que o comportamento no Outlook na Web pode ser diferente dependendo se a caixa de correio compartilhada é aberta no mesmo painel que a caixa de correio principal do usuário ou em uma guia ou janela separada usando a opção Abrir outra caixa de correio. Da mesma forma, o comportamento no novo Outlook no Windows também pode ser diferente, dependendo se a caixa de correio compartilhada foi adicionada ou promovida como uma conta completa no cliente.

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 Compose de mensagens

No modo de Compose de Mensagem, getSharedPropertiesAsync não é compatível com o Outlook na Web ou no Windows (novo e clássico), a menos que as condições a seguir sejam atendidas.

• Acesso delegado/Pastas compartilhadas

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

• Caixa de correio compartilhada aberta no mesmo painel que a caixa de correio principal do usuário (Web, Windows clássico) ou caixa de correio compartilhada que não foi promovida a conta completa (novo Windows)

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

  Observação

  O getSharedPropertiesAsync método tem suporte nas seguintes plataformas sem condições adicionais.

  • Outlook na Web quando a caixa de correio compartilhada for aberta em uma guia ou janela separada usando a opção Abrir outra caixa de correio.
  • novo Outlook no Windows quando a caixa de correio compartilhada é promovida a uma conta completa.

Depois que essas condições forem atendidas, a mensagem ficará disponível em um contexto compartilhado e os suplementos que dão suporte a esses cenários compartilhados poderão obter as propriedades compartilhadas do item. Depois que a mensagem é enviada, ela geralmente é encontrada na pasta Itens Enviados da caixa de correio pessoal do remetente.

Usuário ou caixa de correio compartilhada oculta de uma lista de endereços

Se um administrador ocultou um usuário ou endereço de caixa de correio compartilhada de uma lista de endereços, como a GAL (lista de endereços global), os itens de email afetados abertos na caixa de correio relatam Office.context.mailbox.item como nulos. Por exemplo, se o usuário abrir um item de email em uma caixa de correio compartilhada que está oculta da GAL, Office.context.mailbox.item representar que o item de email é nulo.

Sincronização entre clientes de pastas compartilhadas

As atualizações de um representante para a caixa de correio do proprietário geralmente são sincronizadas entre as caixas de correio imediatamente. No entanto, se operações do Microsoft Graph foram usadas para definir uma propriedade estendida em um item, essas alterações podem levar algum tempo para sincronizar. Para evitar um atraso, recomendamos que você use o objeto CustomProperties e as APIs relacionadas. Para saber mais, confira a guia "Propriedades personalizadas" de Obter e definir metadados em um suplemento do Outlook.

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
• Visão geral do Microsoft Graph