Exchange の EWS 識別子

Exchange での識別子、およびそれらを EWS マネージ API と EWS アプリケーションで使用する方法について説明します。

Exchange ストア内のすべてのオブジェクトには、一意の識別子があります。 オブジェクトの識別子を使用して、そのオブジェクトを参照し、他のオブジェクトと区別できます。 使用頻度の最も高い 2 つの識別子は、フォルダーとアイテムの識別子です。

識別子と、識別子がアプリケーションにとってどのように重要なのかを理解するために、Exchange のオブジェクト間の関係を理解しておくようお勧めします。 EWS マネージ API または EWS アプリケーションが Exchange と通信するときには、メールボックス、フォルダー、アイテムのオブジェクトを含むオブジェクトの階層を操作します。 ストアは、これらのオブジェクトの種類のいずれにでもすることができます。 通常、ストアは Exchange サーバー上のメールボックスです。しかし、ストアを Exchange サーバーのパブリック フォルダーとすることもできます。 (Exchange Online、Office 365 に含まれる Exchange Online、および Exchange 2013 以降のバージョンの Exchange では、パブリック フォルダーはメールボックスの一種にすぎず、異なる種類のストアではないことに注意してください。) 次の図に示されるように、フォルダーはストアに格納され、アイテムはフォルダーに格納されます。それぞれのフォルダーやアイテムには識別子があります。

図 1. メールボックス、フォルダー、アイテムの階層構造

EWS 識別子

EWS がフォルダーおよびアイテム用に使用する識別子を EWS 識別子、または EwsId と呼びます。 EwsId は、EWS 内部の多くの異なるオブジェクト内にありますが、オブジェクトが異なると呼び方も異なります。 アプリケーションでこれらのオブジェクトを使用する可能性があるため、EwsId とオブジェクトの識別子の関係がどのようなものか理解する必要があります。

さらに、EWS の識別子は、EWS マネージ API にも適用できます。 EWS マネージ API では、識別子はオブジェクトのプロパティであり、EWS 要素にマッピングされるよう内部で管理されます。

表 1. EWS のオブジェクト識別子

Object	識別子	EwsId との関係
CalendarItem	子要素 ItemId に予定表アイテムの一意の識別子が含まれています。	子要素 ItemId は、このアイテムの EwsId と同じです。
ConversationId	Id 属性に、このアイテムが含まれるスレッドの識別子が含まれています。	Id 属性は、このアイテムの EwsId と同じです。
AttachmentId	添付物の一意の識別子を提供します。 RootItemId 属性には、添付物の添付先ルート ストア アイテムの一意の識別子が含まれています。	添付ファイルは Exchange ストア内の他のアイテムである場合があります。その場合、 AttachmentId は EwsId と同じです。 いずれの場合も、 RootItemId はストア内のアイテムを参照するため EwsId です。
PersonaId	Id 属性は、ペルソナの識別子を含む文字列を返します。	Id 属性は、ペルソナの EwsId と同じです。
ContactId	Id 属性は、連絡先の識別子を含む文字列を返します。	Id 属性は、連絡先の EwsId と同じです。
GroupId	Id 属性は、グループの識別子を含む文字列を返します。	Id 属性は、グループの EwsId と同じです。
AssociatedCalendarItemId	Id 属性は、MeetingMessage、MeetingRequest、MeetingResponse、または MeetingCancellation に関連付けられている予定表アイテムを識別します。	Id 属性は、予定表アイテムの EwsId と同じです。
UserConfigurationProperties	この要素の Id 値は、識別子プロパティを指定します。	この識別子は、プロパティの識別子であってアイテムではないため、直接には EwsId にマッピングされません。
OccurrenceItemId	RecurringMasterId 属性は、定期的なアイテムのマスターを識別します。	OccurrenceItemId 値は、直接には EwsId にマッピングされません。しかし、RecurringMasterId は、定期的なアイテムの最上位レベルのオブジェクトを参照しているため、直接に EwsId にマッピングされます。
StoreEntryId	アイテムの Exchange ストア識別子が含まれています。	StoreEntryId 値は EwsId にはマッピングされませんが、アイテムが保存されているストアの識別子を指定します。

