Acessar contatos como um representante usando o EWS no ExchangeAccess contacts as a delegate by using EWS in Exchange

Saiba como acessar contatos como um representante usando a API gerenciada do EWS ou o EWS no Exchange.Learn how to access contacts as a delegate by using the EWS Managed API or EWS in Exchange.

Você pode usar a API gerenciada do EWS ou o EWS para conceder a um usuário acesso a uma pasta de contatos do proprietário da caixa de correio.You can use the EWS Managed API or EWS to give a user access to a mailbox owner's Contacts folder. O representante pode então criar contatos em nome do proprietário da caixa de correio e recuperar, atualizar e excluir contatos da pasta de contatos do proprietário da caixa de correio, dependendo de suas permissões.The delegate can then create contacts on behalf of the mailbox owner, and retrieve, update, and delete contacts from the mailbox owner's Contacts folder, depending on their permissions.

Como representante, você usa os mesmos métodos e operações para acessar a pasta de contatos do proprietário da caixa de correio que você usa para acessar sua própria pasta de contatos.As a delegate, you use the same methods and operations to access a mailbox owner's Contacts folder that you use to access your own Contacts folder. A principal diferença é que você precisa usar o acesso explícito para localizar ou criar um item de contato e depois depois de identificar a ID do item, você pode usar o acesso implícito para obter, atualizar ou excluir o item.The main difference is that you have to use explicit access to find or create a contact item, and then after you identify the item ID, you can use implicit access to get, update, or delete the item.

Tabela 1. Métodos da API gerenciada do EWS e operações do EWS para acessar um contato como um representanteTable 1. EWS Managed API methods and EWS operations for accessing a contact as a delegate

Se você quiser...If you want to… Use este método de API gerenciada do EWS...Use this EWS Managed API method… Use esta operação do EWS...Use this EWS operation…
Criar um contato como representanteCreate a contact as a delegate
Item. Save onde o parâmetro FolderId fornece acesso explícito à pasta de contatos do proprietário da caixa de correioItem.Save where the FolderId parameter provides explicit access to the mailbox owner's Contacts folder
CreateItem onde o elemento Mailbox especifica o EmailAddress do proprietário da caixa de correioCreateItem where the Mailbox element specifies the EmailAddress of the mailbox owner
Criar vários contatos como um representanteCreate multiple contacts as a delegate
ExchangeService. CreateItems onde o parâmetro FolderId fornece acesso explícito à pasta de contatos do proprietário da caixa de correioExchangeService.CreateItems where the FolderId parameter provides explicit access to the mailbox owner's Contacts folder
CreateItem onde o elemento Mailbox especifica o EmailAddress do proprietário da caixa de correioCreateItem where the Mailbox element specifies the EmailAddress of the mailbox owner
Resolver um contato como representanteResolve a contact as a delegate
ExchangeService. ResolveName onde o parâmetro FolderId fornece acesso explícito à pasta de contatos do proprietário da caixa de correioExchangeService.ResolveName where the FolderId parameter provides explicit access to the mailbox owner's Contacts folder
ResolveNames onde o elemento Mailbox especifica o EmailAddress do proprietário da caixa de correioResolveNames where the Mailbox element specifies the EmailAddress of the mailbox owner
Procurar ou localizar um contato como representanteSearch for or find a contact as a delegate
ExchangeService. FindItems onde o parâmetro FolderId fornece acesso explícito à pasta de contatos do proprietário da caixa de correioExchangeService.FindItems where the FolderId parameter provides explicit access to the mailbox owner's Contacts folder
FindItem onde o elemento Mailbox especifica o EmailAddress do proprietário da caixa de correioFindItem where the Mailbox element specifies the EmailAddress of the mailbox owner
Obter um contato como representanteGet a contact as a delegate
Contato. bindContact.Bind
GetItemGetItem
Atualizar um contato como representanteUpdate a contact as a delegate
Contato. bind seguido por Contact. UpdateContact.Bind followed by Contact.Update
GetItem seguido por UpdateItemGetItem followed by UpdateItem
Excluir um contato como representanteDelete a contact as a delegate
Contato. bind seguido por Contact. DeleteContact.Bind followed by Contact.Delete
GetItem seguido por DeleteItemGetItem followed by DeleteItem

Observação

Nos exemplos de código deste artigo, primary@contoso.com é o proprietário da caixa de correio.In the code examples in this article, primary@contoso.com is the mailbox owner.

Tarefas de pré-requisitoPrerequisite tasks

