Acesso de representante e EWS no Exchange

Descubra como usar a API Gerenciada do EWS e o EWS no Exchange para fornecer acesso de representante às caixas de correio dos usuários.

Você pode permitir que os usuários acessem as caixas de correio de outros usuários de três maneiras:

• Adicionando representantes e especificando permissões para cada representante.

• Modificando as permissões de pasta diretamente.

• Usando a representação.

A delegação e as permissões da pasta são melhores quando você concede acesso a apenas alguns usuários, pois tem que adicionar permissões individualmente a cada caixa de correio. A representação é a melhor opção quando você lida com várias caixas de correio, porque você pode facilmente habilitar uma conta de serviço para acessar todas as caixas de correio em um banco de dados. A Figura 1 mostra algumas das diferenças entre cada tipo de acesso.

Figura 1. Maneiras de acessar as caixas de correio de outros usuários

Quando se trata de enviar reuniões de email ou agendamento, os delegados podem receber permissões de "enviar em nome de", de modo que o destinatário de um email ou uma solicitação de reunião que foi enviada por um delegado verá " delegado em nome do proprietário da caixa de correio " quando receberem o email ou a solicitação de reunião no Outlook. A inclusão do texto "enviar em nome de" é um detalhe de implementação do cliente que pode ser criado usando os valores "de" e "remetente". O valor “de” indica o proprietário da caixa de correio e o valor "remetente" indica o representante que enviou o e-mail. Se uma conta de serviço representando um usuário enviar um e-mail ou agendar uma reunião para o proprietário da caixa de correio, a mensagem será "enviada como" o proprietário da caixa de correio. Não tem como o destinatário saber que o e-mail foi enviado pela conta de serviço. Os usuários que recebem permissões de pasta, mas não acesso de representante, não podem "enviar como" ou "enviar em nome de" um proprietário de caixa de correio. Têm acesso às pastas de caixa de correio e talvez possam criar itens nas pastas, mas não podem enviar os itens.

Quando é apropriado modificar as permissões de pasta diretamente? Geralmente, quando você quer fornecer acesso a uma pasta para um usuário, mas não quer conceder ao usuário permissões "enviar em nome de"; quando seus requisitos de permissões não são mapeados para os valores de enumeração de API Gerenciada do EWS DelegateFolderPermissionLevel ou valores do elemento EWS PermissionLevel; ou quando você quer fornecer ao usuário acesso a uma única pasta personalizada.

Se você só precisar modificar as permissões de pasta para atingir seu objetivo e não precisar adicionar um representante (ou seja, não precisar de permissões "enviar em nome de"), consulte Configurar permissões de pasta para outro usuário usando o EWS no Exchange.

Observe que você também pode usar o Outlook ou o PowerShell do Exchange Server (Shell de Gerenciamento do Exchange) para configurar o acesso do representante.

Como funciona o acesso do representante?

O acesso do representante permite que os usuários acessem algumas ou todas as pastas do proprietário da caixa de correio e atuem em nome do proprietário da caixa de correio. O proprietário da caixa de correio pode ser um usuário ou um recurso, como uma sala de conferência. Por exemplo, um recepcionista pode receber permissões de representante para a pasta de calendário de uma sala de conferência para lidar com solicitações de reserva. Você pode usar a API Gerenciada do EWS ou o EWS para permitir que o proprietário da caixa de correio ou um administrador adicionem um representante, especifiquem quais pastas o representante pode acessar e, em seguida, especifiquem permissões para essa pasta. Os representantes podem receber permissão de acesso às seguintes pastas:

• Calendário

• Tarefas

• Caixa de Entrada

• Contatos

• Observações

• Diário

Quando tem acesso de representante a uma ou mais dessas pastas, um usuário pode criar, obter, atualizar, excluir, copiar e pesquisar itens nessa pasta e em pastas filhas, dependendo do conjunto de permissões da pasta. A maneira como o aplicativo executa essas ações depende de se um acesso explícito ou implícito é necessário.

Delegar permissões

