Freigeben über

Outlook Erweiterte Eigenschaften-REST-API-Verweis

  • Artikel

Gilt für: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Hinweis

Diese Version der Dokumentation behandelt die Outlook erweiterte Eigenschaften-REST-API in der Vorschauversion. Die Funktionen der Vorschauversion können vor der Fertigstellung geändert werden und können den Code, der sie verwendet, unterbrechen. Aus diesem Grund sollten Sie in der Regel nur eine Produktionsversion einer API in Ihrem Produktionscode verwenden. Falls verfügbar, ist v2.0 derzeit die bevorzugte Version.

Die Outlook erweiterte Eigenschaften-REST-API ermöglicht es Anwendungen, benutzerdefinierte Daten zu speichern und bietet ihnen einen Fallback-Mechanismus, um auf benutzerdefinierte Daten für Outlook MAPI-Eigenschaften zuzugreifen, wenn diese Eigenschaften nicht bereits in den Outlook REST-API-Metadaten enthalten sind. Sie können die erweiterte Eigenschaften-API verwenden, um solche benutzerdefinierten Daten in einer Nachricht, einem E-Mail-Ordner, einem Ereignis, einem Kalender, einem Kontakt, einem Kontaktordner, einer Aufgabe oder einem Aufgabenordner im Konto des angemeldeten Benutzers zu speichern oder abzurufen. Das Konto kann sich in Office 365 oder in einem Microsoft-Konto (Hotmail.com, Live.com, MSN.com, Outlook.com und Passport.com) befinden.

Hinweis

Zur Vereinfachung der Referenz verwendet der Rest dieses Artikels Outlook.com, um diese Microsoft-Kontodomänen aufzunehmen.

Sie interessieren sich nicht für die Beta-Version der API? Wechseln Sie im Inhaltsverzeichnis auf der linken Seite zu Office 365 REST API reference und wählen Sie die gewünschte Version aus.

Verwenden der erweiterten Eigenschaften-REST-API

Erweiterte Eigenschaften oder Datenerweiterungen?

Verwenden Sie erweiterte Eigenschaften und diese REST-API nur, wenn Sie auf benutzerdefinierte Daten für Outlook MAPI-Eigenschaften zugreifen müssen, die nicht bereits über die Outlook REST-API-Metadaten verfügbar sind. Für die meisten Szenarien sollten Sie Office 365 Datenerweiterungen und deren REST-API verwenden, um benutzerdefinierte Daten für Elemente im Postfach des Benutzers zu speichern und darauf zuzugreifen. Sie können überprüfen, welche Eigenschaften die Metadaten bei https://outlook.office.com/api/{version}/$metadata anzeigen, indem Sie {version} durch v2.0, beta, etc. ersetzen.

Authentifizierung

Wie für andere Outlook-REST-API sollten Sie für jede Anforderung an die erweiterte Eigenschaften-API ein gültiges Zugriffstoken angeben. Um ein Zugriffstoken zu erhalten, müssen Sie sich registriert und Ihre App identifiziert und die entsprechende Autorisierung erhalten haben.

Sie können mehr über einige optimierte Registrierungs- und Autorisierungsoptionen für Sie herausfinden. Beachten Sie dies, wenn Sie mit den spezifischen Operationen in der erweiterte Eigenschaften-API fortfahren.

Version der API

Diese API wurde von der Vorschauversion auf den Status Allgemeine Verfügbarkeit (GA) befördert. Sie wird in den v2.0 und Beta-Versionen der Outlook-REST-API unterstützt.

Unterstützte REST-Ressourcen

Sie können erweiterte Eigenschaften für Instanzen der folgenden Ressourcen anlegen:

Die Ressource muss sich im Postfach des angemeldeten Benutzers in Office 365 oder Outlook.com befinden.

URL-Parameter

Die Beispiele in diesem Artikel verwenden die folgenden ID-Platzhalter in den Parametern für REST-Anforderungs-URLs. Sie müssen die ID der Instanz der Ressource angeben, für die Sie eine Erweiterung anlegen wollen.

