Acessar contatos como um representante usando o EWS no Exchange

Artigo
03/29/2023

Saiba como acessar contatos como delegado usando a API Gerenciada do EWS ou o EWS no Exchange.

Você pode usar a API Gerenciada do EWS ou o EWS para dar a um usuário acesso à pasta Contatos do proprietário de uma caixa de correio. Em seguida, o delegado pode criar contatos em nome do proprietário da caixa de correio e recuperar, atualizar e excluir contatos da pasta Contatos do proprietário da caixa de correio, dependendo de suas permissões.

Como delegado, você usa os mesmos métodos e operações para acessar a pasta Contatos do proprietário de uma caixa de correio que você usa para acessar sua própria pasta Contatos. A principal diferença é que você precisa usar o acesso explícito para localizar ou criar um item de contato e, depois de identificar a ID do item, você pode usar o acesso implícito para obter, atualizar ou excluir o item.

Tabela 1. Métodos de API Gerenciada do EWS e operações EWS para acessar um contato como delegado

Se você quiser...	Use este método de API Gerenciada do EWS…	Use esta operação do EWS…
Criar um contato como delegado	Item.Salvar onde o parâmetro FolderId fornece acesso explícito à pasta Contatos do proprietário da caixa de correio	CreateItem em que o elemento Mailbox especifica o EmailAddress do proprietário da caixa de correio
Criar vários contatos como delegado	ExchangeService.CreateItems em que o parâmetro FolderId fornece acesso explícito à pasta Contatos do proprietário da caixa de correio	CreateItem em que o elemento Mailbox especifica o EmailAddress do proprietário da caixa de correio
Resolver um contato como delegado	ExchangeService.ResolveName em que o parâmetro FolderId fornece acesso explícito à pasta Contatos do proprietário da caixa de correio	ResolveNames em que o elemento Caixa de Correio especifica o EmailAddress do proprietário da caixa de correio
Procure ou localize um contato como delegado	ExchangeService.FindItems em que o parâmetro FolderId fornece acesso explícito à pasta Contatos do proprietário da caixa de correio	FindItem em que o elemento Caixa de Correio especifica o EmailAddress do proprietário da caixa de correio
Obter um contato como delegado	Contact.Bind	GetItem
Atualizar um contato como delegado	Contact.Bind seguido por Contact.Update	GetItem seguido por UpdateItem
Excluir um contato como delegado	Contact.Bind seguido por Contact.Delete	GetItem seguido por DeleteItem

Observação

Nos exemplos de código deste artigo, primary@contoso.com está o proprietário da caixa de correio.

Tarefas de pré-requisito

Antes que um usuário possa acessar a pasta Contatos do proprietário da caixa de correio como delegado, o usuário deve ser adicionado como um delegado com permissões para a pasta Contatos do proprietário da caixa de correio.

Criar um contato como delegado usando a API Gerenciada do EWS

A API Gerenciada do EWS permite que você use o objeto de serviço para o usuário delegado criar contatos para o proprietário da caixa de correio. Este exemplo mostra como usar o método Salvar para criar uma reunião e enviar solicitações de reunião aos participantes.

