Outlook erweiterte Eigenschaften-REST-API-Verweis (version 2.0)
Gilt für: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com
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 des Verweises verwendet der Rest dieses Artikels Outlook.com, um diese Microsoft-Kontodomänen einzuschließen.
Kein Interesse an v2.0 der API? Wechseln Sie im Inhaltsverzeichnis auf der linken Seite zum Abschnitt Office 365 REST-API-Verweis 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 Zeichenfolgennamen 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 die Zeichenfolgen, ganze Zahlen und Arrays dieser Typen dargestellt.
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 PropertyId 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
- Erstellen einer erweiterten Eigenschaft in einem vorhandenen Element
- Erstellen einer erweiterten Eigenschaft in einem neuen Element
- Element mit erweiterter Eigenschaft abrufen
- Filter für eine einwertige erweiterte Eigenschaft
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/v2.0/me/messages('{message_id}')
PATCH https://outlook.office.com/api/v2.0/me/events('{event_id}')
PATCH https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')
PATCH https://outlook.office.com/api/v2.0/me/tasks('{task_id}')
PATCH https://outlook.office.com/api/v2.0/me/mailfolders('{mailFolder_id}')
PATCH https://outlook.office.com/api/v2.0/me/calendars('{calendar_id}')
PATCH https://outlook.office.com/api/v2.0/me/contactfolders('{contactFolder_id}')
PATCH https://outlook.office.com/api/v2.0/me/taskfolders('{taskFolder_id}')
Minimal benötigter Bereich
Einer der folgenden Lese- / Schreibbereiche für die Zielressource:
- https://outlook.office.com/mail.readwrite
- https://outlook.office.com/calendars.readwrite
- https://outlook.office.com/contacts.readwrite
- https://outlook.office.com/tasks.readwrite
- wl.imap
- wl.calendars_aktualisieren
- wl.events_erstellen
- wl.contacts_create
Parameter | Typ | Beschreibung |
---|---|---|
Text-Parameter | ||
SingleValueExtendedProperties | Sammlung (SingleValueLegacyExtendedProperty) | Ein Array aus erweiterten mehrwertigen 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 dieColor
-Eigenschaft an. - Wert gibt
Green
als den Wert derColor
-Eigenschaft an.
PATCH https://outlook.office.com/api/v2.0/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
. - Wert definiert
Palette
als ein Array von 3 Zeichenfolgewerten,["Green", "Aqua", "Blue"]
.
PATCH https://outlook.office.com/api/v2.0/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.
Um die neu erstellte erweiterte Eigenschaft zu sehen müssen Sie die Nachricht mit der erweiterten Eigenschaft abrufen.
Erstellen einer erweiterten Eigenschaft in einem neuen Element
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/v2.0/me/messages
POST https://outlook.office.com/api/v2.0/me/events
POST https://outlook.office.com/api/v2.0/me/contacts
POST https://outlook.office.com/api/v2.0/me/tasks
POST https://outlook.office.com/api/v2.0/me/mailfolders
POST https://outlook.office.com/api/v2.0/me/calendars
POST https://outlook.office.com/api/v2.0/me/contactfolders
POST https://outlook.office.com/api/v2.0/me/taskfolders
Minimal benötigter Bereich
Einer der folgenden Lese- / Schreibbereiche für die Zielressource:
- https://outlook.office.com/mail.readwrite
- https://outlook.office.com/calendars.readwrite
- https://outlook.office.com/contacts.readwrite
- https://outlook.office.com/tasks.readwrite
- wl.imap
- wl.calendars_aktualisieren
- wl.events_erstellen
- wl.contacts_create
Parameter | Typ | Beschreibung |
---|---|---|
Text-Parameter | ||
SingleValueExtendedProperties | Sammlung (SingleValueLegacyExtendedProperty) | Ein Array aus erweiterten mehrwertigen 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
Im erste Beispiel erstellt ein neues Ereignis und eine erweiterte Einzelwert-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 dieFun
-Eigenschaft an. - Wert gibt
Food
als den Wert derFun
-Eigenschaft an.
POST https://outlook.office.com/api/v2.0/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.
Um die neu erstellte erweiterte Eigenschaft zu sehen, müssen Sie die Nachricht mit der erweiterten Eigenschaft abrufen.
Beispielanfrage
Das zweite Beispiel erstellt eine mehrwertige erweiterte Eigenschaft in einem neuen Ereignis in ein- und der selben 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
. - Wert definiert
Recreation
als ein Array von 3 Zeichenfolgewerten,["Food", "Hiking", "Swimming"]
.
POST https://outlook.office.com/api/v2.0/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.
Um die neu erstellte erweiterte Eigenschaft zu sehen, müssen Sie die Nachricht mit der erweiterten Eigenschaft 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/v2.0/me/messages('{message_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
GET https://outlook.office.com/api/v2.0/me/events('{event_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
GET https://outlook.office.com/api/v2.0/me/tasks('{task_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
GET https://outlook.office.com/api/v2.0/me/mailfolders('{mailFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
GET https://outlook.office.com/api/v2.0/me/calendars('{calendar_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
GET https://outlook.office.com/api/v2.0/me/contactfolders('{contactFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
GET https://outlook.office.com/api/v2.0/me/taskfolders('{taskfolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
Element mit passenden mehrwertigen erweiterten Eigenschaften erweitern
GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
GET https://outlook.office.com/api/v2.0/me/events('{event_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
GET https://outlook.office.com/api/v2.0/me/tasks('{task_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
GET https://outlook.office.com/api/v2.0/me/mailfolders('{mailFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
GET https://outlook.office.com/api/v2.0/me/calendars('{calendar_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
GET https://outlook.office.com/api/v2.0/me/contactfolders('{contactFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
GET https://outlook.office.com/api/v2.0/me/taskfolders('{taskfolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')
Minimal benötigter Bereich
Einer der folgenden Leseberiche entspricht für die Zielressource:
- https://outlook.office.com/mail.read
- https://outlook.office.com/calendars.read
- https://outlook.office.com/contacts.read
- https://outlook.office.com/tasks.read
- wl.imap
- wl.calendars
- wl.contacts_calendars
- wl.basic
Beispielanfrage
Im ersten Beispiel wird die angegebene Nachricht abgerufen und erweitert, indem eine erweiterte Einzelwerteigenschaft einbezogen wird. 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/v2.0/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/v2.0/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/v2.0/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> </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/v2.0/$metadata#Me/Messages('AAMkAGE1M2_bs88AACHsLqWAAA%3D')/SingleValueExtendedProperties",
"SingleValueExtendedProperties": [
{
"PropertyId": "String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
"Value": "Green"
}
]
}
Beispielanfrage
Im zweiten Beispiel wird das angegebene Ereignis abgerufen und erweitert, indem eine erweiterte Eigenschaft mit mehreren Werten einbezogen wird. 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/v2.0/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/v2.0/$metadata#Me/Events/$entity",
"@odata.id": "https://outlook.office.com/api/v2.0/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/v2.0/$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 Value gefiltert werden. Der Filter wird auf alle Instanzen der Ressource angewendet, die im Postfach eines angemeldeten Benutzers existieren. Diese Filterung unterstützt nur einwertige, aber nicht 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/v2.0/me/messages?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')
GET https://outlook.office.com/api/v2.0/me/events?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')
GET https://outlook.office.com/api/v2.0/me/contacts?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')
GET https://outlook.office.com/api/v2.0/me/tasks?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')
GET https://outlook.office.com/api/v2.0/me/mailfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')
GET https://outlook.office.com/api/v2.0/me/calendars?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')
GET https://outlook.office.com/api/v2.0/me/contactfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')
GET https://outlook.office.com/api/v2.0/me/taskfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')
Minimal benötigter Bereich
Einer der folgenden Leseberiche entspricht für die Zielressource:
- https://outlook.office.com/mail.read
- https://outlook.office.com/calendars.read
- https://outlook.office.com/contacts.read
- https://outlook.office.com/tasks.read
- wl.imap
- wl.calendars
- wl.contacts_calendars
- wl.basic
Beispielanfrage
Das erste Beispiel ruft Nachrichten ab, die die im Filter angegebene einwertige erweiterte Eigenschaft haben. Der Filter gibt die erweiterte Eigenschaft zurück, die folgende Merkmale hat:
- Die PropertyId entspricht der Zeichenfolge
String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color
(URL-Codierung hier zur besseren Lesbarkeit entfernt). - Sein Value ist
Green
.
GET https://outlook.office.com/api/v2.0/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 Sieep/Value
inEdm.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
inEdm.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.
- Beginnen Sie mit den E-Mail-, Kalender- und Kontakte-REST-APIs.
- Möchten Sie Beispiele sehen? Wir haben sie.
Oder erfahren Sie mehr über die Verwendung der Office 365-Plattform:
- Outlook-REST-API im Outlook-Dev-Center
- Überblick über die Entwicklung auf der Office 365-Plattform
- E-Mail-REST-API-Verweis
- Kalender-REST-API-Verweis
- Kontakte-REST-API-Verweis
- Aufgaben-REST-API
- Ressourcenverweis für die E-Mail, Kalender, Kontakte und REST-APIs
- Personen-API-Verweis
- Datenerweiterungen-API-Verweis
- Benachrichtigungen-REST-API-Verweis
- Benutzerfoto-REST-API-Verweis
- Batch Outlook REST Verweise