Parameter Typ Beschreibung
URL-Parameter
calendar_id Zeichenfolge Die Kalender-ID.
contact_id Zeichenfolge Die Kontakt-ID.
contactFolder_id Zeichenfolge Die Kontaktordner-ID.
event_id Zeichenfolge Die Ereignis-ID.
mailFolder_id Zeichenfolge Die Mail-Ordner-ID.
message_id Zeichenfolge Die Nachrichten-ID.
propertyId_value Zeichenfolge Ein PropertyId-Wert in einem der unterstützten Formate.
property_value Zeichenfolge Der Wert einer erweiterten Eigenschaft.
task_id Zeichenfolge Die Aufgaben-ID.
taskFolder_id Zeichenfolge Die Aufgabenordner-ID.

Weitere Informationen, die allen Untergruppen von Outlook-REST-API gemeinsam sind, finden Sie unter Outlook-REST-API verwenden.

Übersicht

Sie können Daten dynamisch in der erweiterten Eigenschaft einer Entitätsinstanz erstellen und speichern. Je nachdem, ob Sie einzelne oder mehrere Werte (vom gleichen Typ) speichern möchten, können Sie die erweiterte Eigenschaft als SingleValueLegacyExtendedProperty oder als MultiValueLegacyExtendedProperty erstellen.

Jeder dieser Typen identifiziert die Eigenschaft nach ihrer PropertyId und speichert Daten als Wert.

Sie können die PropertyId verwenden, um eine spezifische Entitätsinstanz zusammen mit der erweiterten Eigenschaft abzurufen, oder Sie können nach einer einwertigen erweiterten Eigenschaft filtern, um alle Instanzen mit dieser Eigenschaft abzurufen.

Hinweis

Sie können die REST-API nicht verwenden, um alle erweiterten Eigenschaften einer bestimmten Instanz in einem Aufruf abzurufen.

PropertyId-Formate

Wenn Sie eine ein- oder mehrwertige erweiterte Eigenschaft erstellen, können Sie die PropertyId in einem von zwei Formaten angeben, basierend entweder auf einem Namen mit Zeichenfolge oder einem numerischen Bezeichner und auf dem tatsächlichen Typ des Wertes oder der Werte der Eigenschaft. Die folgenden zwei Tabellen enthalten die unterstützten Formate zum Angeben von ein- oder mehrwertigen erweiterten Eigenschaften. {_type_} stellt den Typ des Werts bzw. der Werte für die Eigenschaft dar. In den Beispielen sind dies Zeichenfolgen, ganze Zahlen und Arrays dieser Typen.

Da erweiterte Eigenschaften in den meisten Fällen mit definierten MAPI-Eigenschaften zusammenarbeiten, die nicht in den Microsoft Graph-API-Metadaten verfügbar gemacht wurden, sollte das Format der Einfachheit halber angeben, ob die entsprechende MAPI-Eigenschaft eine Zeichenfolge aus Zeichen oder einen numerischen Wert in ihrem MAPI-Eigenschaftsbezeichner verwendet. Informationen, die Sie in solch einem Fall zum Zuordnen einer erweiterten Eigenschaft zu einer vorhandenen MAPI-Eigenschaft wie dem Eigenschaftsbezeichner und der GUID bräuchten, finden Sie unter [MS-OXPROPS] Microsoft Corporation, „Eigenschaften für Exchange Server-Protokolle“.

Hinweis

Nachdem Sie ein Format für die ID ausgewählt haben, sollten Sie nur mit diesem Format auf die betreffende erweiterte Eigenschaft zugreifen.

Gültige PropertyId-Formate für einwertige erweiterte Eigenschaften

Format Beispiel Beschreibung
„{type} {guid} Name {name}“ "String {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" Identifiziert eine Eigenschaft nach dem Namespace (der GUID), zu dem sie gehört, und einem Namen.
„{type} {guid} Id {id}“ "Integer {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8012" Identifiziert eine Eigenschaft nach dem Namespace (der GUID), zu dem sie gehört, und einem Bezeichner.

