Identificadores de EWS en Exchange
Obtenga información sobre los identificadores en Exchange y cómo puede usarlos en la API administrada de EWS y las aplicaciones EWS.
Cada objeto del almacén de Exchange tiene un identificador único. Puede usar el identificador de un objeto para hacer referencia al objeto y distinguirlo de otros objetos. Los dos identificadores más comunes con los que puede trabajar son los identificadores de carpeta y elemento.
Para comprender los identificadores y cómo son importantes para la aplicación, resulta útil comprender la relación entre los objetos de Exchange. Cuando la API administrada de EWS o la aplicación EWS se comunican con Exchange, se trabaja con una jerarquía de objetos que incluye objetos de buzón, carpeta y elemento. Un almacén puede ser cualquiera de estos tipos de objeto. Normalmente, es un buzón en el servidor exchange, pero también puede ser una carpeta pública en el servidor exchange. (Tenga en cuenta que, en Exchange Online, Exchange Online como parte de Office 365 y versiones de Exchange a partir de Exchange 2013, las carpetas públicas son solo otro tipo de buzón y no un tipo de almacén diferente). El almacén contiene carpetas y las carpetas contienen elementos, y cada una de estas carpetas y elementos tiene un identificador, como se muestra en la ilustración siguiente.
Figura 1. Jerarquía de buzón, carpeta y elemento
Identificadores de EWS
Los identificadores que EWS usa para carpetas y elementos se denominan identificadores de EWS o EwsIds. Los EwsIds se pueden encontrar en muchos objetos diferentes dentro de EWS, pero se denominan algo diferente para objetos diferentes. Dado que puede usar estos objetos en la aplicación, querrá comprender cómo se relacionan los identificadores de estos objetos con el EwsId.
Los identificadores de EWS también se aplican a la API administrada de EWS. En la API administrada de EWS, los identificadores son propiedades de los objetos y se administran internamente para asignarlos a los elementos EWS.
Tabla 1. Identificadores de objeto en EWS
| Objeto | Identificador | ¿Cómo se relaciona con EwsId? |
|---|---|---|
| CalendarItem |
El elemento secundario ItemId contiene el identificador único del elemento de calendario. |
El elemento secundario ItemId es el mismo que el EwsId para este elemento. |
| ConversationId |
El atributo Id contiene el identificador de la conversación de la que forma parte este elemento. |
El atributo Id es el mismo que el EwsId para este elemento. |
| AttachmentId |
Proporciona el identificador único de los datos adjuntos. El atributo RootItemId contiene el identificador único del elemento de almacén raíz al que se adjuntan los datos adjuntos. |
Los datos adjuntos pueden ser otros elementos del almacén de Exchange, en cuyo caso el AttachmentId es el mismo que el EwsId. En todos los casos, RootItemId es un EwsId porque hace referencia a un elemento del almacén. |
| PersonaId |
El atributo Id devuelve una cadena que contiene el identificador del rol. |
El atributo Id es el mismo que el EwsId para el rol. |
| ContactId |
El atributo Id devuelve una cadena que contiene el identificador del contacto. |
El atributo Id es el mismo que el EwsId para el contacto. |
| Groupid |
El atributo Id devuelve una cadena que contiene el identificador del grupo. |
El atributo Id es el mismo que el EwsId del grupo. |
| AssociatedCalendarItemId |
El atributo Id identifica el elemento de calendario asociado a MeetingMessage, MeetingRequest, MeetingResponse o MeetingCancellation. |
El atributo Id es el mismo que el EwsId para el elemento de calendario. |
| UserConfigurationProperties |
El valor Id de este elemento especifica la propiedad identifier. |
Este identificador no se asigna directamente al EwsId, ya que es un identificador de propiedad y no un elemento. |
| OccurrenceItemId |
El atributo RecurringMasterId identifica el patrón de un elemento periódico. |
El valor OccurrenceItemId no se asigna directamente al EwsId, pero recurringMasterId lo hace porque hace referencia al objeto de nivel superior del elemento periódico. |
| StoreEntryId |
Contiene el identificador de almacén de Exchange de un elemento. |
El valor de StoreEntryId no se asigna a EwsId, pero proporciona el identificador del almacén donde se conservan los elementos. |
Trabajar con identificadores
El servidor de Exchange controla los identificadores de muchas maneras diferentes. Tenga en cuenta lo siguiente al desarrollar la API administrada de EWS o la aplicación EWS:
El valor del elemento ItemID para carpetas y elementos distingue mayúsculas de minúsculas. Si examina el identificador de elemento de una carpeta o elemento devuelto por la operación FindItem (o el método de API administrada de EWS FindItems ), es posible que piense que es un duplicado de otro identificador de elemento; sin embargo, uno o más caracteres en los identificadores de elemento de los dos elementos tendrán un caso diferente.
Si va a almacenar el identificador de elemento en una base de datos para recuperarlo más adelante, se recomienda que el tamaño del campo sea de 512 bytes, de modo que sea lo suficientemente grande como para contener el GUID.
No suponga que el identificador de elemento siempre será válido si necesita recuperar el elemento más adelante. Si un elemento se mueve en el almacén, el identificador puede cambiar debido a la forma en que se controla un movimiento. Un elemento se copia realmente y se genera un nuevo identificador y, a continuación, se elimina el elemento original. Tenga en cuenta que los identificadores de carpeta son inmutables y no cambiarán cuando se muevan en el almacén.
Los identificadores de Exchange son opacos. Por ejemplo, el EwsId se crea a partir de varios fragmentos de información que no son importantes para usted como desarrollador, pero que son importantes para Exchange.
Cuando se trabaja con elementos en Exchange, otro valor que hay que tener en cuenta es el atributo ChangeKey . Este valor, además del identificador de elemento, se usa para realizar un seguimiento del estado de un elemento. Cada vez que se cambia un elemento, se genera una nueva clave de cambio. Al realizar una operación UpdateItem, por ejemplo, puede usar el atributo ChangeKey para que el servidor sepa que la actualización se está aplicando a la versión más actual del elemento. Si otra aplicación realizó un cambio en el elemento que está actualizando, las claves de cambio no coincidirán y no podrá realizar la actualización.
Identificadores de carpeta distintivos
Exchange incluye varias carpetas de buzón predefinidas, a cada una de las cuales se le asigna un identificador, conocido como identificador de carpeta distintivo. Se definen mediante la enumeración de api administrada de EWS WellKnownFolderName y el elemento EWS DistinguishedFolderId . Puede usar estos identificadores de carpeta distintivos para hacer referencia más fácilmente a una de las carpetas predefinidas. Por ejemplo, para la carpeta Bandeja de entrada, puede usar simplemente "bandeja de entrada" para el identificador, en lugar de determinar el identificador de carpeta.
Otras carpetas que se crean para organizar los elementos de correo electrónico también tienen un identificador que es único para esa carpeta. Ese identificador no cambia incluso si cambia otras propiedades de la carpeta.
Puede usar identificadores de carpeta distintivos como punto de entrada para el acceso delegado. Al iniciar el acceso delegado, busca elementos o carpetas y proporciona el identificador de carpeta distintivo para especificar dónde buscar. Cuando un usuario delegado accede al servidor, se usa un elemento Mailbox que es un elemento secundario del elemento DistinguishedFolderId para especificar explícitamente el buzón al que tiene acceso el delegado.
Administración de errores
Cada programa está enlazado a obtener un error de vez en cuando, y las aplicaciones basadas en EWS no son ninguna excepción (el juego de palabras está pensado). Es posible que reciba algunos errores relacionados con el identificador en el elemento EWS ResponseCode o como parte de la enumeración api administrada de EWS ServiceError .
Los siguientes errores pueden producirse en la API administrada de EWS o en la aplicación EWS. Si está trabajando con una aplicación de API administrada de EWS, los errores suelen tener problemas con los valores de propiedad; En el caso de las aplicaciones EWS, los errores se asocian con los valores o las operaciones de elementos XML.
Tabla 2. Errores relacionados con el identificador
| Error | Se produce cuando... | Descripción |
|---|---|---|
| ErrorCalendarCannotUseIdForOccurrenceId |
El valor de OccurenceID no corresponde a un elemento de calendario periódico válido. |
El valor de OccurenceId especificado en la solicitud podría ser válido en la estructura, pero la solicitud no pudo coincidir con un patrón periódico existente. El elemento periódico podría quitarse del calendario. Compruebe que el elemento sigue existiendo y que está usando el identificador correcto. |
| ErrorCalendarCannotUseIdForRecurringMasterId |
El atributo RecurringMasterId no corresponde a una aparición válida del elemento OccurrenceId . |
El valor de RecurringMasterId que se especificó en la solicitud podría ser válido en la estructura, pero la solicitud no pudo coincidir con una aparición existente del elemento. La aparición del elemento podría quitarse del calendario. Compruebe que el elemento sigue existiendo y que está usando el identificador correcto. |
| ErrorCannotUseFolderIdForItemId |
El identificador que se pasó representa una carpeta en lugar de un elemento. |
El identificador podría ser válido en formato, pero no lo que el servidor esperaba para la operación. Compruebe que hace referencia al identificador correcto para la operación. |
| ErrorCannotUseItemIdForFolderId |
El identificador que se pasó representa un elemento en lugar de una carpeta. |
El identificador podría ser válido en formato, pero no lo que el servidor esperaba para la operación. Compruebe que hace referencia al identificador correcto para la operación. |
| ErrorChangeKeyRequiredForWriteOperations |
Se debe proporcionar una clave de cambio válida al realizar ciertas operaciones de actualización. |
Omitió un valor ChangeKey cuando solicitó una actualización o la clave de cambio era incorrecta. Compruebe que tiene la clave de cambio correcta al realizar operaciones de actualización. |
| ErrorInvalidAttachmentId |
Los datos adjuntos no se encontraron en la colección de datos adjuntos del elemento. |
Puede recibir este código de respuesta si tiene un identificador de datos adjuntos y, a continuación, se eliminan los datos adjuntos e intenta llamar a la operación GetAttachment en el identificador de datos adjuntos. Compruebe que los datos adjuntos existen en la colección de datos adjuntos. |
| ErrorInvalidChangeKey |
Se ha pasado una clave de cambio no válida. |
Tenga en cuenta que muchas operaciones y métodos no requieren que se pase una clave de cambio. Sin embargo, si proporciona una clave de cambio, debe ser válida, aunque no tiene que estar actualizada necesariamente. |
| ErrorInvalidFolderId |
El identificador de carpeta está dañado. |
Asegúrese de que tiene un identificador válido y con el formato correcto. |
| ErrorInvalidId |
La estructura del identificador o la clave de cambio es internamente incoherente. |
Exchange encontró un problema con el identificador después de analizarlo. Es posible que se haya producido un error en la conversión. Esto puede ocurrir, por ejemplo, si tiene un IdFormatType.HexEntryId para un elemento en Outlook, pero lo convierte a un EwsId pensando que era un formato IdFormatType.EntryId . Asegúrese de usar el tipo de conversión correcto. |
| ErrorInvalidIdEmpty |
La aplicación especificó un identificador que está vacío. |
La aplicación pasó una cadena vacía para el identificador. Asegúrese de que tiene un identificador válido y con el formato correcto. |
| ErrorInvalidIdMalformed |
La estructura del identificador es internamente incoherente. |
Exchange encontró un problema con el identificador después de analizarlo. Es posible que el identificador no se haya convertido correctamente. Asegúrese de usar el tipo de conversión correcto. |
| ErrorInvalidIdMalformedEwsLegacyIdFormat |
Se especificó un identificador de carpeta o elemento que usa el formato de Exchange 2007 para una solicitud con una versión de Exchange 2007 SP1 o posterior. |
No puede usar identificadores de Exchange 2007 en exchange 2007 SP1 o solicitudes posteriores. Debe usar la operación ConvertId EWS o el método convertId EWS Managed API para convertirlos primero. |
| ErrorInvalidIdNotAnItemAttachmentId |
La propiedad AttachmentId no hace referencia a los datos adjuntos de un elemento. |
El identificador podría ser válido en formato, pero no lo que el servidor esperaba para la operación. Compruebe que hace referencia al identificador correcto para la operación. |
| ErrorInvalidIdReturnedByResolveNames |
Un contacto del buzón está dañado. |
La operación EWS ResolveNames o el método de API administrada de EWS ResolveName devolvieron uno o varios identificadores, pero no son válidos. Es posible que tenga que volver a crear el contacto. |
| ErrorInvalidIdStoreObjectIdTooLong |
La estructura del identificador es internamente incoherente. |
Exchange encontró un problema con el identificador después de analizarlo. Es posible que el identificador no se haya convertido correctamente. Asegúrese de usar el tipo de conversión correcto. |
| ErrorInvalidIdTooManyAttachmentLevels |
Las jerarquías de datos adjuntos superan el máximo de 255 niveles de profundidad. |
El valor de la propiedad AttachmentId que se especificó en la solicitud puede ser válido en la estructura, pero los datos adjuntos solicitados son demasiado profundos en la jerarquía. Es posible que el código haya intentado adjuntar un elemento más allá del límite de 255 niveles. |
| ErrorInvalidImContactId |
Este error se puede devolver cuando el contacto no se encuentra en el grupo de mensajería instantánea cuando se usa la operación RemoveImContactFromGroup. Este error se aplica a los clientes que tienen como destino Exchange Online y versiones de Exchange a partir de Exchange 2013. |
El valor de la propiedad ContactId que se especificó en la solicitud podría ser válido en la estructura, pero ningún contacto del buzón coincide con esta estructura. Es posible que el contacto ya se haya quitado. |
| ErrorInvalidImGroupId |
Este error se puede devolver cuando el grupo no se encuentra en el buzón cuando se usa la operación RemoveImGroup. Este error se aplica a los clientes que tienen como destino Exchange Online y versiones de Exchange a partir de Exchange 2013. |
El valor de la propiedad GroupId que se especificó en la solicitud puede ser válido en la estructura, pero ningún grupo del buzón coincide con esta estructura. Es posible que el grupo ya se haya quitado. |
| ErrorInvalidReferenceItem |
El identificador de elemento al que se hace referencia no es un MessageType o ExchangeWebServices.CalendarItemTypeType, ni uno de sus descendientes. El identificador de elemento de referencia es para un objeto CalendarItemType y el organizador está intentando responder o responder a todos. |
El identificador podría ser válido en formato, pero no lo que el servidor esperaba para la operación. Compruebe que hace referencia al identificador correcto para la operación. |
| ErrorMissingManagedFolderId |
Falta la propiedad de identificadores de directiva, etiqueta de propiedad 0x6732, para la carpeta. |
La carpeta está dañada. Considere la posibilidad de volver a crearlo. |
Conversión de identificadores
Es posible que tenga que convertir un identificador de un formato a otro. Por ejemplo, es posible que tenga que convertir un identificador de EWS externo, como un identificador que procede de una conexión MAPI, a un formato que la aplicación puede usar. Para ello, puede usar la operación ConvertId EWS o el método ConvertId EWS Managed API.
Por ejemplo, entryID es un identificador único generado por el almacén de mensajes MAPI asignado por el almacén cuando se guarda el elemento. Para usar un EntryID en la aplicación, primero debe convertirlo en un EwsId.
Outlook Web App usa su propia versión de identificadores, denominada OwaId, en direcciones URL para acceder a carpetas y elementos. Si la aplicación necesita tener acceso a los elementos de Outlook Web App, debe convertir OwaId en un EwsId.
Puede usar la operación ConvertId o el método para convertir varios formatos de identificador diferentes.
Tabla 3. Formatos de identificador convertibles en Exchange
| Format | Descripción |
|---|---|
| EwsLegacyId |
EwsId que se aplica a Exchange 2007. |
| EwsId |
EwsId que se aplica a Exchange Online y versiones de Exchange a partir de Exchange 2007 SP1. |
| StoreId |
Identificador del almacén de Exchange donde se almacenan las carpetas y los elementos. |
| OwaId |
Identificador de Outlook Web App que se usa con Outlook Web App en Exchange 2007 y Exchange 2010. NOTA: Exchange Online y versiones de Exchange a partir de Exchange 2013 usan el EwsId para Outlook Web App. |
| EntryID |
Identificador MAPI que se conoce normalmente como la propiedad PR_ENTRYID de un mensaje MAPI. |
| HexEntryId |
Representación codificada hexadecimalmente de la propiedad PR_ENTRYID que se usa para el identificador de eventos del calendario de disponibilidad. Este es también el formato de identificador que usa Outlook. |