Feedback Bearbeiten

Offene Erweiterung erstellen

  • Artikel
  • 16 Minuten Lesedauer

Namespace: microsoft.graph

Mit dieser API können Sie offene Erweiterungen (Objekte des Typs openTypeExtension) erstellen und einer neuen oder bereits vorhandenen Ressourceninstanz benutzerdefinierte Eigenschaften hinzufügen. Sie können im Rahmen ein und desselben Vorgangs in einer Ressourceninstanz eine offene Erweiterung erstellen und benutzerdefinierte Daten speichern. Ausgenommen sind bestimmte Ressourcen. Weitere Informationen finden Sie unter Bekannte Einschränkungen für offene Erweiterungen.

In der Tabelle im Abschnitt Berechtigungen sind die Ressourcen aufgelistet, die offene Erweiterungen unterstützen.

Hinweis: Wenn Sie offene Erweiterungen auf Outlook-Ressourcen erstellen, ziehen Sie Outlook-spezifische Überlegungen unter openTypeExtension-Ressourcentyp zurate.

Berechtigungen

Abhängig von der Ressource, in der Sie die Erweiterung erstellen, und dem angeforderten Berechtigungstyp (delegiert oder Anwendung) ist die in der folgenden Tabelle angegebene Berechtigung die niedrigste Berechtigung, die zum Aufrufen dieser API erforderlich ist. Um mehr zu erfahren und vor der Wahl weiterer privilegierterer Berechtigungen mit Umsicht vorzugehen, suchen Sie unter Berechtigungen nach den folgenden Berechtigungen.

Unterstützte Ressource Delegiert (Geschäfts-, Schul- oder Unikonto) Delegiert (persönliches Microsoft-Konto) Application
device Directory.AccessAsUser.All Nicht unterstützt Device.ReadWrite.All
event Calendars.ReadWrite Calendars.ReadWrite Calendars.ReadWrite
group Group.ReadWrite.All Nicht unterstützt Group.ReadWrite.All
group event Group.ReadWrite.All Nicht unterstützt Nicht unterstützt
group post Group.ReadWrite.All Nicht unterstützt Group.ReadWrite.All
message Mail.ReadWrite Mail.ReadWrite Mail.ReadWrite
organization Organization.ReadWrite.All Nicht unterstützt Organization.ReadWrite.All
personal contact Contacts.ReadWrite Contacts.ReadWrite Contacts.ReadWrite
todoTask Tasks.ReadWrite Tasks.ReadWrite Tasks.ReadWrite.All
todoTaskList Tasks.ReadWrite Tasks.ReadWrite Tasks.ReadWrite.All
user User.ReadWrite User.ReadWrite User.ReadWrite.All

HTTP-Anforderung

Erstellen einer Erweiterung in einer neuen Ressourceninstanz

Verwenden Sie die gleiche REST-Anforderung, die Sie zum Erstellen der Instanz verwenden.

POST /users/{id|userPrincipalName}/events
POST /users/{id|userPrincipalName}/messages
POST /groups/{id}/events
POST /groups/{id}/threads/{id}/posts/{id}/reply
POST /users/{id|userPrincipalName}/contacts
POST /users/{id|userPrincipalName}/todo/lists/{id}/tasks
POST /users/{id|userPrincipalName}/todo/lists

Hinweis: Diese Syntax zeigt einige häufig verwendete Möglichkeiten zum Erstellen der unterstützten Ressourceninstanzen. Alle anderen POST-Syntaxen, mit denen Sie diese Ressourceninstanzen erstellen können, unterstützen das Erstellen offener Erweiterungen darin in einer ähnlichen Weise.

Im Abschnitt Anforderungstext ist beschrieben, wie Sie die Eigenschaften der neuen Ressourceninstanz und die Erweiterung in den Anforderungstext einschließen können.

Erstellen einer Erweiterung in einer vorhandenen Ressourceninstanz

Geben Sie die Ressourceninstanz in der Anforderung an, und wenden Sie den Befehl POST auf die Navigationseigenschaft extensions an.

POST /devices/{id}/extensions
POST /users/{id|userPrincipalName}/events/{id}/extensions
POST /groups/{id}/extensions
POST /groups/{id}/events/{id}/extensions
POST /groups/{id}/threads/{id}/posts/{id}/extensions
POST /users/{id|userPrincipalName}/messages/{id}/extensions
POST /organization/{id}/extensions
POST /users/{id|userPrincipalName}/contacts/{id}/extensions
POST /users/{id|userPrincipalName}/extensions
POST /users/{id|userPrincipalName}/todo/lists/{id}/tasks/{id}/extensions
POST /users/{id|userPrincipalName}/todo/lists/{id}/extensions