Antes que um usuário possa acessar a pasta de contatos do proprietário da caixa de correio como um representante, o usuário deve ser adicionado como um representante com permissões para a pasta de contatos do proprietário da caixa de correio.Before a user can access the mailbox owner's Contacts folder as a delegate, the user must be added as a delegate with permissions to the mailbox owner's Contacts folder.

Criar um contato como um representante usando a API gerenciada do EWSCreate a contact as a delegate by using the EWS Managed API

A API gerenciada do EWS permite que você use o objeto de serviço para que o usuário delegado crie contatos para o proprietário da caixa de correio.The EWS Managed API enables you to use the service object for the delegate user to create contacts for the mailbox owner. Este exemplo mostra como usar o método Save para criar uma reunião e enviar solicitações de reunião para os participantes.This example shows how to use the Save method to create a meeting and send meeting requests to the attendees.

Este exemplo pressupõe que o serviço é um objeto ExchangeService válido para o representante e que o representante recebeu as permissões apropriadas para a pasta de contatos do proprietário da caixa de correio.This example assumes that service is a valid ExchangeService object for the delegate and that the delegate has been granted the appropriate permissions for the mailbox owner's Contacts folder.

 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, quando você salva o item, a chamada do método Save deve identificar a pasta de contatos do proprietário da caixa de correio.Note that when you save the item, the Save method call must identify the mailbox owner's Contacts folder. Se a pasta de contatos do proprietário da caixa de correio não for especificada, a solicitação de reunião será salva na pasta contatos do representante e não na pasta contatos do proprietário da caixa de correio.If the mailbox owner's Contacts folder is not specified, the meeting request gets saved to the delegate's Contacts folder and not the mailbox owner's Contacts folder. Você pode incluir a pasta de contatos do proprietário da caixa de correio na chamada do método Save de duas vias.You can include the mailbox owner's Contacts folder in the Save method call in two way. Recomendamos que você instancie uma nova instância do objeto FolderId usando o WellKnownFolderName e o endereço SMTP do proprietário da caixa de correio.We recommend that you instantiate a new instance of the FolderId object by using the WellKnownFolderName and the SMTP address of the mailbox owner.

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

No entanto, você também pode vincular a pasta contatos primeiro e, em seguida, usar a ID da pasta na chamada do método Save .However, you can also Bind to the Contacts folder first, and then use the ID of the folder in the Save method call. No entanto, lembre-se de que isso cria uma chamada EWS extra.Be aware, however, that this creates an extra EWS call.

    // 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 um representante usando o EWSCreate a contact as a delegate by using EWS

O EWS permite que você use o objeto de serviço para que o usuário delegado crie itens de contato para o proprietário da caixa de correio.EWS enables you to use the service object for the delegate user to create contact items for the mailbox owner. Este exemplo mostra como usar a operação CreateItem para criar um contato.This example shows how to use the CreateItem operation to create a contact.

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.This is also the XML request that the EWS Managed API sends when you use the Save method to create a contact.

<?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 de NOERROR, que indica que o contato foi criado com êxito.The server responds to the CreateItem request with a CreateItemResponse message that includes a ResponseCode element value of NoError, which indicates that the contact was created successfully. A resposta também contém a ID do item do contato recém-criado.The response also contains the item ID of the newly created contact.

Resolver um contato como um representante usando a API gerenciada do EWSResolve a contact as a delegate by using the EWS Managed API

Para localizar 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.To find a contact based on a possibly ambiguous name or term, you must use one of the ExchangeService.ResolveName methods that includes a FolderId parameter, so that you can specify the mailbox owner's Contacts folder.

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);
    }
}

Após a chamada do método ResolveNames retornar uma resposta com uma ID, você pode obter, atualizar ou excluir o contato usando a ID e o acesso implícito — e não precisa especificar o endereço SMTP do proprietário da caixa de correio.After the ResolveNames method call returns a response with an ID, you can get, update or delete the contact using the ID and implicit access—and you do not need to specify the mailbox owner's SMTP address.

Resolver um contato como um representante usando o EWSResolve a contact as a delegate by using EWS