識別子の処理

Exchange サーバーは、さまざまな方法で識別子を処理します。 EWS マネージ API または EWS アプリケーションを開発する場合、以下をご考慮ください。

• フォルダーとアイテムの ItemID 要素の値は、大文字小文字を区別します。 FindItem 操作 (または EWS マネージ API のFindItems メソッド) によって返されるフォルダーまたはアイテムのアイテム IDは、別のアイテム ID と重複しているように見えるかもしれませんが、2 つのアイテムのアイテム ID を比べると、大文字と小文字の違いがある文字があるあずです。

• 後で取得するためにアイテム ID をデータベースに格納する場合、GUID を保持するのに十分な大きさを確保するために、フィールド サイズを 512 バイトにすることをお勧めします。

• 後でアイテムを取得する必要がある場合は、アイテム ID が常に有効であると想定しないでください。 ストア内でアイテムが移動されると、移動の処理方法によっては、ID が変更される可能性があります。 アイテムの複製が実行され、新たな ID が生成されると、元のアイテムは削除されます。 フォルダー ID は不変であり、ストア内で移動しても変更されない点に注意してください。

• Exchange の識別子は、符号化されています。 たとえば、開発者にとっては重要ではないものの、Exchange にとって重要ないくつかの情報から EwsId が作成されます。

• Exchange のアイテムを操作する時に留意して操作する必要がある値の 中に、ChangeKey 属性があります。 この値は、アイテム ID としてだけではなく、アイテムの状態を追跡するためにも使用されます。 アイテムが変更されるたびに、新しい変更キーが生成されます。 たとえば、UpdateItem 操作を実行するときに、ChangeKey 属性を使用して、アイテムの最新バージョンに更新を適用することをサーバーに認識させることができます。 更新中のアイテムを別のアプリケーションが変更していた場合、変更キーが一致しな くなるため、更新を実行できなくなります。

識別フォルダー ID

Exchange には、定義済みのメールボックス フォルダーが多数含まれています。各フォルダーには、識別フォルダー ID と呼ばれる識別子が割り当てられています。 これらは EWS マネージ API の WellKnownFolderName 列挙体と EWS の DistinguishedFolderId 要素によって定義されます。 これらの識別フォルダー ID を使用すれば、特定の定義済みフォルダーを参照するのが簡単になります。 たとえば、受信トレイ フォルダーでは、識別子にフォルダー識別子を判別しないで、単に "受信トレイ" を使用できます。

メール アイテムを整理するために作成する他のフォルダーにも、そのフォルダーに対して一意な ID が付けられます。 その ID は、フォルダーの他のプロパティを変更しても、変更されることはありません。

識別フォルダー ID は、代理人アクセスのエントリ ポイントとして使用できます。 代理人アクセスを開始すると、アイテムやフォルダーを検索し、識別フォルダー ID を使用して、検索する場所を指定します。 代理人ユーザーがサーバーにアクセスすると、DistinguishedFolderId 要素の子である Mailbox 要素が、代理人がアクセスするメールボックスを明示的に指定するために使用されます。

エラーの処理

どのプログラムにもときおりエラーが発生しますが、EWS ベースのアプリケーションも例外ではありません。 EWS の ResponseCode 要素で、または EWS マネージ API の ServiceError 列挙体の一部分として、識別子に関連するエラーが発生することがあります。

以下は、EWS マネージ API または EWS アプリケーションで発生する可能性のあるエラーです。 EWS マネージ API アプリケーションを操作している際に発生するエラーは、通常はプロパティ値の問題です。EWS アプリケーションでは、エラーは XML 要素値または操作と関連しています。

表 2. 識別子関連のエラー