Hinweis: Diese Syntax zeigt einige häufig verwendete Möglichkeiten zum Identifizieren einer Ressourceninstanz, um eine Erweiterung darin zu erstellen. Alle anderen Syntaxen, mit denen Sie diese Ressourceninstanzen identifizieren können, unterstützen das Erstellen offener Erweiterungen darin in einer ähnlichen Weise.

Im Abschnitt Anforderungstext wird beschrieben, wie Sie die Erweiterung in den Anforderungstext einschließen können.

Pfadparameter

Parameter Typ Beschreibung
id string Ein eindeutiger Bezeichner für ein Objekt in der entsprechenden Sammlung. Erforderlich.

Anforderungsheader

Name Wert
Authorization Bearer {token}. Erforderlich.
Content-Type application/json

Anforderungstext

Geben Sie den JSON-Text einer openTypeExtension an, mit den folgenden erforderlichen Name/Wert-Paaren und allen zusätzlichen benutzerdefinierten Daten. Die Daten in der JSON-Nutzlast können Grundtypen oder Arrays von Grundtypen sein.

Name Wert
@odata.type microsoft.graph.openTypeExtension
extensionName %unique_string%

Beim Erstellen einer Erweiterung in einer neuen Ressourceninstanz müssen Sie zusätzlich zu dem neuen openTypeExtension-Objekt eine JSON-Darstellung der zur Erstellung einer solchen Ressourceninstanz erforderlichen Eigenschaften angeben.

Antwort

Antwortcode

Je nach Vorgang lautet der Antwortcode 201 Created oder 202 Accepted.

Wenn Sie eine Erweiterung mit dem gleichen Vorgang erstellen, mit dem Sie eine Ressourceninstanz erstellt haben, gibt der Vorgang den gleichen Antwortcode zurück, der zurückgegeben wird, wenn Sie den Vorgang zum Erstellen der Ressourceninstanz ohne die Erweiterung verwenden. Weitere Informationen zum Erstellen der Instanz finden Sie in den entsprechenden Themen, wie oben aufgeführt.

Antworttext

Szenario Ressource Antworttext
Erstellen einer Erweiterung bei gleichzeitiger expliziter Erstellung einer neuen Ressourceninstanz contact, event, message Enthält die neue Instanz, erweitert um das openTypeExtension-Objekt.
Erstellen einer Erweiterung bei gleichzeitiger impliziter Erstellung einer Ressourceninstanz post Die Antwort enthält nur einen Antwortcode, keinen Antworttext.
Erstellen einer Erweiterung in einer vorhandenen Ressourceninstanz Alle unterstützten Ressourcen Enthält das openTypeExtension-Objekt.

Beispiel

Anforderung 1

Im ersten Beispiel werden mit ein und demselben Aufruf eine Nachricht und eine Erweiterung erstellt. Der Anforderungstext enthält Folgendes:

  • Die für eine neue Nachricht typischen Eigenschaften subject, body und toRecipients

  • Daneben die folgenden Parameter der Erweiterung:

    • Den Typ microsoft.graph.openTypeExtension
    • Den Erweiterungsnamen „Com.Contoso.Referral“
    • Zusätzliche Daten, die als drei benutzerdefinierte Eigenschaften in der JSON-Nutzlast gespeichert werden sollen: companyName, expirationDate und dealValue
POST https://graph.microsoft.com/v1.0/me/messages

{
  "subject": "Annual review",
  "body": {
    "contentType": "HTML",
    "content": "You should be proud!"
  },
  "toRecipients": [
    {
      "emailAddress": {
        "address": "rufus@contoso.com"
      }
    }
  ],
  "extensions": [
    {
      "@odata.type": "microsoft.graph.openTypeExtension",
      "extensionName": "Com.Contoso.Referral",
      "companyName": "Wingtip Toys",
      "expirationDate": "2015-12-30T11:00:00.000Z",
      "dealValue": 10000
    }
  ]
}

Antwort 1

Unten sehen Sie die Antwort für Beispiel 1. Der Antworttext enthält die Eigenschaften der neuen Nachricht sowie die folgenden Parameter der neuen Erweiterung:

  • Die Eigenschaft id mit dem vollqualifizierten Namen microsoft.graph.openTypeExtension.Com.Contoso.Referral
  • Die in der Anforderung angegebene Standardeigenschaft extensionName
  • Die in der Anforderung angegebenen benutzerdefinierten Daten, gespeichert als 3 benutzerdefinierte Eigenschaften

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt sein.

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages/$entity",
  "@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/messages