Gültige PropertyId-Formate für mehrwertige erweiterte Eigenschaften

Format Beispiel Beschreibung
„{type} {guid} Name {name}“ "StringArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty" Identifiziert eine Eigenschaft nach Namespace (der GUID) und Namen.
„{type} {guid} Id {id}“ "IntegerArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8013" Identifiziert eine Eigenschaft nach Namespace (der GUID) und Bezeichner.

Operationen mit erweiterten Eigenschaften

Erzeugen einer erweiterten Eigenschaft in einem vorhandenen Element

Erstellen Sie eine oder mehrere erweiterte Eigenschaften für die angegebene Instanz einer unterstützten Ressource. Jede erweiterte Eigenschaft kann ein- oder mehrwertig sein.

PATCH https://outlook.office.com/api/beta/me/messages('{message_id}')
PATCH https://outlook.office.com/api/beta/me/events('{event_id}')
PATCH https://outlook.office.com/api/beta/me/contacts('{contact_id}')
PATCH https://outlook.office.com/api/beta/me/tasks('{task_id}')
PATCH https://outlook.office.com/api/beta/me/mailfolders('{mailFolder_id}')
PATCH https://outlook.office.com/api/beta/me/calendars('{calendar_id}')
PATCH https://outlook.office.com/api/beta/me/contactfolders('{contactFolder_id}')
PATCH https://outlook.office.com/api/beta/me/taskfolders('{taskFolder_id}')

Minimal benötigter Bereich

Einer der folgenden Lese- / Schreibbereiche für die Zielressource:

Parameter Typ Beschreibung
Textparameter
SingleValueExtendedProperties Sammlung (SingleValueLegacyExtendedProperty) Ein Array aus einer oder mehreren einwertigen erweiterten Eigenschaften.
PropertyId Zeichenfolge Geben Sie für jede Eigenschaft in der SingleValueExtendedProperties-Sammlung dies an, um die Eigenschaft zu identifizieren. Es muss einem der unterstützten Formate für einwertige erweiterte Eigenschaften folgen. Erforderlich.
Wert Zeichenfolge Geben Sie für jede Eigenschaft in der SingleValueExtendedProperties-Sammlung den Eigenschaftswert an. Erforderlich.
MultiValueExtendedProperties Sammlung (MultiValueLegacyExtendedProperty) Ein Array aus einer oder mehreren mehrwertigen erweiterten Eigenschaften.
PropertyId Zeichenfolge Geben Sie für jede Eigenschaft in der MultiValueExtendedProperties-Sammlung dies an, um die Eigenschaft zu identifizieren. Es muss einem der unterstützten Formate für mehrwertige erweiterte Eigenschaften folgen. Erforderlich.
Wert Sammlung (Zeichenfolge) Geben Sie für jede Eigenschaft in der MultiValueExtendedProperties-Sammlung die Werte für diese Eigenschafte an. Erforderlich.

Beispielanfrage

Das erste Beispiel erzeugt eine einwertige erweiterte Eigenschaft für die angegebene Nachricht. Diese erweiterte Eigenschaft ist das einzige Element im Array SingleValueExtendedProperties. Der Anforderungstext enthält folgendes für die erweiterte Eigenschaft:

  • PropertyId gibt den Eigenschaftstyp als string, die GUID und die Color-Eigenschaft an.
  • Wert gibt Green als den Wert der Color-Eigenschaft an.
PATCH https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')

Content-Type: application/json

{
  "SingleValueExtendedProperties": [
      {
         "PropertyId":"String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
         "Value":"Green"
      }
    ]
}

Beispielantwort

Eine erfolgreiche Antwort wird mit dem Antwortcode HTTP 200 OK gekennzeichnet und enthält die angegebene Nachricht im Antworttext, ähnlich wie die Antwort, die zurückgegeben wird, wenn Sie eine Nachricht aktualisieren. Die Antwort enthält nicht die neu erstellte erweiterte Eigenschaft.