エラー	発生条件	説明
ErrorCalendarCannotUseIdForOccurrenceId	OccurenceID の値が、有効な定期的な予定表アイテムと一致しないとき。	要求で指定された OccurenceId の値は、正しい構造である可能性がありますが、その値は既存の定期的なマスターと一致しませんでした。 定期的なアイテムが予定表から削除された可能性があります。 アイテムがまだ存在していることと、正しい識別子を使用していることを確認します。
ErrorCalendarCannotUseIdForRecurringMasterId	RecurringMasterId 属性が、OccurrenceId 要素の有効な発生と一致しないとき。	要求で指定された RecurringMasterId の値は、正しい構造である可能性がありますが、その値は既存のアイテムと一致しませんでした。 アイテムが予定表から削除された可能性があります。 アイテムがまだ存在していることと、正しい識別子を使用していることを確認します。
ErrorCannotUseFolderIdForItemId	渡された ID が、アイテムではなくフォルダーを表しているとき。	識別子の形式は正しい可能性がありますが、サーバーが操作しようとしていたものとは異なります。 操作する正しい識別子を参照していることをご確認ください。
ErrorCannotUseItemIdForFolderId	渡された ID が、フォルダーではなくアイテムを表しているとき。	識別子の形式は正しい可能性がありますが、サーバーが操作しようとしていたものとは異なります。 操作する正しい ID を参照していることを確認します。
ErrorChangeKeyRequiredForWriteOperations	特定の更新操作を実行する際に、有効な変更キーを指定する必要があります。	更新を要求したときに ChangeKey 値を省略したか、変更キーが正しくなかったかのいずれかです。 更新操作を実行する場合には、変更キーが正しいことを確認します。
ErrorInvalidAttachmentId	添付物が、アイテムの添付ファイル コレクション内で見つからないとき。	削除された添付物の添付ファイル ID に対して GetAttachment 操作を呼び出すと、この応答コードが返される可能性があります。 添付ファイルが添付ファイル コレクションにあることをご確認ください。
ErrorInvalidChangeKey	使用できない変更キーが渡されました。	変更キーを渡す必要がある操作とメソッドは多くないことにご注意ください。 しかし、変更キーを指定する場合、それは必ずしも最新である必要はありませんが、正しくなければなりません。
ErrorInvalidFolderId	フォルダー ID が破損しているとき。	適切な形式の、正しい識別子があることを確認します。
ErrorInvalidId	ID の構造または変更キーで、内部の整合性に問題があるとき。	Exchange は解析後の ID で問題を検出しました。 変換中にエラーが発生した可能性があります。 たとえば、Outlook のアイテムの IdFormatType.HexEntryId があり、それを IdFormatType.EntryId 形式と判断して、EwsId に変換した場合に、これが発生する可能性があります。 適切な種類の変換をご使用ください。
ErrorInvalidIdEmpty	アプリケーションで空の ID が指定されているとき。	アプリケーションは、識別子として空の文字列を渡しました。 適切な形式の、正しい識別子があることを確認します。
ErrorInvalidIdMalformed	ID の構造で、内部の整合性に問題があるとき。	Exchange は解析後の ID で問題を検出しました。 ID が正しく変換されていない可能性があります。 適切な種類の変換をご使用ください。
ErrorInvalidIdMalformedEwsLegacyIdFormat	Exchange 2007 形式を使用しているフォルダーまたはアイテム ID が、Exchange 2007 SP1 以降のバージョンでの要求に指定されました。	Exchange 2007 の ID を Exchange 2007 SP1 以降の要求で使用することはできません。 先に、ConvertId EWS 操作または EWS マネージ API の ConvertId メソッドを使用して、それらを変換する必要があります。
ErrorInvalidIdNotAnItemAttachmentId	AttachmentId プロパティがアイテムの添付ファイルを参照していないとき。	識別子の形式は正しい可能性がありますが、サーバーが操作しようとしていたものとは異なります。 操作する正しい識別子を参照していることをご確認ください。
ErrorInvalidIdReturnedByResolveNames	メールボックス内の連絡先が破損しているとき。	EWS の ResolveNames 操作または EWS マネージ API のResolveName メソッドが返す識別子が無効のとき。 連絡先を再作成する必要がある場合があります。
ErrorInvalidIdStoreObjectIdTooLong	ID の構造で、内部の整合性に問題があるとき。	Exchange は解析後の ID で問題を検出しました。 ID が正しく変換されていない可能性があります。 適切な種類の変換をご使用ください。
ErrorInvalidIdTooManyAttachmentLevels	添付物の階層が、深さの最大値の 255 レベルを超えているとき。	要求で指定された AttachmentId プロパティの値は、正しい構造である可能性がありますが、要求された添付物の階層が深すぎます。 255 レベルの限度を超えるアイテムをコードが添付しようとしている可能性があります。
ErrorInvalidImContactId	RemoveImContactFromGroup 操作を使用していて、連絡先が IM グループで見つからない場合、このエラーが返される可能性があります。 このエラーは、Exchange Online と Exchange 2013 以降のバージョンの Exchange を対象とするクライアントに適用されます。	要求で指定された ContactId プロパティの値は、正しい構造である可能性がありますが、メールボックス内の連絡先に、この構造と一致するものはありません。 連絡先が既に削除されている可能性があります。
ErrorInvalidImGroupId	RemoveImGroup 操作を行う際にメールボックスでグループが見つからない場合、このエラーが返される場合があります。 このエラーは、Exchange Online と Exchange 2013 以降のバージョンの Exchange を対象とするクライアントに適用されます。	要求で指定された GroupId プロパティの値は、正しい構造である可能性がありますが、メールボックス内のグループに、この構造と一致するものはありません。 グループが既に削除されている可能性があります。
ErrorInvalidReferenceItem	参照されているアイテムの識別子は、MessageType、ExchangeWebServices.CalendarItemTypeType、その子孫の 1 つのいずれでもありません。 参照アイテムの識別子は、CalendarItemType オブジェクト用であり、開催者は返信、または全員に返信しようとしています。	識別子の形式は正しい可能性がありますが、サーバーが操作しようとしていたものとは異なります。 操作する正しい識別子を参照していることをご確認ください。
ErrorMissingManagedFolderId	フォルダーに対してポリシー ID プロパティ (プロパティ タグ 0x6732) が指定されていません。	フォルダーが破損しています。 再作成をご検討ください。