O EWS permite que você use o objeto de serviço do usuário delegado para resolver nomes parciais na pasta contatos do proprietário da caixa de correio.EWS enables you to use the service object for the delegate user to resolve partial names in the mailbox owner's Contacts folder. Este exemplo mostra como usar a operação ResolveNames para localizar reuniões na pasta de contatos do proprietário da caixa de correio que contêm a palavra "Johnson".This example shows how to use the ResolveNames operation to find meetings in the mailbox owner's Contacts folder that contain the word "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.This is also the XML request that the EWS Managed API sends when you use the ResolveName method to resolve a contact.

 <?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 que encontrou apenas um resultado, ou ErrorNameResolutionMultipleResults se vários resultados forem encontrados, o que é mostrado no terceiro exemplo de código com base no contato criar um contato como um representante usando a API gerenciada do EWS.The server responds to the ResolveNames request with a ResolveNamesResponse message that includes a ResponseCode element value of NoError, which indicates that the operation completed successfully and found only one result, or ErrorNameResolutionMultipleResults if multiple results were found - which is what's shown in third code example based on the contact Create a contact as a delegate by using the EWS Managed API. A resposta também contém o ItemId de cada resultado.The response also contains the ItemId of each result.

O valor do elemento ItemId foi reduzido para legibilidade.The value of the ItemId element has been shortened for readability.

 <?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 correspondam ao nome ambíguo, é possível obter, atualizar ou excluir itens de contato como um representante usando o EWS usando o ItemId e o acesso implícito — e não é necessário especificar o endereço SMTP do proprietário da caixa de correio.Now that you have the ItemId for the contacts that match the ambiguous name, you can Get, update, or delete contact items as a delegate by using EWS by using the ItemId and implicit access—and you do not need to specify the mailbox owner's SMTP address.

Obter, atualizar ou excluir itens de contato como um representante usando a API gerenciada do EWSGet, update, or delete contact items as a delegate by using the EWS Managed API

Você pode usar a API gerenciada do EWS para obter, atualizar ou excluir um contato da mesma maneira que executará essas ações quando não estiver usando o acesso de representante.You can use the EWS Managed API to get, update, or delete a contact in the same way that you perform these actions when you're not using delegate access. A única diferença é que o objeto de serviço é para o usuário delegado.The only difference is that the service object is for the delegate user. A ID do item incluída na chamada do método BIND identifica exclusivamente o item no repositório de caixa de correio, na pasta contatos do proprietário da caixa de correio.The item ID included in the Bind method call uniquely identifies the item in the mailbox store, in the mailbox owner's Contacts folder.

Tabela 2. Métodos da API gerenciada do EWS trabalhando com um contato como um representanteTable 2. EWS Managed API methods working with a contact as a delegate

TarefaTask Método de API gerenciada do EWSEWS Managed API method Exemplo de códigoCode example
Obter um contatoGet a contact
AssociáBind
Obter um item usando a API gerenciada do EWSGet an item by using the EWS Managed API
Atualizar um contatoUpdate a contact
Vincular seguido por atualizaçãoBind followed by Update
Atualizar um item usando a API gerenciada do EWSUpdate an item by using the EWS Managed API
Excluir um contatoDelete a contact
Vincular seguido por deleteBind followed by Delete
Excluir um item usando a API gerenciada do EWSDelete an item by using the EWS Managed API

Obter, atualizar ou excluir itens de contato como um representante usando o EWSGet, update, or delete contact items as a delegate by using EWS

Você pode usar o EWS para obter, atualizar ou excluir um contato de reunião ou compromisso da mesma maneira que você executa essas ações quando não está usando o acesso de representante.You can use EWS to get, update, or delete a meeting or appointment contact in the same way that you perform these actions when you're not using delegate access. A única diferença é que o objeto de serviço é para o usuário delegado.The only difference is that the service object is for the delegate user. A ID do item incluída na solicitação GetItem identifica exclusivamente o item no repositório de caixa de correio, na pasta contatos do proprietário da caixa de correio.The item ID included in the GetItem request uniquely identifies the item in the mailbox store, in the mailbox owner's Contacts folder.

Tabela 3. Operações do EWS para trabalhar com um contato como representanteTable 3. EWS operations for working with a contact as a delegate

TarefaTask Operação do EWSEWS operation AmostraSample
Obter um contatoGet a contact
GetItemGetItem
Obter um item usando o EWSGet an item by using EWS
Atualizar um contatoUpdate a contact
GetItem seguido por UpdateItemGetItem followed by UpdateItem
Atualizar um item usando o EWSUpdate an item by using EWS
Excluir um contatoDelete a contact
GetItem seguido por DeleteItemGetItem followed by DeleteItem
Excluir um item usando o EWSDelete an item by using EWS

Confira tambémSee also