Beispielanfrage

Das zweite Beispiel erzeugt eine mehrwertige erweiterte Eigenschaft für die angegebene Nachricht. Diese Eigenschaft ist das einzige Element im Array MultiValueExtendedProperties. Der Anforderungstext umfasst:

  • PropertyId definiert die Eigenschaft als ein Array von Zeichenfolgen mit der angegebenen GUID und dem Namen Palette.
  • Value: Dieser Parameter definiert Palette als ein Array von 3 Zeichenfolgewerten, ["Green", "Aqua", "Blue"].
PATCH https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2_as77AACHsLrBBBA=')

Content-Type: application/json

{
  "MultiValueExtendedProperties": [
      {
         "PropertyId":"StringArray {66f5a359-4659-4830-9070-00049ec6ac6e} Name Palette",
         "Value":["Green", "Aqua", "Blue"]
      }
    ]
}

Beispielantwort

Eine erfolgreiche Antwort wird mit dem Antwortcode HTTP 200 OK gekennzeichnet und enthält die angegebene Nachricht im Antworttext, ähnlich wie die Antwort, die zurückgegeben wird, wenn Sie eine Nachricht aktualisieren. Die Antwort enthält nicht die neu erstellte erweiterte Eigenschaft.

Möchten Sie die neu erstellte erweiterte Eigenschaft sehen, müssen Sie die um die erweiterte Eigenschaft erweiterte Nachricht abrufen.

Erweiterte Eigenschaft in einem neuen Element anlegen

Erstellen Sie eine oder mehrere erweiterte Eigenschaften beim Erstellen einer neuen Instanz einer unterstützten Ressource, alle im selben POST-Aufruf. Fügen Sie die erweiterte(n) Eigenschaft(en) in den Text der POST-Anforderung ein.

POST https://outlook.office.com/api/beta/me/messages
POST https://outlook.office.com/api/beta/me/events
POST https://outlook.office.com/api/beta/me/contacts
POST https://outlook.office.com/api/beta/me/tasks
POST https://outlook.office.com/api/beta/me/mailfolders
POST https://outlook.office.com/api/beta/me/calendars
POST https://outlook.office.com/api/beta/me/contactfolders
POST https://outlook.office.com/api/beta/me/taskfolders

Minimal benötigter Bereich

Einer der folgenden Lese- / Schreibbereiche für die Zielressource:

Parameter Typ Beschreibung
Textparameter
SingleValueExtendedProperties Sammlung (SingleValueLegacyExtendedProperty) Ein Array aus einer oder mehreren einwertigen erweiterten Eigenschaften.
PropertyId Zeichenfolge Geben Sie für jede Eigenschaft in der SingleValueExtendedProperties-Sammlung dies an, um die Eigenschaft zu identifizieren. Es muss einem der unterstützten Formate für einwertige erweiterte Eigenschaften folgen. Erforderlich.
Wert Zeichenfolge Geben Sie für jede Eigenschaft in der SingleValueExtendedProperties-Sammlung den Eigenschaftswert an. Erforderlich.
MultiValueExtendedProperties Sammlung (MultiValueLegacyExtendedProperty) Ein Array aus einer oder mehreren mehrwertigen erweiterten Eigenschaften.
PropertyId Zeichenfolge Geben Sie für jede Eigenschaft in der MultiValueExtendedProperties-Sammlung dies an, um die Eigenschaft zu identifizieren. Es muss einem der unterstützten Formate für mehrwertige erweiterte Eigenschaften folgen. Erforderlich.
Wert Sammlung (Zeichenfolge) Geben Sie für jede Eigenschaft in der MultiValueExtendedProperties-Sammlung die Werte für diese Eigenschafte an. Erforderlich.

Beispielanfrage

