Identificadores EWS no Exchange
Saiba mais sobre os identificadores no Exchange e como você pode usá-los em seus aplicativos EWS EWS Managed API e EWS.
Cada objeto na exchange store tem um identificador exclusivo. Você pode usar o identificador de um objeto para fazer referência ao objeto e distingui-lo de outros objetos. Os dois identificadores mais comuns com os quais você pode trabalhar são identificadores de pasta e item.
Para entender os identificadores e como eles são importantes para seu aplicativo, é útil entender a relação entre objetos no Exchange. Quando a API Gerenciada do EWS ou o aplicativo EWS se comunica com o Exchange, você trabalha com uma hierarquia de objetos que inclui objetos de caixa de correio, pasta e item. Um repositório pode ser qualquer um desses tipos de objeto. Mais comumente, é uma caixa de correio no servidor exchange, mas também pode ser uma pasta pública no servidor exchange. (Tenha em mente que, em Exchange Online, Exchange Online como parte de Office 365 e versões do Exchange a partir do Exchange 2013, as pastas públicas são apenas outro tipo de caixa de correio e não um tipo diferente de armazenamento.) O repositório contém pastas e as pastas contêm itens e cada uma dessas pastas e itens tem um identificador, conforme mostrado na figura a seguir.
Figura 1. Hierarquia de caixa de correio, pasta e item
Identificadores EWS
Os identificadores que o EWS usa para pastas e itens são chamados de identificadores EWS ou EwsIds. EwsIds podem ser encontrados em muitos objetos diferentes dentro do EWS, mas são chamados de algo diferente para objetos diferentes. Como você pode usar esses objetos em seu aplicativo, você vai querer entender como os identificadores desses objetos se relacionam com o EwsId.
Os identificadores no EWS também são aplicáveis à API Gerenciada do EWS. Na API Gerenciada do EWS, os identificadores são propriedades dos objetos e são gerenciados internamente para mapear os elementos EWS.
Tabela 1. Identificadores de objeto no EWS
| Object | Identificador | Como ele se relaciona com o EwsId? |
|---|---|---|
| CalendarItem |
O elemento filho ItemId contém o identificador exclusivo do item de calendário. |
O elemento filho ItemId é o mesmo que o EwsId para este item. |
| ConversationId |
O atributo Id contém o identificador da conversa da qual esse item faz parte. |
O atributo Id é o mesmo que o EwsId para este item. |
| AttachmentId |
Fornece o identificador exclusivo do anexo. O atributo RootItemId contém o identificador exclusivo do item do repositório raiz ao qual o anexo está anexado. |
Anexos podem ser outros itens no repositório exchange, nesse caso, o AttachmentId é o mesmo que o EwsId. Em todos os casos, o RootItemId é um EwsId porque faz referência a um item no repositório. |
| PersonaId |
O atributo Id retorna uma cadeia de caracteres que contém o identificador da persona. |
O atributo Id é o mesmo que o EwsId para a persona. |
| ContactId |
O atributo Id retorna uma cadeia de caracteres que contém o identificador do contato. |
O atributo Id é o mesmo que o EwsId para o contato. |
| Groupid |
O atributo Id retorna uma cadeia de caracteres que contém o identificador do grupo. |
O atributo Id é o mesmo que o EwsId para o grupo. |
| AssociatedCalendarItemId |
O atributo Id identifica o item de calendário associado a um MeetingMessage, MeetingRequest, MeetingResponse ou MeetingCancellation. |
O atributo Id é o mesmo que o EwsId para o item de calendário. |
| UserConfigurationProperties |
O valor da ID para esse elemento especifica a propriedade do identificador. |
Esse identificador não é mapeado diretamente para o EwsId, pois ele é um identificador de propriedade e não um item. |
| OccurrenceItemId |
O atributo RecurringMasterId identifica o mestre de um item recorrente. |
O valor OccurrenceItemId não é mapeado diretamente para o EwsId, mas o RecurringMasterId faz porque faz referência ao objeto de nível superior do item recorrente. |
| StoreEntryId |
Contém o identificador do exchange store de um item. |
O valor StoreEntryId não é mapeado para o EwsId, mas fornece o identificador do repositório onde os itens são mantidos. |
Trabalhando com identificadores
O servidor exchange manipula identificadores de várias maneiras diferentes. Considere o seguinte quando você desenvolver a API Gerenciada do EWS ou o aplicativo EWS:
O valor do elemento ItemID para pastas e itens é sensível a maiúsculas de minúsculas. Se você examinar a ID do item para uma pasta ou item retornado pela operação FindItem (ou pelo método de API Gerenciada do FindItems EWS), talvez você pense que é uma duplicata de outra ID de item; no entanto, um ou mais caracteres nas IDs do item para os dois itens terão um caso diferente.
Se você vai armazenar a ID do item em um banco de dados para recuperar posteriormente, recomendamos que o tamanho do campo seja 512 bytes, para que ele seja grande o suficiente para manter o GUID.
Não suponha que a ID do item sempre será válida se você precisar recuperar o item posteriormente. Se um item for movido no repositório, a ID poderá ser alterada devido à maneira como um movimento é tratado. Um item é realmente copiado e uma nova ID é gerada e, em seguida, o item original é excluído. Observe que as IDs de pasta são imutáveis e não serão alteradas quando movidas no repositório.
Os identificadores no Exchange são opacos. Por exemplo, o EwsId é criado a partir de várias informações que não são importantes para você como desenvolvedor, mas são importantes para o Exchange.
Quando você trabalha com itens no Exchange, outro valor a ter em mente é o atributo ChangeKey . Esse valor, além da ID do item, é usado para acompanhar o estado de um item. Sempre que um item é alterado, uma nova chave de alteração é gerada. Ao executar uma operação UpdateItem, por exemplo, você pode usar o atributo ChangeKey para informar ao servidor que sua atualização está sendo aplicada à versão mais atual do item. Se outro aplicativo fez uma alteração no item que você está atualizando, as chaves de alteração não corresponderão e você não poderá executar a atualização.
IDs de pasta diferenciadas
O Exchange inclui várias pastas de caixa de correio predefinidas, cada uma delas atribuída a um identificador, conhecido como ID de pasta diferenciada. Elas são definidas pela enumeração de API Gerenciada do WellKnownFolderName EWS e pelo elemento DistinguishedFolderId EWS. Você pode usar essas IDs de pasta diferenciadas para fazer referência mais facilmente a uma das pastas predefinidas. Por exemplo, para a pasta Caixa de Entrada, você pode simplesmente usar "caixa de entrada" para o identificador, em vez de determinar o identificador de pasta.
Outras pastas que você cria para organizar itens de email também têm uma ID exclusiva para essa pasta. Essa ID não será alterada mesmo se você alterar outras propriedades na pasta.
Você pode usar IDs de pasta diferenciadas como um ponto de entrada para acesso de delegado. Ao iniciar o acesso de delegado, pesquise itens ou pastas e forneça a ID de pasta diferenciada para especificar onde pesquisar. Quando um usuário delegado acessa o servidor, um elemento Mailbox que é filho do elemento DistinguishedFolderId é usado para especificar explicitamente a caixa de correio para o delegado acessar.
Tratamento de erros
Cada programa é obrigado a obter um erro de vez em quando, e aplicativos baseados em EWS não são exceção (trocadilho pretendido). Você pode receber alguns erros relacionados ao identificador no elemento ResponseCode EWS ou como parte da enumeração da API Gerenciada do ServiceError EWS.
Os erros a seguir podem ocorrer em sua API Gerenciada do EWS ou no aplicativo EWS. Se você estiver trabalhando com um aplicativo de API Gerenciada do EWS, os erros normalmente serão problemas com valores de propriedade; para aplicativos EWS, os erros estão associados a valores ou operações de elemento XML.
Tabela 2. Erros relacionados ao identificador
| Erro | Ocorre quando... | Descrição |
|---|---|---|
| ErrorCalendarCannotUseIdForOccurrenceId |
O valor do OccurenceID não corresponde a um item de calendário recorrente válido. |
O valor do OccurenceId especificado na solicitação pode ser válido na estrutura, mas a solicitação não pôde correspondê-la a um mestre recorrente existente. O item recorrente pode ser removido do calendário. Verifique se o item ainda existe e se você está usando o identificador correto. |
| ErrorCalendarCannotUseIdForRecurringMasterId |
O atributo RecurringMasterId não corresponde a uma ocorrência válida do elemento OccurrenceId . |
O valor do RecurringMasterId especificado na solicitação pode ser válido na estrutura, mas a solicitação não pôde correspondê-lo a uma ocorrência existente do item. A ocorrência do item pode ser removida do calendário. Verifique se o item ainda existe e se você está usando o identificador correto. |
| ErrorCannotUseFolderIdForItemId |
A ID passada representa uma pasta em vez de um item. |
O identificador pode ser válido em formato, mas não o que o servidor esperava para a operação. Verifique se você está fazendo referência ao identificador correto para a operação. |
| ErrorCannotUseItemIdForFolderId |
A ID passada representa um item em vez de uma pasta. |
O identificador pode ser válido em formato, mas não o que o servidor esperava para a operação. Verifique se você está fazendo referência à ID correta para a operação. |
| ErrorChangeKeyRequiredForWriteOperations |
Uma chave de alteração válida deve ser fornecida quando você estiver executando determinadas operações de atualização. |
Você omitiu um valor ChangeKey quando solicitou uma atualização ou a chave de alteração estava incorreta. Verifique se você tem a chave de alteração correta ao executar operações de atualização. |
| ErrorInvalidAttachmentId |
O anexo não foi encontrado na coleção de anexos do item. |
Você poderá receber esse código de resposta se tiver uma ID de anexo e o anexo for excluído e tentar chamar a operação GetAttachment na ID do anexo. Verifique se o anexo existe na coleção de anexos. |
| ErrorInvalidChangeKey |
Uma chave de alteração inválida foi passada. |
Observe que muitas operações e métodos não exigem que uma chave de alteração seja passada. No entanto, se você fornecer uma chave de alteração, ela deve ser válida, embora ela não precise necessariamente estar atualizada. |
| ErrorInvalidFolderId |
A ID da pasta está corrompida. |
Verifique se você tem um identificador devidamente formatado e válido. |
| ErrorInvalidId |
A estrutura da chave de ID e/ou alteração é internamente inconsistente. |
O Exchange encontrou um problema com a ID depois que ela foi analisada. Pode ter havido um erro na conversão. Isso pode ocorrer, por exemplo, se você tiver um IdFormatType.HexEntryId para um item no Outlook, mas você o converterá em um EwsId pensando que era um formato IdFormatType.EntryId . Use o tipo de conversão correto. |
| ErrorInvalidIdEmpty |
O aplicativo especificou uma ID vazia. |
Seu aplicativo passou em uma cadeia de caracteres vazia para o identificador. Verifique se você tem um identificador devidamente formatado e válido. |
| ErrorInvalidIdMalformed |
A estrutura da ID é internamente inconsistente. |
O Exchange encontrou um problema com a ID depois que ela foi analisada. A ID pode não ter sido convertida corretamente. Use o tipo de conversão correto. |
| ErrorInvalidIdMalformedEwsLegacyIdFormat |
Uma ID de pasta ou item que está usando o formato do Exchange 2007 foi especificada para uma solicitação com uma versão do Exchange 2007 SP1 ou posterior. |
Você não pode usar IDs do Exchange 2007 no Exchange 2007 SP1 ou solicitações posteriores. Você deve usar a operação ConvertId EWS ou o método de API Gerenciada do ConvertId EWS para convertê-los primeiro. |
| ErrorInvalidIdNotAnItemAttachmentId |
A propriedade AttachmentId não se refere a um anexo de item. |
O identificador pode ser válido em formato, mas não o que o servidor esperava para a operação. Verifique se você está fazendo referência ao identificador correto para a operação. |
| ErrorInvalidIdReturnedByResolveNames |
Um contato em sua caixa de correio está corrompido. |
A operação ResolveNames EWS ou o método ResolveName EWS Managed API retornaram um ou mais identificadores, mas eles não são válidos. Talvez seja necessário recriar o contato. |
| ErrorInvalidIdStoreObjectIdTooLong |
A estrutura da ID é internamente inconsistente. |
O Exchange encontrou um problema com a ID depois que ela foi analisada. A ID pode não ter sido convertida corretamente. Use o tipo de conversão correto. |
| ErrorInvalidIdTooManyAttachmentLevels |
As hierarquias de anexo excedem o máximo de 255 níveis de profundidade. |
O valor da propriedade AttachmentId especificada na solicitação pode ser válido na estrutura, mas o anexo solicitado é muito profundo na hierarquia. Seu código pode ter tentado anexar um item além do limite de 255 níveis. |
| ErrorInvalidImContactId |
Esse erro pode ser retornado quando o contato não pode ser encontrado no grupo IM quando você usa a operação RemoveImContactFromGroup. Esse erro se aplica a clientes que visam Exchange Online e versões do Exchange a partir do Exchange 2013. |
O valor da propriedade ContactId especificada na solicitação pode ser válido na estrutura, mas nenhum contato na caixa de correio corresponde a essa estrutura. O contato já pode ter sido removido. |
| ErrorInvalidImGroupId |
Esse erro pode ser retornado quando o grupo não pode ser encontrado na caixa de correio quando você usa a operação RemoveImGroup. Esse erro se aplica a clientes que visam Exchange Online e versões do Exchange a partir do Exchange 2013. |
O valor da propriedade GroupId especificada na solicitação pode ser válido na estrutura, mas nenhum grupo na caixa de correio corresponde a essa estrutura. O grupo já pode ter sido removido. |
| ErrorInvalidReferenceItem |
O identificador de item referenciado não é um MessageType ou ExchangeWebServices.CalendarItemTypeType ou um de seus descendentes. O identificador de item de referência é para um objeto CalendarItemType e o organizador está tentando Responder ou ReplyAll. |
O identificador pode ser válido em formato, mas não o que o servidor esperava para a operação. Verifique se você está fazendo referência ao identificador correto para a operação. |
| ErrorMissingManagedFolderId |
A propriedade IDs da política, a marca de propriedade 0x6732, para a pasta está ausente. |
A pasta está corrompida. Considere recriá-lo. |
Convertendo identificadores
Talvez seja necessário converter um identificador de um formato para outro. Por exemplo, talvez seja necessário converter um identificador de fora do EWS, como um identificador proveniente de uma conexão MAPI, em um formato que seu aplicativo pode usar. Para fazer isso, você pode usar a operação ConvertId EWS ou o método ConvertId EWS Managed API.
Por exemplo, um EntryID é um identificador exclusivo gerado pelo repositório de mensagens MAPI atribuído pelo repositório quando o item é salvo. Para usar um EntryID em seu aplicativo, primeiro você precisa convertê-lo em um EwsId.
Outlook Web App usa sua própria versão de identificadores, chamada OwaId, em URLs para acessar pastas e itens. Se seu aplicativo precisar acessar itens no Outlook Web App, você precisará converter o OwaId em um EwsId.
Você pode usar a operação ConvertId ou o método para converter vários formatos diferentes de identificador.
Tabela 3. Formatos de identificador conversível no Exchange
| Format | Descrição |
|---|---|
| EwsLegacyId |
O EwsId que se aplica ao Exchange 2007. |
| EwsId |
O EwsId que se aplica a Exchange Online e versões do Exchange a partir do Exchange 2007 SP1. |
| Storeid |
O identificador do exchange store em que as pastas e os itens são armazenados. |
| OwaId |
O identificador Outlook Web App usado com Outlook Web App no Exchange 2007 e no Exchange 2010. OBSERVAÇÃO: Exchange Online e versões do Exchange a partir do Exchange 2013 usam o EwsId para Outlook Web App. |
| Entryid |
Um identificador MAPI que é comumente conhecido como a propriedade PR_ENTRYID de uma mensagem MAPI. |
| HexEntryId |
Uma representação codificada por hexadecimal da propriedade PR_ENTRYID que é usada para o identificador de eventos do calendário de disponibilidade. Esse também é o formato de identificador que o Outlook usa. |