Este exemplo pressupõe que o serviço seja um objeto ExchangeService válido para o delegado e que o delegado recebeu as permissões apropriadas para a pasta Contatos do proprietário da caixa de correio.

 public static void DelegateAccessCreateContact(ExchangeService service)
{
    // Create the contact.
    Contact contact = new Contact(service);
    // Specify the name and how the contact should be filed.
    contact.GivenName = "Brian";
    contact.MiddleName = "David";
    contact.Surname = "Johnson";
    contact.FileAsMapping = FileAsMapping.SurnameCommaGivenName;
    // Specify the company name.
    contact.CompanyName = "Contoso";
    // Specify the business, home, and car phone numbers.
    contact.PhoneNumbers[PhoneNumberKey.BusinessPhone] = "425-555-0110";
    contact.PhoneNumbers[PhoneNumberKey.HomePhone] = "425-555-0120";
    contact.PhoneNumbers[PhoneNumberKey.CarPhone] = "425-555-0130";
    // Specify two email addresses.
    contact.EmailAddresses[EmailAddressKey.EmailAddress1] = 
        new EmailAddress("brian_1@contoso.com");
    contact.EmailAddresses[EmailAddressKey.EmailAddress2] = 
        new EmailAddress("brian_2@contoso.com");
    // Save the contact in the mailbox owner's Contacts folder.
    // This method call results in a CreateItem call to EWS. 
    // The contact identifier contains the context for the mailbox owner's 
    // Contact folder. Any additional actions take on this contact will 
    // be performed in the mailbox owner's mailbox. 
    contact.Save(new FolderId(WellKnownFolderName.Contacts, 
        "primary@contoso.com"));
    // Verify that the contact was created.
    // This method call results in a GetItem call to EWS
    // to load the display name property on the contact. 
    contact.Load(new PropertySet (ContactSchema.DisplayName));
    Console.WriteLine("\nContact created: " + contact.DisplayName + "\n");
}

Observe que, ao salvar o item, a chamada do método Salvar deve identificar a pasta Contatos do proprietário da caixa de correio. Se a pasta Contatos do proprietário da caixa de correio não for especificada, a solicitação de reunião será salva na pasta Contatos do delegado e não na pasta Contatos do proprietário da caixa de correio. Você pode incluir a pasta Contatos do proprietário da caixa de correio na chamada do método Salvar de duas formas. Recomendamos que você crie uma instância do objeto FolderId usando o WellKnownFolderName e o endereço SMTP do proprietário da caixa de correio.

contact.Save(new FolderId(WellKnownFolderName.Contacts, "primary@contoso.com"));

No entanto, você também pode Associar à pasta Contatos primeiro e, em seguida, usar a ID da pasta na chamada do método Salvar . No entanto, lembre-se de que isso cria uma chamada EWS extra.

    // Identify the mailbox owner's SMTP address 
    // and bind to their Contacts folder.
    Mailbox primary = new Mailbox("primary@contoso.com"); 
    Folder primaryContacts = Folder.Bind(service, new FolderId(WellKnownFolderName.Contacts, primary)); 
…
    // Save the contact to the mailbox owner's Contacts folder.
    meeting.Save(primaryContacts.Id);

Criar um contato como delegado usando o EWS

O EWS permite que você use o objeto de serviço para o usuário delegado criar itens de contato para o proprietário da caixa de correio. Este exemplo mostra como usar a operação CreateItem para criar um contato.

Essa também é a solicitação XML que a API Gerenciada do EWS envia quando você usa o método Save para criar um contato.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2007_SP1" />
  </soap:Header>
  <soap:Body>
    <m:CreateItem MessageDisposition="SaveOnly">
      <m:SavedItemFolderId>
        <t:DistinguishedFolderId Id="contacts">
          <t:Mailbox>
            <t:EmailAddress>primary@contoso.com</t:EmailAddress>
          </t:Mailbox>
        </t:DistinguishedFolderId>
      </m:SavedItemFolderId>
      <m:Items>
        <t:Contact>
          <t:FileAsMapping>LastCommaFirst</t:FileAsMapping>
          <t:GivenName>Brian</t:GivenName>
          <t:MiddleName>David</t:MiddleName>
          <t:CompanyName>Contoso</t:CompanyName>
          <t:EmailAddresses>
            <t:Entry Key="EmailAddress1">brian_1@contoso.com</t:Entry>
            <t:Entry Key="EmailAddress2">brian_2@contoso.com</t:Entry>
          </t:EmailAddresses>
          <t:PhoneNumbers>
            <t:Entry Key="BusinessPhone">425-555-0110</t:Entry>
            <t:Entry Key="HomePhone">425-555-0120</t:Entry>
            <t:Entry Key="CarPhone">425-555-0130</t:Entry>
          </t:PhoneNumbers>
          <t:Surname>Johnson</t:Surname>
        </t:Contact>
      </m:Items>
    </m:CreateItem>
  </soap:Body>