Das erste Beispiel erzeugt ein neues Ereignis und eine einwertige erweiterte Eigenschaft. Abgesehen von den Eigenschaften, die Sie normalerweise für ein neues Ereignis einfügen würden, enthält der Anforderungstext das Array SingleValueExtendedProperties, das eine einwertige erweiterte Eigenschaft enthält, und das Folgende für die Eigenschaft:

  • PropertyId gibt den Eigenschaftstyp als string, die GUID und die Fun-Eigenschaft an.
  • Wert gibt Food als den Wert der Fun-Eigenschaft an.
POST https://outlook.office.com/api/beta/me/events

Content-Type: application/json

{
  "Subject": "Celebrate Thanksgiving",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together!"
  },
  "Start": {
      "DateTime": "2015-11-26T18:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-26T23:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    }
  ],
  "SingleValueExtendedProperties": [
     {
           "PropertyId":"String {66f5a359-4659-4830-9070-00040ec6ac6e} Name Fun",
           "Value":"Food"
     }
  ]
}

Beispielantwort

Eine erfolgreiche Antwort wird mit dem Antwortcode HTTP 201 Created gekennzeichnet und enthält das neue Ereignis im Antworttext, ähnlich wie die Antwort, die zurückgegeben wird, wenn Sie nur ein Ereignis erstellen. Die Antwort enthält keine neu erstellten erweiterten Eigenschaften.

Möchten Sie die neu erstellte erweiterte Eigenschaft sehen, müssen Sie das um die erweiterte Eigenschaft erweiterte Element abrufen.

Beispielanfrage

Das zweite Beispiel erstellt eine mehrwertige erweiterte Eigenschaft in einem neuen Ereignis in ein- und derselben POST-Operation. Abgesehen von den Eigenschaften, die Sie normalerweise für ein neues Ereignis angeben würden, enthält der Anforderungstext das Array MultiValueExtendedProperties, das eine erweiterte Eigenschaft enthält.

Der Anforderungstext enthält folgendes für diese mehrwertige erweiterte Eigenschaft:

  • PropertyId definiert die Eigenschaft als ein Array von Zeichenfolgen mit der angegebenen GUID und dem Namen Recreation.
  • Value: Dieser Parameter definiert Recreation als ein Array von 3 Zeichenfolgewerten, ["Food", "Hiking", "Swimming"].
POST https://outlook.office.com/api/beta/me/events

Content-Type: application/json

{
  "Subject": "Family reunion",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together this Thanksgiving!"
  },
  "Start": {
      "DateTime": "2015-11-26T09:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-29T21:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    },
    {
      "EmailAddress": {
        "Address": "Lauren@contoso.com",
        "Name": "Lauren Solis"
      },
      "Type": "Required"
    }
  ],
  "MultiValueExtendedProperties": [
     {
           "PropertyId":"StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
           "Value": ["Food", "Hiking", "Swimming"]
     }
  ]
}

Beispielantwort

Eine erfolgreiche Antwort wird mit dem Antwortcode HTTP 201 Created gekennzeichnet und enthält das neue Ereignis im Antworttext, ähnlich wie die Antwort, die zurückgegeben wird, wenn Sie nur ein Ereignis erstellen. Die Antwort enthält keine neu erstellten erweiterten Eigenschaften.

Möchten Sie die neu erstellte erweiterte Eigenschaft sehen, müssen Sie das um die erweiterte Eigenschaft erweiterte Element abrufen.

Element mit erweiterter Eigenschaft abrufen

Rufen Sie eine Instanz einer unterstützten Ressource mit der erweiterten Eigenschaft ab, die durch einen Filter in der PropertyId angegeben wird.

Die Zeichenfolge {propertyId_value}, die Sie im Filter für PropertyId angeben, muss einem der unterstützten PropertyId-Formate folgen. Stellen Sie sicher, dass Sie für die Leerzeichen in der Filter-Zeichenfolge die URL-Codierung verwenden.

Element mit passenden einwertigen erweiterten Eigenschaften erweitern

