Exchange における EWS のプロパティと拡張プロパティProperties and extended properties in EWS in Exchange

Exchange で EWS を使用して、アイテムとフォルダーのプロパティを定義してアクセスできるようにする方法を説明します。Discover how you can define and access properties on items and folders by using EWS in Exchange.

Exchange メールボックスには、電子メール メッセージ、予定、会議など、多数のアイテムが含まれています。An Exchange mailbox contains a large number of items, including email messages, appointments, meetings, and so on. それらのアイテムはプロパティで構成されます。プロパティにはアイテムの記述があります。Those items are made up of properties; the properties describe the items. アイテムのプロパティを使用して、検索アイテムの変更の同期、およびカスタム プロパティの種類の作成を行うことができます。You can use item properties to perform a search, synchronize item changes, and create custom property types. この記事では、プロパティの概要と、アプリケーションでプロパティを使用する方法の概要について扱います。This article provides an overview of properties and how you can work with properties in your application.

Exchange のアイテム プロパティExchange item properties

Exchange のアイテムとフォルダーは、基本的には表内の行です。アイテムまたはフォルダーを識別する主なプロパティは、EWS 識別子です。Exchange データベースにはその他の識別子に関連するプロパティがありますが、EWS の場合、EWS 識別子はアイテムを記述するプロパティのコレクションの主キーとして機能します。EWS の識別子プロパティには、次の 2 つの部分があります。Items and folders in Exchange are essentially rows in tables. The main property that identifies an item or folder is its EWS identifier. Although there are other identifier-related properties in the Exchange database, for EWS, the EWS identifier acts as the primary key for the collection of properties that describe an item. The EWS identifier property contains two parts:

  • アイテムを識別する ItemId プロパティまたは FolderId プロパティAn ItemId or FolderId property that identifies the item

  • アイテムまたはフォルダーが変更されたかどうかに関するステートフルな情報を含む ChangeKey プロパティA ChangeKey property that contains stateful information about whether an item or folder has changed

メールボックス内のすべてのアイテムは、同じ Exchange データベースに格納され、同じデータベース スキーマを使用します。All items in a mailbox are stored in the same Exchange database and use the same database schema. アイテムは、ItemClass プロパティ、プロパティの制約、および Exchange ストアでの管理方法に影響するビジネス ロジック層、の組み合わせによって識別されます。Items are distinguished by a combination of the ItemClass property, property constraints, and the business logic layers that affect how they are managed in the Exchange store. 表 1 は、様々なアイテムの種類にプロパティが適用される方法を示しています。ここでは、電子メールのアイテムと予定のアイテムの例を取り上げています。Table 1 shows how properties are applied across different item types; in this example, email and appointment items. どちらのアイテムも Subject プロパティの値を持っています。Both items have a value for the Subject property. ただし、IsAllDayEvent プロパティは電子メール アイテムに設定されず、IsReadReceiptRequested プロパティは予定アイテムに設定されません。But notice that the IsAllDayEvent property is not set on the email item, and the IsReadReceiptRequested property is not set on the appointment. どのプロパティが各アイテム クラスに適用できるかを知っている必要はなく、その点は EWS が処理してくれます。Fortunately, you don't need to know which properties are applicable for each item class; EWS handles this for you.

表 1. 予定のプロパティと電子メールのプロパティの比較Table 1. Comparison of appointment and email properties

アイテムの種類Item type アイテム クラスItem class 件名Subject IsAllDayEventIsAllDayEvent IsReadReceiptRequestedIsReadReceiptRequested
メールEmail
IPM.NoteIPM.Note
進捗レポート:プロジェクト X の完了Status report: Project X complete
NULLNULL
truetrue
AppointmentAppointment
IPM.AppointmentIPM.Appointment
Contoso 全社ミーティングContoso company meeting
falsefalse
NULLNULL