Quando adiciona um representante a uma caixa de correio, um administrador ou proprietário de caixa de correio também podem definir o nível de permissão para uma ou mais pastas. Se um nível de permissão não for definido para uma pasta, o valor da permissão será definido como o valor padrão Nenhum. Vários usuários podem ter o mesmo nível de permissão em uma pasta e os usuários podem ter níveis de permissão diferentes para pastas diferentes. Se estiver usando a API Gerenciada do EWS, use a propriedade DelegateUser.Permissions, que contém um dos valores de enumeração DelegateFolderPermissionLevel para cada pasta, para definir as permissões de representante nas pastas. Se estiver usando o EWS, use o elemento DelegatePermissions para definir permissões de representante e o elemento PermissionLevel para definir o nível da permissão.

Tabela 2. Níveis de permissão delegado

A propriedade DelgateUser.ViewPrivateItems da API Gerenciada do EWS e a ViewPrivateItems do EWS é uma configuração global que afeta todas as pastas do proprietário da caixa de correio, incluindo todas as pastas de E-mail, Contatos, Calendário, Tarefas, Anotações e Diário. Você não pode permitir o acesso a itens privados em apenas uma pasta.

Acesso explícito

Em poucas palavras, o acesso explícito é a forma de entrada para os representantes executarem ações em pastas ou itens de um proprietário de caixa de correio. O acesso explícito é concedido a um representante quando ele inclui o nome de pasta bem conhecido para a pasta de um proprietário de caixa de correio juntamente com o endereço SMTP do proprietário da caixa de correio em uma solicitação ao servidor. O acesso é explícito porque a solicitação do representante declara explicitamente que o contexto para o método ou operação é a caixa de correio do proprietário da caixa de correio, e não a caixa de correio do representante.

O acesso explícito define o contexto para todos os métodos ou operações executadas nas pastas ou itens desse ponto em diante. Todas as IDs de item e pasta retornadas quando um acesso explícito está configurado se autoidentificam exclusivamente como pertencentes ao proprietário da caixa de correio (embora não estejam em nenhum formato legível por humanos). Assim, o aplicativo não precisa especificar o endereço SMTP do proprietário da caixa de correio todas as vezes, já que o contexto está oculto nos identificadores. Após um item ou pasta terem sido identificados, um representante na verdade usa um acesso implícito para modificar o item. A figura a seguir mostra o processo de obter um acesso explícito e implícito.

Figura 2. Solicitando acesso explícito e implícito a um item ou pasta

Você pode configurar um acesso explícito em muitos cenários diferentes. Essencialmente, sempre que estiver enviando uma ID de pasta em um método ou operação você poderá configurar um acesso explícito. Isso pode incluir localizar pastas, localizar compromissos, obter itens, encontrar conversas e assim por diante.

Acesso explícito e a API Gerenciada do EWS

Você pode iniciar o acesso explícito de representante usando qualquer um dos seguintes métodos sobrecarregados que usam um parâmetro de entrada FolderId para identificar a pasta de destino:

• Folder.Bind

• ExchangeService.FindItems

• ExchangeService.FindAppointments

• ExchangeService.FindFolders

• E muito mais!

Você pode usar o parâmetro FolderId em cada um desses métodos para identificar a pasta de destino do proprietário da caixa de correio da seguinte maneira.

new FolderId(WellKnownFolderName.Calendar, "primary@contoso.com");

Por exemplo, para vincular à pasta Calendário, o método FolderId nesse método de Vinculação especifica o nome da pasta bem conhecido e o endereço SMTP do proprietário da caixa de correio.

CalendarFolder calendar = CalendarFolder.Bind(service, new FolderId(WellKnownFolderName.Calendar, "primary@contoso.com"), new PropertySet());

Ao especificar o nome de pasta bem conhecido e o endereço SMTP, o representante pode se vincular à pasta Calendário do proprietário da caixa de correio e, consequentemente, obter acesso explícito à pasta. Todas as solicitações subsequentes para o acesso implícito aos itens na pasta irão depender do contexto retornado nas IDs do item e nas IDs da pasta. Essencialmente, os identificadores contêm o contexto para as chamadas de acesso implícitas do representante. Ou, para recuperar a ID de item de um item que cumpra critérios específicos, use o seguinte.

