Exchange における EWS のプロパティと拡張プロパティ
Exchange で EWS を使用して、アイテムとフォルダーのプロパティを定義してアクセスできるようにする方法を説明します。
Exchange メールボックスには、電子メール メッセージ、予定、会議など、多数のアイテムが含まれています。 それらのアイテムはプロパティで構成されます。プロパティにはアイテムの記述があります。 アイテムのプロパティを使用して、検索、アイテムの変更の同期、およびカスタム プロパティの種類の作成を行うことができます。 この記事では、プロパティの概要と、アプリケーションでプロパティを使用する方法の概要について扱います。
Exchange のアイテム プロパティ
Exchange のアイテムとフォルダーは、基本的には表内の行です。 アイテムまたはフォルダーを識別する主なプロパティは、EWS 識別子です。 Exchange データベースにはその他の識別子に関連するプロパティがありますが、EWS の場合、EWS 識別子はアイテムを記述するプロパティのコレクションの主キーとして機能します。 EWS の識別子プロパティには、次の 2 つの部分があります。
メールボックス内のすべてのアイテムは、同じ Exchange データベースに格納され、同じデータベース スキーマを使用します。 アイテムは、ItemClass プロパティ、プロパティの制約、および Exchange ストアでの管理方法に影響するビジネス ロジック層、の組み合わせによって識別されます。 表 1 は、様々なアイテムの種類にプロパティが適用される方法を示しています。ここでは、電子メールのアイテムと予定のアイテムの例を取り上げています。 どちらのアイテムも Subject プロパティの値を持っています。 ただし、IsAllDayEvent プロパティは電子メール アイテムに設定されず、IsReadReceiptRequested プロパティは予定アイテムに設定されません。 どのプロパティが各アイテム クラスに適用できるかを知っている必要はなく、その点は EWS が処理してくれます。
表 1. 予定のプロパティと電子メールのプロパティの比較
| アイテムの種類 | アイテム クラス | 件名 | IsAllDayEvent | IsReadReceiptRequested |
|---|---|---|---|---|
| メール |
IPM.Note |
進捗レポート:プロジェクト X の完了 |
NULL |
true |
| Appointment |
IPM.Appointment |
Contoso 全社ミーティング |
false |
NULL |
EWS のスキーマは、Exchange データベースで管理されている、また EWS と Exchange データベースの間のビジネス ロジック層で管理されている制約の多くをサポートしています。 EWS のスキーマは、定義されたプロパティのセットを各アイテムの種類ごとに適用します。 EWS で提供される厳密に型指定された Exchange データベースのアイテムを次に示します。
電子メール メッセージ
予定
連絡先
配布リスト
会議のメッセージ
会議出席依頼
会議の応答
会議のキャンセル
タスク
アイテムの投稿
EWS では、汎用アイテムは電子メール メッセージとして返されます。 EWS マネージ API では、これらすべてのアイテムの種類を実装します。
注:
応答オブジェクトは、他のユーザーから受信したアイテムへの応答として、クライアントによってのみサーバーに送信されます。 応答オブジェクトは、Exchange データベース内には存在しません。
EWS のプロパティとは
EWS のスキーマは、EWS のクライアントと Exchange の間で送信されるデータを記述します。 スキーマの大部分は、Exchange データベースにアクセスできるアイテムとフォルダーのプロパティを記述します。 EWS のスキーマは、アプリケーションで利用可能な Exchange データベースのプロパティの XML 表現について記述します。 実際のプロパティ、利用可能なプロパティ、それらの形式、返す値は、実行しようとしている処理によって異なります。 たとえば、Body プロパティは FindItem 操作の最初の 512 文字のみを返しますが、GetItem 操作は、アイテムのテキスト全体を返します。 ほとんどのプロパティは、設定および取得が可能ですが、一部のプロパティは Exchange によって設定のみ行われます。 各プロパティは、スキーマに XML 形式で存在しており、Exchange データベースに保存される際のプロパティを反映するか、Exchange データベースに保存されているプロパティから計算されます。 Subject プロパティは設定可能なプロパティの例であり、フォルダーの UnreadCount プロパティは、計算されたプロパティの例です。 プロパティのコア セットは、コア アイテムの種類と共通です。
アプリケーションが Exchange から取得するプロパティ セットは、次の要因によって決まります。
アプリケーションが呼び出している操作
基本的な応答の図形
アイテムの種類
指定したプロパティのパス
これらのさまざまな要素が、アクセスできるデータにどのように影響するかを理解することが重要です。 前述した Body プロパティの例のように、いくつかの情報はさまざまな要因に応じて条件付きで利用できます。 これらの要因を理解していると、必要な情報を利用する適切なオプションを選択できるので、時間の節約になります。 どのプロパティが利用できるかを確認するには、これらの要因を吟味して、アプリケーションが必要とするプロパティを利用する方法を判断する必要があります。 ここでは、EWS の応答で返されるプロパティに、これらのさまざまな要因がどのように影響するのか説明します。
EWS の応答の図形
Exchange は、アイテムに関する様々な情報を格納しています。 アプリケーションでは、必ずしもすべての情報を必要としない場合があり、情報をまったく取得しないことが最適な場合も少なくありません。 EWS 応答の図形はプロパティの図形とも呼ばれ、どのプロパティがサーバーから返されるかを示します。 応答の図形の中心となる要素は、基本図形です。 基本図形は、厳密に型指定されたアイテムの既定の事前設定プロパティ バッグです。 EWS マネージ API で基本図形に相当するものは BasePropertySet です。 EWS には、3 つの既定の応答図形が含まれています。
表 2. 既定の応答の図形
| 既定の応答の図形の名前 | EWS マネージ API の同等物 | 説明 |
|---|---|---|
| IdOnly |
BasePropertySet.IdOnly |
EWS 識別子と変更キーのみが返されます。 クライアントは、AllProperties または既定の図形から返されるすべてのプロパティを使用する場合を除き、IdOnly 図形を使用し、PropertySet クラスのプロパティ パス セットを使用して追加のプロパティを指定します。 ほとんどのアプリケーションは、追加のプロパティを指定して IdOnly 応答図形を使用する必要があります。 これにより、クライアントによって要求される不要なデータの量が減少します。 |
| 既定値 |
N/A |
アイテムの種類の標準プロパティのセット。 アプリケーションがプロパティをすべて使用する場合にのみ、この応答の図形を使用します。 |
| AllProperties |
BasePropertySet.FirstClassProperties 値 |
既定の図形よりも大規模なプロパティのセットです。 名前が示すものとは異なり、このオプションはアイテムに対してすべてのプロパティを返すことはしません。 このプロパティ セットは、クライアント アプリケーションで最も頻繁に使用されるプロパティを返します。 追加のプロパティが必要な場合、プロパティ パスを使用して要求できます。 アプリケーションが、この応答の図形で返されたプロパティをすべて使用するわけではない場合、追加のプロパティを指定して IdOnly の応答の図形を使用します。 |
EWS の操作の多くは、アイテムとそのプロパティを返します。 指定した応答の図形に関わりなく、操作が異なれば、異なるプロパティ セットが返ってくることがあります。 また、アイテムの種類が異なると、指定した操作と応答の図形に応じて、異なるプロパティが返されます。 次の操作では、どのプロパティを返すのかを識別するために応答の図形を使用します。
表 3. 応答図形を使用する操作
プロパティの図形は、アプリケーションに返してほしいプロパティを識別する基本的な手段です。 ただし、アプリケーションが特定のプロパティのより洗練されたセットを必要とすることがあります。 これには、プロパティ パスを使用できます。
プロパティ パスによってプロパティを選択する
EWS のプロパティ パスは、要求または応答のいずれかのプロパティを識別するために使用されるメタデータです。
表 4. プロパティ パスの種類
| プロパティ パスの種類 | スキーマの種類 | EWS マネージ API の実装 | 説明 |
|---|---|---|---|
| FieldUri |
PathToUnindexedFieldType |
ServiceObjectSchema から継承される種類。 |
最も一般的なプロパティ パス。 FieldUri プロパティ パスは、EWS マネージ API の PropertySet オブジェクトで指定されます。 FieldUri プロパティ パスでは、EWS のほとんどのプロパティを指定できます。 これは、EWS のスキーマで UnindexedFieldURIType によって記述されます。 FieldUri プロパティ パスの XML は、次のようになります。 XML<FieldURI FieldURI="item:Subject"/>このプロパティのパスは、EWS マネージ API の ItemSchema.Subject に相当します。 |
| IndexedFieldUri |
PathToIndexedFieldType |
ItemSchema から継承される種類。 |
返す値を指定するためにプロパティ インデックスを必要とする、ディクショナリ プロパティを識別します。 プロパティが複数の値を持つことができる場合に、このパスを使用します。 これは、EWS のスキーマで DictionaryURIType プロパティによって記述されます。 DictionaryURIType プロパティ パスは、EWS マネージ API の PropertySet オブジェクトで指定されます。 IndexedFieldUri プロパティ パスの XML は、次のようになります。 XML<IndexedFieldURI FieldURI="contacts:PhysicalAddress:Street FieldIndex="Home"/> |
| ExtendedFieldUri |
PathToExtendedFieldType |
ExtendedPropertyDefinition |
アイテムのカスタム プロパティまたはスキーマ化されていないプロパティを識別する拡張プロパティの定義です。 ExtendedFieldUri プロパティ パスの XML は、次のようになります。 XML<ExtendedFieldURI> PropertyTag="0x1234" PropertyType="Integer" /> |
| ExceptionFieldUri |
ExceptionFieldURI |
ServiceResponse |
EWS の応答のエラーに関連付けられているプロパティを指定します。 これは、EWS のスキーマで ExceptionPropertyURIType 型によって記述されます。 これは、予定表の定期的なパターンを使用しているときに行われるエラー応答の MessageXml 要素でのみ発生します。 |
ベスト プラクティスとして、プロパティを要求するときは、IdOnly 基本図形 (EWS マネージ API の BasePropertySet.IdOnly) を使用し、プロパティのパスを指定することにより、アプリケーションにとって必要なプロパティのみを要求します。
スキーマ化されたプロパティ
EWS クライアントが必要とするプロパティのほとんどは、EWS のスキーマによって記述されます。 主なフォルダーとアイテムの種類の定義は、プロパティの定義を含むもので、Types.xsd スキーマ内にあります。 次のスキーマの種類には、使用できるほとんどのオブジェクトのプロパティの定義が含まれています。
表 5。 プロパティ定義が含まれているスキーマの種類
| EWS のスキーマの種類 | EWS マネージ API の種類の同等物 | 定義対象 |
|---|---|---|
| ItemType |
アイテム クラス |
基本項目の種類のプロパティ セット。 この型はクライアントから作成できますが、Exchange から返されることはありません。 Exchange は、すべてのジェネリック オブジェクトの MessageType オブジェクトを返します。 |
| MessageType |
EmailMessage クラス |
電子メール メッセージ オブジェクトのプロパティ セットとすべての汎用的なオブジェクトのプロパティ セット。 |
| CalendarItemType |
Appointment クラス |
予定表アイテムのプロパティ セット。これには、1 つの定期的な予定が含まれます。 |
| ContactItemType |
Contact クラス |
連絡先アイテムのプロパティ セット。 |
| DistributionListType |
ContactGroup クラス |
個人用配布リストのプロパティ セット。 |
| MeetingMessageType |
MeetingMessage クラス |
会議のメッセージ型のプロパティ セット。 |
| MeetingRequestMessageType |
MeetingRequest クラス |
会議の要求型のプロパティ セット。 |
| MeetingResponseMessageType |
MeetingResponse クラス |
会議の応答型のプロパティ セット。 |
| MeetingCancellationMessageType |
MeetingCancellation クラス |
会議の取り消し型のプロパティ セット。 |
| TaskType |
Task クラス |
タスク型のプロパティ セット。 |
| PostItemType |
PostItem クラス |
Postitem 型のプロパティ セット。 |
| FolderType |
Folder クラス |
フォルダー型のプロパティ セット。 |
| CalendarFolderType |
CalendarFolder クラス |
SearchFolder 型のプロパティ セット。 |
| ContactsFolderType |
ContactsFolder クラス |
ContactsFolder 型のプロパティ セット。 |
| SearchFolderType |
SearchFolder クラス |
SearchFolder 型のプロパティ セット。 |
| TasksFolderType |
TasksFolder クラス |
TasksFolder 型のプロパティ セット。 |
| UserConfigurationType |
UserConfiguration クラス |
UserConfiguration 型のプロパティ セット。 |
EWS スキーマ内のプロパティは、多くのアプリケーションには十分ですが、スキーマで記述されている内容を使用するだけでは実装できないシナリオもあります。 これらのシナリオでは、プロパティを拡張することができます。
拡張プロパティ (別名はスキーマ化されていないプロパティ)
拡張プロパティを使用すると、EWS スキーマで定義されていない Exchange ストア内のアイテムとフォルダーのプロパティにアクセスできるカスタム プロパティを作成できます。 これらを使用して、Exchange データベースのネイティブ MAPI アイテムとフォルダーのプロパティにアクセスできます。 拡張プロパティを使用すると、スキーマ化されたすべてのプロパティにアクセスできます。これらのスキーマ化されたプロパティは、Exchange データベースの MAPI プロパティに過ぎないためです。
Types.xsd スキーマ内にある、PathToExtendedFieldType スキーマ型は、拡張プロパティを表す XML を定義します。 このスキーマの種類は、XML インスタンスの ExtendedFieldURI 要素を定義します。つまり、サービスとクライアント間で送信される XML を定義します。 ExtendedPropertyType スキーマの種類は、ExtendedFieldURI 要素と、拡張プロパティに含まれる値または値の配列の両方を定義します。 次の表は、拡張プロパティの XML のおおよそのマッピングと、EWS マネージ API 内のアイテムの実装方法を示します。
表 6. EWS マネージ API で実装されると、拡張プロパティの XML
| EWS マネージ API の実装 | 内容 | マップ先 |
|---|---|---|
| Item.ExtendedProperties プロパティ |
アイテムの拡張プロパティのコレクション。 |
アイテムの拡張プロパティの 1 つ以上のインスタンス。 |
| ExtendedProperty クラス |
拡張プロパティの定義と値。 |
ExtendedPropertyType スキーマの種類。 |
| ExtendedPropertyDefinition クラス |
拡張プロパティの定義。 |
PathToExtendedFieldType スキーマの種類。 |
アプリケーションで拡張プロパティを使用する方法の詳細については、次のコード サンプルを参照してください。