EWS のスキーマは、Exchange データベースで管理されている、また EWS と Exchange データベースの間のビジネス ロジック層で管理されている制約の多くをサポートしています。EWS のスキーマは、定義されたプロパティのセットを各アイテムの種類ごとに適用します。EWS で提供される厳密に型指定された Exchange データベースのアイテムを次に示します。 The EWS schema supports many of the constraints managed by the Exchange database and the business logic layers between EWS and the Exchange database. The EWS schema applies a defined a set of properties to each item type. The following are the strongly-typed Exchange database items provided by EWS:

  • 電子メール メッセージEmail messages

  • 予定Appointments

  • 連絡先Contacts

  • 配布リストDistribution lists

  • 会議のメッセージMeeting messages

  • 会議出席依頼Meeting requests

  • 会議の応答Meeting responses

  • 会議のキャンセルMeeting cancellations

  • タスクTasks

  • アイテムの投稿Post items

EWS では、汎用アイテムは電子メール メッセージとして返されます。EWS マネージ API では、これらすべてのアイテムの種類を実装します。Generic items are returned by EWS as email messages. The EWS Managed API implements all these item types.

注意

応答オブジェクトは、他のユーザーから受信したアイテムへの応答として、クライアントによってのみサーバーに送信されます。応答オブジェクトは、Exchange データベース内には存在しません。Response objects are only sent by the client to the server in response to items received from other people. They do not exist in the Exchange database.

EWS のプロパティとはWhat are properties in EWS?

EWS のスキーマは、EWS のクライアントと Exchange の間で送信されるデータを記述します。The EWS schema describes the data that is sent between an EWS client and Exchange. スキーマの大部分は、Exchange データベースにアクセスできるアイテムとフォルダーのプロパティを記述します。A large part of the schema describes the item and folder properties that you can access in the Exchange database. EWS のスキーマは、アプリケーションで利用可能な Exchange データベースのプロパティの XML 表現について記述します。The EWS schema describes the XML representation of the Exchange database properties that are available to your application. 実際のプロパティ、利用可能なプロパティ、それらの形式、返す値は、実行しようとしている処理によって異なります。The actual properties, in terms of which properties are available, what form they take, and the values they return, vary based on what you trying to do. たとえば、Body プロパティは FindItem 操作の最初の 512 文字のみを返しますが、GetItem 操作は、アイテムのテキスト全体を返します。For example, the Body property will only return the first 512 characters in a FindItem operation, but the GetItem operation returns the full text of the item. ほとんどのプロパティは、設定および取得が可能ですが、一部のプロパティは Exchange によって設定のみ行われます。Although most properties are both settable and retrievable, some properties are only set by Exchange. 各プロパティは、スキーマに XML 形式で存在しており、Exchange データベースに保存される際のプロパティを反映するか、Exchange データベースに保存されているプロパティから計算されます。Each property exists in the schema in an XML format that either reflects the property as it is stored in the Exchange database, or is computed from properties stored in the Exchange database. Subject プロパティは設定可能なプロパティの例であり、フォルダーの UnreadCount プロパティは、計算されたプロパティの例です。The Subject property is an example of a settable property; the UnreadCount property on a folder is an example of a computed property. プロパティのコア セットは、コア アイテムの種類と共通です。A core set of properties are common to the core item types.

アプリケーションが Exchange から取得するプロパティ セットは、次の要因によって決まります。The following factors determine the property set that your application gets from Exchange:

  • アプリケーションが呼び出している操作The operation that your application is calling

  • 基本的な応答の図形The base response shape

  • アイテムの種類The item type

  • 指定したプロパティのパスThe specified property paths

これらのさまざまな要素が、アクセスできるデータにどのように影響するかを理解することが重要です。It is important to understand how these different factors affect the data that you can access. 前述した Body プロパティの例のように、いくつかの情報はさまざまな要因に応じて条件付きで利用できます。As with the example of the Body property mentioned earlier, some information is conditionally available depending on various factors. これらの要因を理解していると、必要な情報を利用する適切なオプションを選択できるので、時間の節約になります。Understanding these factors might save you time by helping you choose the correct options to access the information you want. どのプロパティが利用できるかを確認するには、これらの要因を吟味して、アプリケーションが必要とするプロパティを利用する方法を判断する必要があります。To discover which properties are accessible, you will need to test these factors to determine how to access the properties your application needs. ここでは、EWS の応答で返されるプロパティに、これらのさまざまな要因がどのように影響するのか説明します。This section describes how these different factors affect which properties are returned in EWS responses.

EWS の応答の図形EWS response shapes