</soap:Envelope>

O servidor responde à solicitação CreateItem com uma mensagem CreateItemResponse que inclui um valor de elemento ResponseCode do NoError, que indica que o contato foi criado com êxito. A resposta também contém a ID do item do contato recém-criado.

Resolver um contato como delegado usando a API Gerenciada do EWS

Para encontrar um contato com base em um nome ou termo possivelmente ambíguo, você deve usar um dos métodos ExchangeService.ResolveName que inclui um parâmetro FolderId , para que você possa especificar a pasta Contatos do proprietário da caixa de correio.

private static void DelegateAccessResolveContacts(ExchangeService service)
{
    // Create a list to store folders to search.
    List<FolderId> folders = new List<FolderId>();
   
    // Add the mailbox owner's folder to the list.
    folders.Add(new FolderId(WellKnownFolderName.Contacts, 
        "primary@contoso.com"));
    
    // Resolve the ambiguous name "Johnson".
    // This method call results in a ResolveNames call to EWS.
    NameResolutionCollection resolvedNames = service.ResolveName(
        "johnson", folders, ResolveNameSearchLocation.ContactsOnly, true);
    // Output the list of candidate email addresses and contact names.
    foreach (NameResolution nameRes in resolvedNames)
    {
        Console.WriteLine("Contact e-mail address: " + nameRes.Mailbox.Address);
        Console.WriteLine("Contact ID: " + nameRes.Mailbox.Id);
    }
}

Depois que a chamada do método ResolveNames retornar uma resposta com uma ID, você poderá obter, atualizar ou excluir o contato usando a ID e o acesso implícito e não precisar especificar o endereço SMTP do proprietário da caixa de correio.

Resolver um contato como delegado usando o EWS

O EWS permite que você use o objeto de serviço para o usuário delegado resolver nomes parciais na pasta Contatos do proprietário da caixa de correio. Este exemplo mostra como usar a operação ResolveNames para encontrar reuniões na pasta Contatos do proprietário da caixa de correio que contém a palavra "johnson".

Essa também é a solicitação XML que a API Gerenciada do EWS envia quando você usa o método ResolveName para resolver um contato.

 <?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2007_SP1" />
  </soap:Header>
  <soap:Body>
    <m:ResolveNames ReturnFullContactData="true"
                    SearchScope="Contacts">
      <m:ParentFolderIds>
        <t:DistinguishedFolderId Id="contacts">
          <t:Mailbox>
            <t:EmailAddress>primary@contoso.com</t:EmailAddress>
          </t:Mailbox>
        </t:DistinguishedFolderId>
      </m:ParentFolderIds>
      <m:UnresolvedEntry>johnson</m:UnresolvedEntry>
    </m:ResolveNames>
  </soap:Body>
</soap:Envelope>

O servidor responde à solicitação ResolveNames com uma mensagem ResolveNamesResponse que inclui um valor de elemento ResponseCode de NoError, que indica que a operação foi concluída com êxito e encontrou apenas um resultado, ou ErrorNameResolutionMultipleResults se vários resultados foram encontrados - que é o que é mostrado no terceiro exemplo de código com base no contato Criar um contato como delegado usando a API Gerenciada do EWS. A resposta também contém o ItemId de cada resultado.