GET https://outlook.office.com/api/beta/me/messages('{message_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/events('{event_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/tasks('{task_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/mailfolders('{mailFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/calendars('{calendar_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contactfolders('{contactFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/taskfolders('{taskfolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

Element mit passenden mehrwertigen erweiterten Eigenschaften erweitern

GET https://outlook.office.com/api/beta/me/messages('{message_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/events('{event_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/tasks('{task_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/mailfolders('{mailFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/calendars('{calendar_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contactfolders('{contactFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/taskfolders('{taskfolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

Minimal benötigter Bereich

Einer der folgenden Lese- / Schreibbereiche für die Zielressource:

Beispielanfrage

Das erste Beispiel ruft die Nachricht ab und erweitert sie um eine einwertige erweiterte Eigenschaft. Der Filter gibt die erweiterte Eigenschaft zurück, deren PropertyId der Zeichenfolge String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color entspricht (wobei die URL-Codierung hier zur besseren Lesbarkeit entfernt wurde).

GET https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')?$expand=SingleValueExtendedProperties($filter=PropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color')

Beispielantwort

Eine erfolgreiche Antwort wird mit einem HTTP 200 OK Antwortcode angegeben.

Der Antworttext enthält alle Eigenschaften der angegebenen Nachricht und die vom Filter zurückgegebene erweiterte Eigenschaft.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGE1M2_bs88AACHsLqWAAA=')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H\"",
    "Id": "AAMkAGE1M2_bs88AACHsLqWAAA=",
    "CreatedDateTime": "2015-11-11T02:41:24Z",
    "LastModifiedDateTime": "2015-12-09T04:07:57Z",
    "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H",
    "Categories": [
    ],
    "ReceivedDateTime": "2015-11-11T02:41:24Z",
    "SentDateTime": "2015-11-11T02:41:24Z",
    "HasAttachments": false,
    "InternetMessageId": "<SN2SR0101MB002977E7C30F9CA9AA55961484130@SN2SR0101MB0029.contoso.com>",
    "Subject": "RE: Talk about emergency prep",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=iso-8859-1\">\r\n<style type=\"text/css\" style=\"\">\r\n<!--\r\np\r\n\t{margin-top:0;\r\n\tmargin-bottom:0}\r\n-->\r\n</style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<hr tabindex=\"-1\" style=\"display:inline-block; width:98%\">\r\n<div id=\"divRplyFwdMsg\" dir=\"ltr\"><font face=\"Calibri, sans-serif\" color=\"#000000\" style=\"font-size:11pt\"><b>From:</b> Christine Irwin<br>\r\n<b>Sent:</b> Sunday, November 8, 2015 12:28:31 AM<br>\r\n<b>To:</b> Terrie Barrera<br>\r\n<b>Subject:</b> Talk about emergency prep<br>\r\n<b>When:</b> Sunday, November 8, 2015 7:00 PM-8:00 PM.<br>\r\n<b>Where:</b> The Commons</font>\r\n<div>&nbsp;</div>\r\n</div>\r\n<div>\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt; color:#000000; background-color:#FFFFFF; font-family:Calibri,Arial,Helvetica,sans-serif\">\r\n<p>Please see the attached before you come to the meeting.<br>\r\n</p>\r\n</div>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "________________________________",
    "Importance": "Normal",
    "ParentFolderId": "AQMkAGE1M2jgxCloXP1JupQN7j5uzzwAAAIBDwAAAA==",
    "Sender": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "From": null,
    "ToRecipients": [
        {
            "EmailAddress": {
                "Name": "Christine Irwin",
                "Address": "christine@contoso.com"
            }
        }
    ],
    "CcRecipients": [
    ],
    "BccRecipients": [
    ],
    "ReplyTo": [
    ],
    "ConversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVlLTY0YjcxZWUzNTE1MAAQAHWT1sRiMChEmlQCIZUadoU=",
    "IsDeliveryReceiptRequested": false,
    "IsReadReceiptRequested": false,
    "IsRead": true,
    "IsDraft": true,
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACHsLqWAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "MentionedMe": null,
    "HashtagDetailsPreview": null,
    "LikesPreview": null,
    "Mentioned": [
    ],
    "InferenceClassification": "Focused",
    "UnsubscribeData": [
    ],
    "UnsubscribeEnabled": false,
    "SingleValueExtendedProperties@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkAGE1M2_bs88AACHsLqWAAA%3D')/SingleValueExtendedProperties",
    "SingleValueExtendedProperties": [
        {
            "PropertyId": "String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
            "Value": "Green"
        }
    ]
}