Exchange は、アイテムに関する様々な情報を格納しています。Exchange stores a lot of information about items. アプリケーションでは、必ずしもすべての情報を必要としない場合があり、情報をまったく取得しないことが最適な場合も少なくありません。Sometimes, your application doesn't need all of that information, and in many cases, it is best not to get it all. EWS 応答の図形はプロパティの図形とも呼ばれ、どのプロパティがサーバーから返されるかを示します。EWS response shapes, also called property shapes, indicate which properties are returned from the server. 応答の図形の中心となる要素は、基本図形です。The core element of the response shape is the base shape. 基本図形は、厳密に型指定されたアイテムの既定の事前設定プロパティ バッグです。A base shape is a default preset property bag for strongly typed items. EWS マネージ API で基本図形に相当するものは BasePropertySet です。The EWS Managed API equivalent of the base shape is the BasePropertySet. EWS には、3 つの既定の応答図形が含まれています。EWS includes three default response shapes.

表 2. 既定の応答の図形Table 2. Default response shapes

既定の応答の図形の名前Default response shape name EWS マネージ API の同等物EWS Managed API equivalent 説明Description
IdOnlyIdOnly
BasePropertySet.IdOnlyBasePropertySet.IdOnly value
EWS 識別子と変更キーのみが返されます。Only the EWS identifier and change key are returned. クライアントは、AllProperties または既定の図形から返されるすべてのプロパティを使用する場合を除き、IdOnly 図形を使用し、PropertySet クラスのプロパティ パス セットを使用して追加のプロパティを指定します。Unless the client uses all the properties returned by the AllProperties or Default shape, use the IdOnly shape and specify additional properties by using the property path set on the PropertySet class. ほとんどのアプリケーションは、追加のプロパティを指定して IdOnly 応答図形を使用する必要があります。Most applications should use the IdOnly response shape with additional properties specified. これにより、クライアントによって要求される不要なデータの量が減少します。This reduces the amount of unused data that is requested by clients.
既定値Default
N/AN/A
アイテムの種類の標準プロパティのセット。アプリケーションがプロパティをすべて使用する場合にのみ、この応答の図形を使用します。 A set of standard properties for the item type. Only use this response shape if your application uses all the properties.
AllPropertiesAllProperties
BasePropertySet.FirstClassProperties 値BasePropertySet.FirstClassProperties value
既定の図形よりも大規模なプロパティのセットです。名前が示すものとは異なり、このオプションはアイテムに対してすべてのプロパティを返すことはしません。このプロパティ セットは、クライアント アプリケーションで最も頻繁に使用されるプロパティを返します。追加のプロパティが必要な場合、プロパティ パスを使用して要求できます。 A larger set of properties than the Default shape. Although the name implies it, this option does not return all properties on an item. This property set returns the properties that client applications use most often. If you need additional properties, you can request them by their property path.
アプリケーションが、この応答の図形で返されたプロパティをすべて使用するわけではない場合、追加のプロパティを指定して IdOnly の応答の図形を使用します。If your application doesn't use all the properties returned with this response shape, use the IdOnly response shape with additional properties specified.

EWS の操作の多くは、アイテムとそのプロパティを返します。指定した応答の図形に関わりなく、操作が異なれば、異なるプロパティ セットが返ってくることがあります。また、アイテムの種類が異なると、指定した操作と応答の図形に応じて、異なるプロパティが返されます。次の操作では、どのプロパティを返すのかを識別するために応答の図形を使用します。Many EWS operations return items and their properties. Regardless of the response shapes that you specify, different operations can return different property sets. Different item types also return different properties, depending on the operation and the response shape specified. The following operations use response shapes to identify which properties to return.

表 3. 応答の図形を使用する操作Table 3. Operations that use response shapes