識別子の変換

識別子を、ある形式から別の形式に変換することが必要になる場合があります。 たとえば、EWS の外部からの識別子 (MAPI 接続からの識別子など) を、アプリケーションが使用できる形式に変換することが必要になる場合があります。 これを行うには、EWS の ConvertId 操作または EWS マネージ API の ConvertId メソッドを使用できます。

たとえば、EntryID は、アイテムを保存するときに、ストアによって割り当てられる MAPI メッセージ ストアによって生成される一意の識別子です。 EntryID をアプリケーションで使用するには、最初に EwsId に変換する必要があります。

Outlook Web App は、フォルダーおよびアイテムにアクセスするための URL 内で、独自のバージョンの識別子 (OwaId と呼ばれる) を使用します。 アプリケーションが Outlook Web App のアイテムにアクセスする必要がある場合、OwaId を EwsId に変換する必要があります。

ConvertId 操作またはメソッドを使用して、いくつかの異なる識別子の形式を変換できます。

表 3. Exchange で変換可能な識別子の形式

Format	説明
EwsLegacyId	この EwsId は、Exchange 2007 に適用されます。
EwsId	この EwsId は、Exchange Online、Exchange 2007 SP1 以降のバージョンの Exchange に適用されます。
StoreId	フォルダーとアイテムが格納されている Exchange ストアの識別子です。
OwaId	Exchange 2007 と Exchange 2010 の Outlook Web App で使用する Outlook Web App 識別子です。 注意: Exchange Online と Exchange 2013 以降のバージョンの Exchange は、Outlook Web App で EwsId を使用します。
EntryId	MAPI メッセージの PR_ENTRYID プロパティとして一般的に知られる、MAPI 識別子です。
HexEntryId	PR_ENTRYID プロパティを 16 進数でエンコードした表現で、空き時間の予定表のイベント識別子のために使用されます。 これは、Outlook が使用する識別子の形式でもあります。

関連項目

• Exchange の Web サービス クライアントを開発する
• ConvertId 操作
• ServiceError 列挙体
• Exchange で、EWS を使ってのアイテムの削除