O valor do elemento ItemId foi reduzido para legibilidade.

 <?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="https://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <h:ServerVersionInfo MajorVersion="15"
                         MinorVersion="0"
                         MajorBuildNumber="893"
                         MinorBuildNumber="17"
                         Version="V2_10"
                         xmlns:h="https://schemas.microsoft.com/exchange/services/2006/types"
                         xmlns="https://schemas.microsoft.com/exchange/services/2006/types"
                         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
  </s:Header>
  <s:Body>
    <m:ResolveNamesResponse xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages"
                            xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
      <m:ResponseMessages>
        <m:ResolveNamesResponseMessage ResponseClass="Warning">
          <m:MessageText>Multiple results were found.</m:MessageText>
          <m:ResponseCode>ErrorNameResolutionMultipleResults</m:ResponseCode>
          <m:DescriptiveLinkKey>0</m:DescriptiveLinkKey>
          <m:ResolutionSet TotalItemsInView="2"
                           IncludesLastItemInRange="true">
            <t:Resolution>
              <t:Mailbox>
                <t:Name>brian_1@contoso.com</t:Name>
                <t:EmailAddress>brian_1@contoso.com</t:EmailAddress>
                <t:RoutingType>SMTP</t:RoutingType>
                <t:MailboxType>Contact</t:MailboxType>
                <t:ItemId Id="iMihAAA="
                          ChangeKey="EQAAABYAAADOilbYa8KaT7ZgMoTz2P+hAAABiPQo" />
              </t:Mailbox>
            </t:Resolution>
            <t:Resolution>
              <t:Mailbox>
                <t:Name>brian_2@contoso.com</t:Name>
                <t:EmailAddress>brian_2@contoso.com</t:EmailAddress>
                <t:RoutingType>SMTP</t:RoutingType>
                <t:MailboxType>Contact</t:MailboxType>
                <t:ItemId Id="iMihAAA="
                          ChangeKey="EQAAABYAAADOilbYa8KaT7ZgMoTz2P+hAAABiPQo" />
              </t:Mailbox>
            </t:Resolution>
          </m:ResolutionSet>
        </m:ResolveNamesResponseMessage>
      </m:ResponseMessages>
    </m:ResolveNamesResponse>
  </s:Body>
</s:Envelope>

Agora que você tem o ItemId para os contatos que correspondem ao nome ambíguo, você pode Obter, atualizar ou excluir itens de contato como delegado usando o EWS usando o ItemId e o acesso implícito e você não precisa especificar o endereço SMTP do proprietário da caixa de correio.

Obter, atualizar ou excluir itens de contato como delegado usando a API Gerenciada do EWS

Você pode usar a API Gerenciada do EWS para obter, atualizar ou excluir um contato da mesma forma que executa essas ações quando não estiver usando o acesso de delegado. A única diferença é que o objeto de serviço é para o usuário delegado. A ID do item incluída na chamada do método Bind identifica exclusivamente o item no repositório de caixas de correio, na pasta Contatos do proprietário da caixa de correio.

Tabela 2. Métodos de API Gerenciada do EWS trabalhando com um contato como delegado

Tarefa	Método da API Gerenciada do EWS	Exemplo de código
Obter um contato	Vincular	Gerenciar um item usando a API Gerenciada do EWS
Atualizar um contato	Bind seguido por Update	Atualizar um item usando a API Gerenciada do EWS
Excluir um contato	Bind seguido por Delete	Excluir um item usando a API Gerenciada do EWS

Obter, atualizar ou excluir itens de contato como delegado usando o EWS

Você pode usar o EWS para obter, atualizar ou excluir um contato de reunião ou compromisso da mesma forma que executa essas ações quando não estiver usando o acesso de delegado. A única diferença é que o objeto de serviço é para o usuário delegado. A ID do item incluída na solicitação GetItem identifica exclusivamente o item no repositório de caixas de correio, na pasta Contatos do proprietário da caixa de correio.

Tabela 3. Operações EWS para trabalhar com um contato como delegado

Tarefa	Operação do EWS	Amostra
Obter um contato	GetItem	Get um item usando EWS
Atualizar um contato	GetItem seguido por UpdateItem	Atualizar um item usando o EWS
Excluir um contato	GetItem seguido por DeleteItem	Excluir um item usando o EWS