EWS 操作EWS operation EWS マネージ API メソッドEWS Managed API method
GetConversationItemsGetConversationItems
ExchangeService.GetConversationItems メソッドExchangeService.GetConversationItems method
GetFolderGetFolder
Folder.Bind メソッドFolder.Bind method
GetItemGetItem
Item.Bind メソッドItem.Bind method
ExchangeService.BindToItems メソッドExchangeService.BindToItems method
FindConversationFindConversation
ExchangeService.FindConversation メソッドExchangeService.FindConversation method
FindFolderFindFolder
Folder.FindFolders メソッドFolder.FindFolders method
ExchangeService.FindFolders メソッドExchangeService.FindFolders method
FindItemFindItem
Folder.FindItems メソッドFolder.FindItems method
ExchangeService.FindItems メソッドExchangeService.FindItems method
FindPeopleFindPeople
実装されていません。Not implemented.
ResolveNamesResolveNames
ExchangeService.ResolveNames メソッドExchangeService.ResolveNames method
SearchMailboxesSearchMailboxes
ExchangeService.SearchMailboxes メソッドExchangeService.SearchMailboxes method
ExchangeService.BeginSearchMailboxes メソッドExchangeService.BeginSearchMailboxes method
SyncFolderHierarchySyncFolderHierarchy
ExchangeService.SyncFolderHierarchy メソッドExchangeService.SyncFolderHierarchy method
SyncFolderItemsSyncFolderItems
ExchangeService.SyncFolderItems メソッドExchangeService.SyncFolderItems method

プロパティの図形は、アプリケーションに返してほしいプロパティを識別する基本的な手段です。ただし、アプリケーションが特定のプロパティのより洗練されたセットを必要とすることがあります。これには、プロパティ パスを使用できます。Property shapes are one, rudimentary way to identify the properties that you want your application to return. Sometimes, however, your application needs a more refined set of specific properties. For this, you can use the property path.

プロパティ パスによってプロパティを選択するChoose properties by their property path

EWS のプロパティ パスは、要求または応答のいずれかのプロパティを識別するために使用されるメタデータです。An EWS property path is metadata that is used to identify properties in either a request or response.

表 4. プロパティ パスの種類Table 4. Property path types

プロパティ パスの種類Property path type スキーマの種類Schema type EWS マネージ API の実装EWS Managed API implementation 説明Description
FieldUriFieldUri
PathToUnindexedFieldTypePathToUnindexedFieldType
ServiceObjectSchema から継承される種類。Types that inherit from ServiceObjectSchema.
最も一般的なプロパティ パス。The most common property path. FieldUri プロパティ パスは、EWS マネージ API の PropertySet オブジェクトで指定されます。FieldUri property paths are specified on a PropertySet object in the EWS Managed API. FieldUri プロパティ パスでは、EWS のほとんどのプロパティを指定できます。Most EWS properties can be specified by the FieldUri property path. これは、EWS のスキーマで UnindexedFieldURIType によって記述されます。This is described by the UnindexedFieldURIType in the EWS schema.
FieldUri プロパティ パスの XML は、次のようになります。The FieldUri property path XML looks like this:
XML<FieldURI FieldURI="item:Subject"/>このプロパティのパスは、EWS マネージ API の ItemSchema.Subject に相当します。XML<FieldURI FieldURI="item:Subject"/>This property path is the equivalent of ItemSchema.Subject in the EWS Managed API.
IndexedFieldUriIndexedFieldUri
PathToIndexedFieldTypePathToIndexedFieldType
ItemSchema から継承される種類。Types that inherit from ItemSchema.
返す値を指定するためにプロパティ インデックスを必要とする、ディクショナリ プロパティを識別します。Identifies dictionary properties that require a property index to specify the value to return. プロパティが複数の値を持つことができる場合に、このパスを使用します。Use this path when a property can have more than one value. これは、EWS のスキーマで DictionaryURIType プロパティによって記述されます。This is described by the DictionaryURIType property in the EWS schema. DictionaryURIType プロパティ パスは、EWS マネージ API の PropertySet オブジェクトで指定されます。DictionaryURIType property paths are specified on a PropertySet object in the EWS Managed API.
IndexedFieldUri プロパティ パスの XML は、次のようになります。The IndexedFieldUri property path XML looks like this:
XML<IndexedFieldURI FieldURI="contacts:PhysicalAddress:Street FieldIndex="Home"/>
ExtendedFieldUriExtendedFieldUri
PathToExtendedFieldTypePathToExtendedFieldType
ExtendedPropertyDefinitionExtendedPropertyDefinition
アイテムのカスタム プロパティまたはスキーマ化されていないプロパティを識別する拡張プロパティの定義です。Identifies an extended property definition that identifies custom or non-schematized properties on items.
ExtendedFieldUri プロパティ パスの XML は、次のようになります。The ExtendedFieldUri property path XML looks like this:
XML<ExtendedFieldURI> PropertyTag="0x1234" PropertyType="Integer" />
ExceptionFieldUriExceptionFieldUri
ExceptionFieldURIExceptionFieldURI
ServiceResponseServiceResponse
EWS の応答のエラーに関連付けられているプロパティを指定します。Specifies properties that are associated with an error in an EWS response. これは、EWS のスキーマで ExceptionPropertyURIType 型によって記述されます。This is described by the ExceptionPropertyURIType type in the EWS schema. これは、予定表の定期的なパターンを使用しているときに行われるエラー応答の MessageXml 要素でのみ発生します。This only occurs in the MessageXml element of error responses that occur when you are working with calendar recurrence patterns.