('AAMkAGEbs88AAB84uLuAAA=')",
  "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj\"",
  "id": "AAMkAGEbs88AAB84uLuAAA=",
  "createdDateTime": "2015-10-30T03:03:43Z",
  "lastModifiedDateTime": "2015-10-30T03:03:43Z",
  "changeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj",
  "categories": [ ],
  "receivedDateTime": "2015-10-30T03:03:43Z",
  "sentDateTime": "2015-10-30T03:03:43Z",
  "hasAttachments": false,
  "subject": "Annual review",
  "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\nYou should be proud!\r\n</body>\r
\n</html>\r\n"
  },
  "bodyPreview": "You should be proud!",
  "importance": "Normal",
  "parentFolderId": "AQMkAGEwAAAIBDwAAAA==",
  "sender": null,
  "from": null,
  "toRecipients": [
    {
      "emailAddress": {
        "address": "rufus@contoso.com",
        "name": "John Doe"
      }
    }
  ],
  "ccRecipients": [ ],
  "bccRecipients": [ ],
  "replyTo": [ ],
  "conversationId": "AAQkAGEFGugh3SVdMzzc=",
  "isDeliveryReceiptRequested": false,
  "isReadReceiptRequested": false,
  "isRead": true,
  "isDraft": true,
  "webLink": "https://outlook.office.com/owa/?
ItemID=AAMkAGEbs88AAB84uLuAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
  "inferenceClassification": "Focused",
  "extensions": [
    {
      "@odata.type": "#microsoft.graph.openTypeExtension",
      "@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/messages
('AAMkAGEbs88AAB84uLuAAA=')/extensions('microsoft.graph.openTypeExtension.Com.Contoso.Referral')",
      "id": "microsoft.graph.openTypeExtension.Com.Contoso.Referral",
      "extensionName": "Com.Contoso.Referral",
      "companyName": "Wingtip Toys",
      "expirationDate": "2015-12-30T11:00:00.000Z",
      "dealValue": 10000
    }
  ]
}

Anforderung 2

Das zweite Beispiel erstellt eine Erweiterung in der angegebenen Nachricht. Der Anforderungstext enthält die folgenden Parameter für die Erweiterung:

  • Den Typ microsoft.graph.openTypeExtension
  • Den Erweiterungsnamen „Com.Contoso.Referral“
  • Zusätzliche Daten, die als 3 benutzerdefinierte Eigenschaften in der JSON-Nutzlast gespeichert werden sollen: companyName, dealValue und expirationDate
POST https://graph.microsoft.com/v1.0/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions

{
  "@odata.type" : "microsoft.graph.openTypeExtension",
  "extensionName" : "Com.Contoso.Referral",
  "companyName" : "Wingtip Toys",
  "dealValue" : 500050,
  "expirationDate" : "2015-12-03T10:00:00.000Z"
}

Antwort 2

Die Antwort für das zweite Beispiel sehen Sie unten. Der Antworttext enthält die folgenden Parameter für die neue Erweiterung:

  • Die Standardeigenschaft extensionName
  • Die Eigenschaft id mit dem vollqualifizierten Namen microsoft.graph.openTypeExtension.Com.Contoso.Referral
  • Die benutzerdefinierten Daten, die gespeichert werden sollen
HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('microsoft.graph.openTypeExtension.Com.Contoso.Referral')",
    "extensionName": "Com.Contoso.Referral",
    "id": "microsoft.graph.openTypeExtension.Com.Contoso.Referral",
    "companyName": "Wingtip Toys",
    "dealValue": 500050,
    "expirationDate": "2015-12-03T10:00:00.000Z"
}

Anforderung 3

Das dritte Beispiel erstellt eine Erweiterung in dem angegebenen Gruppenereignis. Der Anforderungstext enthält die folgenden Parameter für die Erweiterung:

  • Den Typ microsoft.graph.openTypeExtension
  • Den Erweiterungsnamen „Com.Contoso.Deal“
  • Zusätzliche Daten, die als 3 benutzerdefinierte Eigenschaften in der JSON-Nutzlast gespeichert werden sollen: companyName, dealValue und expirationDate
POST https://graph.microsoft.com/v1.0/groups/f5480dfd-7d77-4d0b-ba2e-3391953cc74a/events/AAMkADVl17IsAAA=/extensions

{
  "@odata.type" : "microsoft.graph.openTypeExtension",
  "extensionName" : "Com.Contoso.Deal",
  "companyName" : "Alpine Skis",
  "dealValue" : 1010100,
  "expirationDate" : "2015-07-03T13:04:00.000Z"
}

Antwort 3