Beispielanfrage

Das zweite Beispiel ruft das Ereignis ab und erweitert es um eine mehrwertige erweiterte Eigenschaft. Der Filter gibt die erweiterte Eigenschaft zurück, deren PropertyId der Zeichenfolge StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation entspricht (wobei die URL-Codierung hier zur besseren Lesbarkeit entfernt wurde).

GET https://outlook.office.com/api/beta/me/events('AAMkAGE1M2_bs88AACbuFiiAAA=')?$expand=MultiValueExtendedProperties($filter=PropertyId%20eq%20'StringArray%20{66f5a359-4659-4830-9070-00050ec6ac6e}%20Name%20Recreation')

Beispielantwort

Eine erfolgreiche Antwort wird mit einem HTTP 200 OK Antwortcode angegeben.

Der Antworttext enthält alle Eigenschaften des angegebenen Ereignisses und erweiterte Eigenschaften, die von dem Filter zurückgegeben wurden.

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE1M2_bs88AACbuFiiAAA=')",
    "@odata.etag": "W/\"mODEKWhc/Um6lA3uPm7PPAAAm8k15A==\"",
    "Id": "AAMkAGE1M2_bs88AACbuFiiAAA=",
    "CreatedDateTime": "2015-12-09T05:18:05.9477979Z",
    "LastModifiedDateTime": "2015-12-09T05:18:06.197802Z",
    "ChangeKey": "mODEKWhc/Um6lA3uPm7PPAAAm8k15A==",
    "Categories": [
    ],
    "OriginalStartTimeZone": "Pacific Standard Time",
    "OriginalEndTimeZone": "Pacific Standard Time",
    "ResponseStatus": {
        "Response": "Organizer",
        "Time": "0001-01-01T00:00:00Z"
    },
    "iCalUId": "04000000828A332796D9",
    "ReminderMinutesBeforeStart": 15,
    "IsReminderOn": true,
    "HasAttachments": false,
    "Subject": "Family reunion",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nLet's get together this Thanksgiving!\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "Let's get together this Thanksgiving!",
    "Importance": "Normal",
    "Sensitivity": "Normal",
    "Start": {
        "DateTime": "2015-11-26T17:00:00.0000000",
        "TimeZone": "UTC"
    },
    "End": {
        "DateTime": "2015-11-30T05:00:00.0000000",
        "TimeZone": "UTC"
    },
    "Location": {
        "DisplayName": ""
    },
    "IsAllDay": false,
    "IsCancelled": false,
    "IsOrganizer": true,
    "Recurrence": null,
    "ResponseRequested": true,
    "SeriesMasterId": null,
    "ShowAs": "Busy",
    "Type": "SingleInstance",
    "Attendees": [
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Terrie Barrera",
                "Address": "Terrie@contoso.com"
            }
        },
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Lauren Solis",
                "Address": "Lauren@contoso.com"
            }
        }
    ],
    "Organizer": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACbuFiiAAA%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
    "MultiValueExtendedProperties@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events('AAMkAGE1M2_bs88AACbuFiiAAA%3D')/MultiValueExtendedProperties",
    "MultiValueExtendedProperties": [
        {
            "PropertyId": "StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
            "Value": [
                "Food",
                "Hiking",
                "Swimming"
            ]
        }
    ]
}

Element durch Filtern nach erweiterter Eigenschaft abrufen