ベスト プラクティスとして、プロパティを要求するときは、IdOnly 基本図形 (EWS マネージ API の BasePropertySet.IdOnly) を使用し、プロパティのパスを指定することにより、アプリケーションにとって必要なプロパティのみを要求します。As a best practice, when you request properties, use the IdOnly base shape (BasePropertySet.IdOnly in the EWS Managed API) and then request only the properties your application needs by specifying the property paths.

スキーマ化されたプロパティSchematized properties

EWS クライアントが必要とするプロパティのほとんどは、EWS のスキーマによって記述されます。Most of the properties that your EWS client needs are described by the EWS schema. 主なフォルダーとアイテムの種類の定義は、プロパティの定義を含むもので、Types.xsd スキーマ内にあります。The primary folder and item type definitions, which contain the property definitions, are found in the types.xsd schema. 次のスキーマの種類には、使用できるほとんどのオブジェクトのプロパティの定義が含まれています。The following schema types contain the property definitions for most objects that you can use.

表 5. プロパティ定義が含まれているスキーマの種類Table 5. Schema types that contain property definitions

EWS のスキーマの種類EWS schema type EWS マネージ API の種類の同等物EWS Managed API type equivalent 定義対象Defines the…
ItemTypeItemType
アイテム クラスItem class
基本アイテム型のプロパティ セットこの型は、クライアントから作成することができますが、Exchange によって返されることはありません。Exchange は、汎用的なすべてのオブジェクトに対して MessageType オブジェクトを返します。Base item type property set. This type can be created from a client but is never returned by Exchange. Exchange returns a MessageType object for all generic objects.
MessageTypeMessageType
EmailMessage クラスEmailMessage class
電子メール メッセージ オブジェクトのプロパティ セットとすべての汎用的なオブジェクトのプロパティ セット。Email message object property set and the property set for all generic objects.
CalendarItemTypeCalendarItemType
Appointment クラスAppointment class
予定表アイテムのプロパティ セット。これには、1 つの定期的な予定が含まれます。Calendar item property set; this includes single and recurring appointments.
ContactItemTypeContactItemType
Contact クラスContact class
連絡先アイテムのプロパティ セット。Contact item property set.
DistributionListTypeDistributionListType
ContactGroup クラスContactGroup class
個人用配布リストのプロパティ セット。Personal distribution list property set.
MeetingMessageTypeMeetingMessageType
MeetingMessage クラスMeetingMessage class
会議のメッセージ型のプロパティ セット。Meeting message type property set.
MeetingRequestMessageTypeMeetingRequestMessageType
MeetingRequest クラスMeetingRequest class
会議の要求型のプロパティ セット。Meeting request type property set.
MeetingResponseMessageTypeMeetingResponseMessageType
MeetingResponse クラスMeetingResponse class
会議の応答型のプロパティ セット。Meeting response type property set.
MeetingCancellationMessageTypeMeetingCancellationMessageType
MeetingCancellation クラスMeetingCancellation class
会議の取り消し型のプロパティ セット。Meeting cancellation type property set.
TaskTypeTaskType
Task クラスTask class
タスク型のプロパティ セット。Task type property set.
PostItemTypePostItemType
PostItem クラスPostItem class
Postitem 型のプロパティ セット。Postitem type property set.
FolderTypeFolderType
Folder クラスFolder class
フォルダー型のプロパティ セット。Folder type property set.
CalendarFolderTypeCalendarFolderType
CalendarFolder クラスCalendarFolder class
SearchFolder 型のプロパティ セット。SearchFolder type property set.
ContactsFolderTypeContactsFolderType
ContactsFolder クラスContactsFolder class
ContactsFolder 型のプロパティ セット。ContactsFolder type property set.
SearchFolderTypeSearchFolderType
SearchFolder クラスSearchFolder class
SearchFolder 型のプロパティ セット。SearchFolder type property set.
TasksFolderTypeTasksFolderType
TasksFolder クラスTasksFolder class
TasksFolder 型のプロパティ セット。TasksFolder type property set.
UserConfigurationTypeUserConfigurationType
UserConfiguration クラスUserConfiguration class
UserConfiguration 型のプロパティ セット。UserConfiguration type property set.