Unten sehen Sie die Antwort auf die Anforderung im dritten Beispiel:

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups('f5480dfd-7d77-4d0b-ba2e-3391953cc74a')/events('AAMkADVl7IsAAA%3D')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "id": "microsoft.graph.openTypeExtension.Com.Contoso.Deal",
    "extensionName": "Com.Contoso.Deal",
    "companyName": "Alpine Skis",
    "dealValue": 1010100,
    "expirationDate": "2015-07-03T13:04:00Z"
}

Anforderung 4

Das vierte Beispiel erstellt eine Erweiterung in einem neuen Gruppenbeitrag, mit demselben reply-Aktionsaufruf, wie er für bereits vorhandene Gruppenbeiträge verwendet wird. Die Aktion reply erstellt einen neuen Beitrag und eine neue, in diesen Beitrag eingebettete Erweiterung. Der Antworttext enthält eine Eigenschaft post mit dem Text des neuen Beitrags sowie die folgenden Daten der neuen Erweiterung:

  • Den Typ microsoft.graph.openTypeExtension
  • Den Erweiterungsnamen „Com.Contoso.HR“
  • Zusätzliche Daten, die als 3 benutzerdefinierte Eigenschaften in der JSON-Nutzlast gespeichert werden sollen: companyName, expirationDate und das Zeichenfolgen-Array topPicks
POST https://graph.microsoft.com/v1.0/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/threads/AAQkADJizZJpEWwqDHsEpV_KA==/posts/AAMkADJiUg96QZUkA-ICwMubAAC1heiSAAA=/reply

{
  "post": {
    "body": {
      "contentType": "html",
      "content": "<html><body><div><div><div><div>When and where? </div></div></div></div></body></html>"
    },
  "extensions": [
    {
      "@odata.type": "microsoft.graph.openTypeExtension",
      "extensionName": "Com.Contoso.HR",
      "companyName": "Contoso",
      "expirationDate": "2015-07-03T13:04:00.000Z",
      "topPicks": [
        "Employees only",
        "Add spouse or guest",
        "Add family"
      ]
    }
  ]
  }
}

Antwort 4

Die Antwort für das vierte Beispiel sehen Sie unten. Wird eine Erweiterung in einem neuen Gruppenbeitrag erstellt, wird nur der Antwortcode „HTTP 202“ zurückgegeben.

HTTP/1.1 202 Accepted
Content-type: text/plain
Content-Length: 0

Anforderung 5

Das fünfte Beispiel erstellt in ein und derselben POST-Operation eine Erweiterung in einem neuen Gruppenbeitrag und eine Unterhaltung. Die POST-Operation erstellt eine neue Unterhaltung, einen neuen Thread, einen neuen Beitrag und eine neue, in diesen Beitrag eingebettete Erweiterung. Der Anforderungstext enthält die Eigenschaften Topic und Threads sowie ein untergeordnetes Objekt des Typs post der neuen Unterhaltung. Das post-Objekt wiederum enthält den Text des neuen Beitrags sowie die folgenden Daten der Erweiterung:

  • Den Typ microsoft.graph.openTypeExtension
  • Den Erweiterungsnamen „Com.Contoso.HR“
  • Zusätzliche Daten, die als 3 benutzerdefinierte Eigenschaften in der JSON-Nutzlast gespeichert werden sollen: companyName, expirationDate und das Zeichenfolgen-Array topPicks
POST https://graph.microsoft.com/v1.0/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/conversations

{
  "Topic": "Does anyone have a second?",
  "Threads": [
    {
      "Posts": [
        {
          "Body": {
            "ContentType": "HTML",
            "Content": "This is urgent!"
          },
          "Extensions": [
            {
              "@odata.type": "microsoft.graph.openTypeExtension",
              "extensionName": "Com.Contoso.Benefits",
              "companyName": "Contoso",
              "expirationDate": "2016-08-03T11:00:00.000Z",
              "topPicks": [
                "Employees only",
                "Add spouse or guest",
                "Add family"
              ]
            }
          ]
        }
      ]
    }
  ]
}

Antwort 5

Unten sehen Sie die Antwort für das fünfte Beispiel mit der neuen Unterhaltung und einer Thread-ID. Dieser neue Thread enthält einen automatisch erstellten Beitrag, der wiederum die neue Erweiterung enthält.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt sein.

Zum Abrufen der neuen Erweiterung rufen Sie zunächst alle Beiträge in diesem Thread ab. Anfangs sollte es nur einen Beitrag geben. Wenden Sie dann die Beitrags-ID und den Erweiterungsnamen Com.Contoso.Benefits an, um die Erweiterung abzurufen.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/conversations/$entity",
    "id": "AAQkADJToRlbJ5Mg7TFM7H-j3Y=",
    "threads": [
        {
            "id": "AAQkADJDtMUzsf_PdhAAswJOhGVsnkyDtMUzsf_Pdg=="
        }
    ]
}