FindItemsResults<Item> results = service.FindItems(new FolderId(WellKnownFolderName.Calendar, "primary@contoso.com"), filter, view);

Nesse caso, a ID do item é retornada e, em seguida, o representante pode usar o acesso implícito para fazer alterações no item usando a ID do item.

Você não precisa iniciar o acesso explícito novamente até precisar de uma ID de item ou de uma ID de pasta que ainda não acessou por meio do acesso explícito existente.

Acesso explícito e o EWS

Você pode iniciar o acesso explícito usando as operações GetFolder, FindItem ou FindFolder. Essas operações fornecem a opção de usar o elemento DistinguishedFolderId para identificar a pasta de destino. O elemento DistinguishedFolderId tem um único elemento filho opcional, o elemento Mailbox. O elemento Mailbox, quando usado como um filho do elemento DistinguishedFolderId, especifica a caixa de correio que o representante deve acessar. Se o usuário que estiver chamando tiver permissão para acessar a pasta do proprietário da caixa de correio, a resposta conterá um conjunto de identificadores para itens ou pastas nessa caixa de correio. Os identificadores de item e de pasta retornados na resposta podem ser usados para o acesso implícito do representante.

Acesso implícito

O acesso implícito é usado depois que um representante já recuperou a ID de um item ou pasta na caixa de correio do proprietário da caixa de correio e deseja atualizar, excluir ou copiar o item. Quando o representante usa essa ID de item ou de pasta em uma solicitação, as alterações no item são feitas na caixa de correio do proprietário da caixa de correio. O representante não precisa incluir o endereço SMTP do proprietário da caixa de correio.

Por exemplo, quando souber a ID de uma das pastas do proprietário da caixa de correio, o representante pode executar uma operação FindItem nessa pasta usando a ID da pasta, sem identificar explicitamente a caixa de correio do proprietário da caixa de correio. Nessa altura, o representante pode executar ações na pasta do proprietário da caixa de correio usando as IDs retornadas nas respostas.

Acesso implícito e a API Gerenciada do EWS

Se uma ID de item foi recuperada pelo método FindItems, essa ID de item poderá ser usada em uma chamada do método Item.Bind subsequente para vinculá-la ao item. Em seguida, você pode chamar o método Item.Update, Item.Delete ou Item.Copy — ou qualquer chamada de método que requeira uma ID de item — conforme necessário para executar sua tarefa. Desde que o representante tenha as permissões apropriadas para a pasta que contém o item (e, se for o caso, para a pasta para a qual o item está migrando), o representante poderá fazer alterações de acordo com seus níveis de permissão.

Acesso implícito e o EWS

Se uma ID de item foi recuperada pela operação FindItem, essa ID de item poderá ser usada em operações GetItem subsequentes para vinculá-la ao item. Em seguida, você pode chamar a operação UpdateItem, DeleteItem ou CopyItem — ou qualquer operação que exija uma ID de item — conforme necessário para executar sua tarefa. Desde que o representante tenha as permissões apropriadas para a pasta que contém o item (e, se for o caso, para a pasta para a qual o item está migrando), o representante poderá fazer alterações de acordo com seus níveis de permissão.

Nesta seção

• Adicionar e remover representantes usando o EWS no Exchange

• Acessar um calendário como um representante usando o EWS no Exchange

• Acessar contatos como um representante usando o EWS no Exchange

• Acessar o e-mail como um representante usando o EWS no Exchange

• Configurar permissões de pasta para outro usuário usando o EWS no Exchange

• Como lidar com erros relacionados à delegação de representantes no EWS no Exchange

Confira também

• Desenvolver clientes do serviço web para o Exchange

• Permitir que outra pessoa gerencie seu e-mail e seu calendário

• Adicionar MailboxPermission