EWS スキーマ内のプロパティは、多くのアプリケーションには十分ですが、スキーマで記述されている内容を使用するだけでは実装できないシナリオもあります。While the properties in the EWS schema are sufficient for many applications, you can't implement some scenarios by using only what is described in the schema. これらのシナリオでは、プロパティを拡張することができます。For those scenarios, you can extended properties.

拡張プロパティ (別名はスキーマ化されていないプロパティ)Extended properties (aka non-schematized properties)

拡張プロパティを使用すると、EWS のスキーマで定義されていない Exchange ストア内のアイテムとフォルダーのプロパティにアクセスするためのカスタム プロパティを作成できます。これらを使用して、Exchange データベースのネイティブの MAPI アイテムおよびフォルダーのプロパティにアクセスできます。拡張プロパティを使用して、スキーマ化されたすべてのプロパティにアクセスできます。これは実際には、これらのスキーマ化されたプロパティは単なる Exchange データベースの MAPI プロパティであるためです。 Extended properties enable you to create custom properties, which give you access to properties on items and folders in the Exchange store that are not defined in the EWS schema. You can use them to access the native MAPI item and folder properties in the Exchange database. You can use extended properties to access all the schematized properties, because under the covers, those schematized properties are nothing more than MAPI properties in the Exchange database.

Types.xsd スキーマ内にある、PathToExtendedFieldType スキーマ型は、拡張プロパティを表す XML を定義します。The PathToExtendedFieldType schema type, located in the types.xsd schema, defines the XML that represents an extended property. このスキーマの種類は、XML インスタンスの ExtendedFieldURI 要素を定義します。つまり、サービスとクライアント間で送信される XML を定義します。This schema type defines the ExtendedFieldURI element in XML instances; in other words, it defines the XML that is sent between the service and client. ExtendedPropertyType スキーマの種類は、ExtendedFieldURI 要素と、拡張プロパティに含まれる値または値の配列の両方を定義します。The ExtendedPropertyType schema type defines both the ExtendedFieldURI element and the value or array of values that an extended property contains. 次の表は、拡張プロパティの XML のおおよそのマッピングと、EWS マネージ API 内のアイテムの実装方法を示します。The following table shows the approximate mapping of the extended property XML and how it is implemented on items in the EWS Managed API.

表 6. EWS マネージ API で実装されると、拡張プロパティの XMLTable 6. Extended property XML as implemented in the EWS Managed API

EWS マネージ API の実装EWS Managed API implementation 内容What it contains マップ先What it maps to
Item.ExtendedProperties プロパティItem.ExtendedProperties property
アイテムの拡張プロパティのコレクション。A collection of extended properties on an item.
アイテムの拡張プロパティの 1 つ以上のインスタンス。One or more instances of extended properties on an item.
ExtendedProperty クラスExtendedProperty class
拡張プロパティの定義と値。The extended property definition and values.
ExtendedPropertyType スキーマの種類。The ExtendedPropertyType schema type.
ExtendedPropertyDefinition クラスExtendedPropertyDefinition class
拡張プロパティの定義。An extended property definition.
PathToExtendedFieldType スキーマの種類。The PathToExtendedFieldType schema type.

アプリケーションで拡張プロパティを使用する方法の詳細については、次のコード サンプルを参照してください。If you want to learn more about how you can use extended properties in your application, you can explore the following code samples:

このセクションの内容In this section

関連項目See also