Rufen Sie Instanzen einer unterstützten Ressource ab, bei denen die erweiterte Eigenschaft nach PropertyId und Wert gefiltert werden. Der Filter wird auf alle Instanzen der Ressource angewendet, die im Postfach eines angemeldeten Benutzers existieren. Diese Filterung unterstützt nur einwertige, nicht aber mehrwertige erweiterte Eigenschaften.

Die Zeichenfolge {propertyId_value}, die Sie im Filter für PropertyId angeben, muss einem der unterstützten PropertyId-Formate folgen.

Wenn {property_value} keine Zeichenfolge ist, stellen Sie sicher, dass Sie explizit ep/value auf den entsprechenden Edm-Datentyp setzen, wenn Sie ihn mit {property_value} vergleichen. Beispiele für solche Umwandlungen finden Sie weiter unten unter Beispielanforderungen für Eigenschaften ohne Zeichenfolgen.

Stellen Sie sicher, dass Sie für die folgenden Zeichen in der Filterzeichenfolge die URL-Codierung verwenden: Doppelpunkte, Schrägstrich und Leerzeichen.

GET https://outlook.office.com/api/beta/me/messages?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/events?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/contacts?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/tasks?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/mailfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/calendars?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/contactfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/taskfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

Minimal benötigter Bereich

Einer der folgenden Lese- / Schreibbereiche für die Zielressource:

Beispielanfrage

Das erste Beispiel ruft Nachrichten ab, die die im Filter spezifizierte einwertige erweiterte Eigenschaft vom Typ Zeichenfolge haben. Der Filter sucht nach der erweiterten Eigenschaft, die folgende Merkmale hat:

  • Die PropertyId entspricht der Zeichenfolge String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color (URL-Codierung hier zur besseren Lesbarkeit entfernt).
  • Der Wert ist die Zeichenfolge Green.
GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties%2FAny(ep%3A%20ep%2FPropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color'%20and%20ep%2FValue%20eq%20'Green')

Die nächsten beiden Beispiele zeigen, wie man Nachrichten mit nicht-stringartigen, einwertigen erweiterten Eigenschaften erhält. Zur besseren Lesbarkeit ist die erforderliche URL-Codierung dort nicht enthalten. Das folgende Beispiel zeigt einen Filter, der nach der erweiterte Eigenschaft mit den folgenden Merkmalen sucht:

  • Seine PropertyId entspricht der Zeichenfolge CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid.
  • Der Wert ist die GUID b9cf8971-7d55-4b73-9ffa-a584611b600b. Wenn Sie den Eigenschaftswert mit einer GUID vergleichen möchten, ändern Sie ep/Value in Edm.Guid.
GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid' and cast(ep/Value, Edm.Guid) eq (b9cf8971-7d55-4b73-9ffa-a584611b600b))

Das dritte und letzte Beispiel zeigt einen Filter, der nach der erweiterten Eigenschaft mit den folgenden Merkmalen sucht:

  • Seine PropertyId entspricht der Zeichenfolge Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete.
  • Der Wert ist gleich der ganzen Zahl 12. Um den Eigenschaftswert mit einer ganzen Zahl zu vergleichen, ändern Sie ep/Value in Edm.Int32.
GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete' and cast(ep/Value, Edm.Int32) eq 12)

Beispielantwort

Eine erfolgreiche Antwort ist durch den Antwortcode HTTP 200 OK gekennzeichnet. Der Antworttext enthält alle Eigenschaften der Nachrichten, die die dem Filter entsprechende erweiterte Eigenschaft haben. Der Antworttext ähnelt der Antwort beim Abrufen einer Nachrichtensammlung. Die Antwort enthält nicht die dem Filter entsprechende erweiterte Eigenschaft.

Nächste Schritte

Egal, ob Sie bereit sind, eine App zu erstellen oder einfach nur mehr darüber erfahren möchten, wir haben alles im Griff.

Oder erfahren Sie mehr über die Verwendung der Office 365-Plattform: