Outlook の拡張プロパティの概要

  • [アーティクル]

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

注意

Outlook タスクは非推奨となり、2022 年 8 月 10 日にデータの返しを停止しました。 Outlook タスクでこの機能を使用する既存のアプリを更新します。

拡張プロパティを使用すると、カスタム データを格納でき、Microsoft Graph API metadata_でこれらのプロパティがまだ公開されていない場合に、アプリが Outlook MAPI プロパティのカスタム データにアクセスするためのフォールバック メカニズムとして特に機能します。 拡張プロパティ REST API を使用して、次のユーザー リソースにこのようなカスタム データを格納または取得できます。

または、次の Microsoft 365 グループリソースの場合:

拡張プロパティとオープン拡張機能のどちらを使用するか

ほとんどの一般的なシナリオでは、開いている拡張機能 ( openTypeExtension(旧称 Office 365 データ拡張機能) を使用して、ユーザーのメールボックス内のリソース インスタンスのカスタム データを格納およびアクセスできる必要があります。 拡張プロパティは、 Microsoft Graph API メタデータでまだ公開されていない Outlook MAPI プロパティのカスタム データにアクセスする必要がある場合にのみ使用します。

拡張プロパティのタイプ

拡張プロパティに単一の値を保存するか、または (同じ型の) 複数の値を保存するかに応じて、拡張プロパティを singleValueLegacyExtendedProperty、または multiValueLegacyExtendedProperty として作成できます。

これらのタイプはそれぞれ、id によってプロパティを識別し、データを value に格納します。

id を使用して、特定のリソース インスタンスをその拡張プロパティと一緒に取得するか、単一の値の拡張プロパティでフィルターして、そのプロパティのすべてのインスタンスを取得できます。

手記 REST API を使用して、特定のインスタンスのすべての拡張プロパティを 1 回の呼び出しで取得することはできません。

id の形式

拡張プロパティの id は、次の 3 つの形式のいずれかで指定することができます。

  • 名前付きプロパティ - 拡張プロパティの種類、名前空間、および文字列名によって識別されます。
  • 名前付きプロパティ - 拡張プロパティの種類、名前空間、および数値の識別子によって識別されます。
  • proptag の形式 - 拡張プロパティの種類、および MAPI プロパティのタグによって識別されます。

次の 2 つの表では、これらの形式が単一および複数値の拡張プロパティに適用される場合について説明します。 {type} は、拡張プロパティ値の種類を表します。 この例では、これらの種類の文字列、整数、および配列を示しています。

単一値の拡張プロパティに有効な id の形式

形式 例 説明
"{type} {guid} Name {name}" "String {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" 属している名前空間 (GUID) と文字列の名前で、プロパティを識別します。
"{type} {guid} Id {id}" "Integer {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8012" 属している名前空間 (GUID) と数値の識別子で、プロパティを識別します。
"{type} {proptag}" "String 0x4001" 定義済みのプロパティをそのプロパティ タグで識別します。

複数値の拡張プロパティに有効な id の形式

形式 例 説明
"{type} {guid} Name {name}" "StringArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" 名前空間 (GUID) と文字列の名前で、プロパティを識別します。
"{type} {guid} Id {id}" "IntegerArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8013" 名前空間 (GUID) と数値の識別子で、プロパティを識別します。
"{type} {proptag}" "StringArray 0x4002" 定義済みのプロパティをそのプロパティ タグで識別します。

名前付きプロパティ形式のいずれかを使用して、単一値または複数値の拡張プロパティをカスタム プロパティとして定義します。 2 つの形式のうち、文字列名 (Name) を先にとる形式の方が参照しやすいため、推奨形式となります。 名前付きプロパティのプロパティの識別子は、0x8000-0xfffe の範囲にあります。

MAPI、またはクライアントまたはサーバーによって定義済みのプロパティにアクセスするには、proptag 形式を使用します。これは、Microsoft Graph でまだ公開されていません。 これらのプロパティのプロパティ識別子は、0x0001〜0x7fff の範囲にあります。 proptag 形式を使用してカスタム プロパティを定義しないでください。

プロパティ識別子や GUID などの既存の MAPI プロパティへの拡張プロパティのマッピングに関する情報は、[MS-OXPROPS] Microsoft Corporation の "Exchange Server Protocols Master Property List" にあります。

注id に対して 1 つの形式を選択したら、その形式でのみ拡張プロパティにアクセスする必要があります。

REST API の操作

単一値の拡張プロパティの操作:

複数値の拡張プロパティの操作: