Acceso a contactos como delegado mediante EWS en Exchange

Artículo
03/29/2023

Obtenga información sobre cómo acceder a los contactos como delegado mediante la API administrada de EWS o EWS en Exchange.

Puede usar la API administrada de EWS o EWS para proporcionar a un usuario acceso a la carpeta Contactos del propietario de un buzón. A continuación, el delegado puede crear contactos en nombre del propietario del buzón y recuperar, actualizar y eliminar contactos de la carpeta Contactos del propietario del buzón, en función de sus permisos.

Como delegado, usa los mismos métodos y operaciones para acceder a la carpeta Contactos del propietario de un buzón que usa para acceder a su propia carpeta Contactos. La principal diferencia es que tiene que usar el acceso explícito para buscar o crear un elemento de contacto y, después de identificar el identificador de elemento, puede usar el acceso implícito para obtener, actualizar o eliminar el elemento.

Tabla 1. Métodos de API administrada de EWS y operaciones de EWS para acceder a un contacto como delegado

Si quiere...	Usar este método de API administrada de EWS...	Use esta operación EWS...
Creación de un contacto como delegado	Item.Save donde el parámetro FolderId proporciona acceso explícito a la carpeta Contactos del propietario del buzón	CreateItem donde el elemento Mailbox especifica el EmailAddress del propietario del buzón
Creación de varios contactos como delegado	ExchangeService.CreateItems donde el parámetro FolderId proporciona acceso explícito a la carpeta Contactos del propietario del buzón	CreateItem donde el elemento Mailbox especifica el EmailAddress del propietario del buzón
Resolución de un contacto como delegado	ExchangeService.ResolveName donde el parámetro FolderId proporciona acceso explícito a la carpeta Contactos del propietario del buzón	ResolveNames donde el elemento Mailbox especifica el emailaddress del propietario del buzón
Buscar o buscar un contacto como delegado	ExchangeService.FindItems donde el parámetro FolderId proporciona acceso explícito a la carpeta Contactos del propietario del buzón	FindItem donde el elemento Mailbox especifica el EmailAddress del propietario del buzón
Obtener un contacto como delegado	Contact.Bind	GetItem
Actualizar un contacto como delegado	Contact.Bind seguido de Contact.Update	GetItem seguido de UpdateItem
Eliminación de un contacto como delegado	Contact.Bind seguido de Contact.Delete	GetItem seguido de DeleteItem

Nota:

En los ejemplos de código de este artículo, primary@contoso.com es el propietario del buzón.

Tareas de requisitos previos

Antes de que un usuario pueda acceder a la carpeta Contactos del propietario del buzón como delegado, el usuario debe agregarse como delegado con permisos a la carpeta Contactos del propietario del buzón.

Creación de un contacto como delegado mediante la API administrada de EWS

La API administrada de EWS permite usar el objeto de servicio para que el usuario delegado cree contactos para el propietario del buzón. En este ejemplo se muestra cómo usar el método Guardar para crear una reunión y enviar convocatorias de reunión a los asistentes.

En este ejemplo se supone que el servicio es un objeto ExchangeService válido para el delegado y que se han concedido al delegado los permisos adecuados para la carpeta Contactos del propietario del buzón.

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

Tenga en cuenta que al guardar el elemento, la llamada al método Save debe identificar la carpeta Contactos del propietario del buzón. Si no se especifica la carpeta Contactos del propietario del buzón, la convocatoria de reunión se guarda en la carpeta Contactos del delegado y no en la carpeta Contactos del propietario del buzón. Puede incluir la carpeta Contactos del propietario del buzón en la llamada al método Save de dos maneras. Se recomienda crear una instancia nueva del objeto FolderId mediante el WellKnownFolderName y la dirección SMTP del propietario del buzón.

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

Sin embargo, también puede enlazar primero a la carpeta Contactos y, a continuación, usar el identificador de la carpeta en la llamada al método Save . Tenga en cuenta, sin embargo, que esto crea una llamada EWS adicional.

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

Creación de un contacto como delegado mediante EWS

EWS permite usar el objeto de servicio para que el usuario delegado cree elementos de contacto para el propietario del buzón. En este ejemplo se muestra cómo usar la operación CreateItem para crear un contacto.

Esta es también la solicitud XML que envía la API administrada de EWS cuando se usa el método Save para crear un contacto.

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

El servidor responde a la solicitud CreateItem con un mensaje CreateItemResponse que incluye un valor de elemento ResponseCode de NoError, lo que indica que el contacto se creó correctamente. La respuesta también contiene el identificador de elemento del contacto recién creado.

Resolución de un contacto como delegado mediante la API administrada de EWS

Para encontrar un contacto basado en un nombre o término posiblemente ambiguo, debe usar uno de los métodos ExchangeService.ResolveName que incluye un parámetro FolderId , de modo que pueda especificar la carpeta Contactos del propietario del buzón.

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

Una vez que la llamada al método ResolveNames devuelve una respuesta con un identificador, puede obtener, actualizar o eliminar el contacto mediante el identificador y el acceso implícito, y no es necesario especificar la dirección SMTP del propietario del buzón.

Resolución de un contacto como delegado mediante EWS

EWS permite usar el objeto de servicio para que el usuario delegado resuelva nombres parciales en la carpeta Contactos del propietario del buzón. En este ejemplo se muestra cómo usar la operación ResolveNames para buscar reuniones en la carpeta Contactos del propietario del buzón que contienen la palabra "johnson".

Esta es también la solicitud XML que la API administrada de EWS envía cuando se usa el método ResolveName para resolver un contacto.

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

El servidor responde a la solicitud ResolveNames con un mensaje ResolveNamesResponse que incluye un valor de elemento ResponseCode de NoError, lo que indica que la operación se completó correctamente y solo encontró un resultado, o ErrorNameResolutionMultipleResults si se encontraron varios resultados, que es lo que se muestra en el tercer ejemplo de código basado en el contacto Crear un contacto como delegado mediante la API administrada de EWS. La respuesta también contiene el ItemId de cada resultado.

El valor del elemento ItemId se ha abreviado para mejorar la legibilidad.

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

Ahora que tiene itemId para los contactos que coinciden con el nombre ambiguo, puede obtener, actualizar o eliminar elementos de contacto como delegado mediante EWS mediante el itemId y el acceso implícito, y no es necesario especificar la dirección SMTP del propietario del buzón.

Obtener, actualizar o eliminar elementos de contacto como delegado mediante la API administrada de EWS

Puede usar la API administrada de EWS para obtener, actualizar o eliminar un contacto de la misma manera que realiza estas acciones cuando no usa el acceso delegado. La única diferencia es que el objeto de servicio es para el usuario delegado. El identificador de elemento incluido en la llamada al método Bind identifica de forma única el elemento en el almacén de buzones, en la carpeta Contactos del propietario del buzón.

Tabla 2. Métodos de API administrada de EWS que funcionan con un contacto como delegado

Task	Método de la API administrada de EWS	Ejemplo de código
Obtener un contacto	Enlazar	Obtener un elemento mediante la API administrada de EWS
Actualizar un contacto	Bind seguido de Update	Actualización de un elemento mediante la API administrada de EWS
Eliminación de un contacto	Bind seguido de Delete	Eliminación de un elemento mediante la API administrada de EWS

Obtener, actualizar o eliminar elementos de contacto como delegado mediante EWS

Puede usar EWS para obtener, actualizar o eliminar un contacto de reunión o cita de la misma manera que realiza estas acciones cuando no usa el acceso delegado. La única diferencia es que el objeto de servicio es para el usuario delegado. El identificador de elemento incluido en la solicitud GetItem identifica de forma única el elemento en el almacén de buzones, en la carpeta Contactos del propietario del buzón.

Tabla 3. Operaciones de EWS para trabajar con un contacto como delegado

Task	Operación de EWS	Ejemplo
Obtener un contacto	GetItem	Obtener un elemento mediante EWS
Actualizar un contacto	GetItem seguido de UpdateItem	Actualización de un elemento mediante EWS
Eliminación de un contacto	GetItem seguido de DeleteItem	Eliminación de un elemento mediante EWS