openTypeExtension aktualisieren

Namespace: microsoft.graph

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

Achtung

Vorhandene Apps, die dieses Feature mit baseTask oder baseTaskList verwenden, sollten aktualisiert werden, da der auf diesen Ressourcen basierende To-Do-API-Satz ab dem 31. Mai 2022 veraltet ist. Dieser API-Satz wird ab dem 31. August 2022 keine Daten mehr zurückgeben. Bitte verwenden Sie den API-Satz, der auf todoTask basiert.

Aktualisieren einer geöffneten Erweiterung (openTypeExtension-Objekt ) für einen unterstützten Ressourcentyp.

  • Wenn eine Eigenschaft im Anforderungsheader mit dem Name einer vorhandenen Eigenschaft in der Erweiterung übereinstimmt, werden die Daten in die Erweiterung aktualisiert.
  • Andernfalls werden diese Eigenschaft und ihre Daten der Erweiterung hinzugefügt.

Bei den Daten in einer Erweiterung kann es sich um primitive Typen oder um Arrays von primitiven Typen handeln. Der Vorgang verhält sich für Ressourcen, die Verzeichnisobjekte sind, anders als für andere Ressourcen.

Die Liste der Ressourcen, die offene Erweiterungen unterstützen, finden Sie in der Tabelle im Abschnitt "Berechtigungen ".

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Weltweiter Service US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet
✅ ✅ ✅ ❌

Berechtigungen

Abhängig von der Ressource, in der die Erweiterung erstellt wurde, und dem angeforderten Berechtigungstyp (delegiert oder Anwendung) ist die in der folgenden Tabelle angegebene Berechtigung die am wenigsten privilegierte, 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
driveItem Files.ReadWrite Files.ReadWrite Nicht unterstützt
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
Hinweis ShortNotes.ReadWrite ShortNotes.ReadWrite ShortNotes.ReadWrite.All
organization Organization.ReadWrite.All Nicht unterstützt Organization.ReadWrite.All
personal contact Contacts.ReadWrite Contacts.ReadWrite Contacts.ReadWrite
site Sites.ReadWrite.All Nicht unterstützt Nicht unterstützt
todoTask Tasks.ReadWrite Tasks.ReadWrite Nicht unterstützt
todoTasklist Tasks.ReadWrite Tasks.ReadWrite Nicht unterstützt
user User.ReadWrite Nicht unterstützt User.ReadWrite.All
baseTask (veraltet) Tasks.ReadWrite Tasks.ReadWrite Nicht unterstützt
baseTasklist (veraltet) Tasks.ReadWrite Tasks.ReadWrite Nicht unterstützt

HTTP-Anforderung

In der Anforderung geben Sie die Ressourceninstanz an, spezifizieren in der Navigationseigenschaft extensions dieser Instanz die Erweiterung und wenden anschließend den Befehl PATCH auf diese Erweiterungsinstanz an.

PATCH /administrativeUnits/{administrativeUnitId}/extensions/{extensionId}
PATCH /devices/{deviceId}/extensions/{extensionId}
PATCH /users/{userId|userPrincipalName}/events/{eventId}/extensions/{extensionId}
PATCH /groups/{groupId}/extensions/{extensionId}
PATCH /groups/{groupId}/events/{eventId}/extensions/{extensionId}
PATCH /groups/{groupId}/threads/{threadId}/posts/{postId}/extensions/{extensionId}
PATCH /users/{userId|userPrincipalName}/messages/{messageId}/extensions/{extensionId}
PATCH /users/{userId|userPrincipalName}/notes/{noteId}/extensions/{extensionId}
PATCH /organization/{organizationId}/extensions/{extensionId}
PATCH /users/{userId|userPrincipalName}/contacts/{contactId}/extensions/{extensionId}
PATCH /users/{userId|userPrincipalName}/extensions/{extensionId}
PATCH /users/{userId|userPrincipalName}/todo/lists/{listId}/tasks/{taskId}/extensions/{extensionId}
PATCH /users/{userId|userPrincipalName}/todo/lists/{listId}/extensions/{extensionId}
PATCH /users/{userId|userPrincipalName}/tasks/lists/{listId}/tasks/{taskId}/extensions/{extensionId}
PATCH /users/{userId|userPrincipalName}/tasks/lists/{listId}/extensions/{extensionId}
PATCH /drive/items/{itemId}/extensions/{extensionId}
PATCH /sites/{siteId}/extensions/{extensionId}

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

Im Abschnitt Anforderungstext wird beschrieben, wie Sie benutzerdefinierte Daten zur Änderung oder Ergänzung der Erweiterung in den Anforderungstext einschließen können.

Anforderungsheader

Name Wert
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung.
Content-Type application/json

Anforderungstext

Geben Sie im Anforderungstext nur die Werte für die zu aktualisierenden Eigenschaften an. Vorhandene Eigenschaften, die nicht im Anforderungstext enthalten sind, behalten ihre vorherigen Werte bei oder werden basierend auf Änderungen an anderen Eigenschaftswerten neu berechnet.

In der folgenden Tabelle sind die Eigenschaften angegeben, die aktualisiert werden können.

Stellen Sie den JSON-Text eines openTypeExtension-Objekts mit den folgenden erforderlichen Name-Wert-Paaren und allen benutzerdefinierten Daten bereit, die geändert oder zu dieser Erweiterung hinzugefügt werden sollen.

Eigenschaft Typ Beschreibung
@odata.type Zeichenfolge Muss #microsoft.graph.openTypeExtension sein. Erforderlich.
extensionName String Erforderlich, wenn keine ID angegeben wird. aktualisierbar.
id Zeichenfolge Erforderlich, wenn keine ID angegeben wird. Schreibgeschützt.

Für Ressourcen, bei denen es sich um Verzeichnisobjekte (Microsoft Entra ID) handelt:

  • Um eine Eigenschaft im geöffneten Erweiterungsobjekt zu aktualisieren, müssen Sie alle Eigenschaften im Anforderungstext angeben. Andernfalls löscht Microsoft Graph die nicht angegebenen Eigenschaften.
  • Um Daten aus einer Eigenschaft im geöffneten Erweiterungsobjekt zu löschen, aber die Eigenschaft beizubehalten, legen Sie ihren Wert auf nullfest.
  • Um eine Eigenschaft aus dem geöffneten Erweiterungsobjekt zu löschen, übergeben Sie sie nicht im Text der PATCH-Anforderung, und Microsoft Graph löscht sie.
  • Wenn Sie Daten aus allen Eigenschaften im geöffneten Erweiterungsobjekt löschen, aber das geöffnete Erweiterungsobjekt beibehalten möchten, aktualisieren Sie die Werte aller Eigenschaften auf null.

Für Microsoft 365-Ressourcen wie Nachrichten:

  • Sie können eine Teilmenge der Eigenschaften im Anforderungstext angeben, um sie zu aktualisieren. Die weggelassenen Eigenschaften und ihre Werte werden beibehalten.
  • null Werte sind nicht zulässig.

Antwort

Bei erfolgreicher Ausführung gibt diese Methode einen 204 No Content Antwortcode für Verzeichnisobjekte oder einen 200 OK Antwortcode und ein aktualisiertes openTypeExtension-Objekt für andere Ressourcen zurück.

Beispiel

Anforderung 1

Im ersten Beispiel wird gezeigt, wie eine Erweiterung in einer Nachricht aktualisiert wird. Die Erweiterung wird anfänglich durch die folgende JSON-Nutzlast dargestellt:

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

Sie können anhand des Namens auf die Erweiterung verweisen:

PATCH https://graph.microsoft.com/beta/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions/Com.Contoso.Referral

Sie können auch anhand des vollqualifizierten Namens auf die Erweiterung verweisen:

PATCH https://graph.microsoft.com/beta/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions/Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral

Sie können die Beispielanforderung und den folgenden Anforderungstext verwenden, um die oben genannte Erweiterung auf folgende Weise zu aktualisieren:

  • Durch Ändern des companyName von Wingtip Toys zu Wingtip Toys (USA)
  • Durch Ändern des dealValue von 500050 zu 500100
  • Durch Hinzufügen neuer Daten als die benutzerdefinierte updated-Eigenschaft
{
    "@odata.type": "microsoft.graph.openTypeExtension",
    "extensionName": "Com.Contoso.Referral",
    "companyName": "Wingtip Toys (USA)",
    "dealValue": "500100",
    "expirationDate": "2015-12-03T10:00:00.000Z",
    "updated": "2015-10-29T11:00:00.000Z"
} 

Antwort 1

Es wird unabhängig von der zur Referenzierung der Erweiterung verwendeten Methode jeweils die gleiche Antwort zurückgegeben.

HTTP/1.1 200 OK
Content-type: application/json

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

Anforderung 2

Im zweiten Beispiel wird gezeigt, wie eine Erweiterung in einem Gruppenbeitrag aktualisiert wird. Die Erweiterung wird anfänglich durch die folgende JSON-Nutzlast mit einem expirationDate-Wert von 2015-07-03T13:04:00Z dargestellt:

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/threads('AAQkADJizZJpEWwqDHsEpV_KA%3D%3D')/posts('AAMkADJiUg96QZUkA-ICwMubAADDEd7UAAA%3D')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Estimate",
    "extensionName": "Com.Contoso.Estimate",
    "companyName": "Contoso",
    "expirationDate": "2015-07-03T13:04:00Z",
    "DealValue": 1010100,
    "Strings@odata.type": "#Collection(String)",
    "topPicks": [
        "Employees only",
        "Add spouse or guest",
        "Add family"
    ]
}

Im Folgenden werden die Anforderung und Anforderungstext zum Ändern von expirationDate zu 2016-07-30T11:00:00Z dargestellt:

PATCH https://graph.microsoft.com/beta/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/threads/AAQkADJizZJpEWwqDHsEpV_KA==/posts/AAMkADJiUg96QZUkA-ICwMubAADDEd7UAAA=/extensions/Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Estimate
Content-type: application/json

{
   "@odata.type": "#microsoft.outlookServices.openTypeExtension",
   "extensionName": "Com.Contoso.Estimate",
   "companyName": "Contoso",
   "expirationDate": "2016-07-30T11:00:00.000Z",
   "DealValue": 1010100,
   "topPicks": [
       "Employees only",
       "Add spouse or guest",
       "Add family"
    ]
}

Antwort 2

Im Folgenden wird die Antwort des zweiten Beispiels dargestellt, welche das aktualisierte expirationDate-Element in die Erweiterung zeigt.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/threads('AAQkADJizZJpEWwqDHsEpV_KA%3D%3D')/posts('AAMkADJiUg96QZUkA-ICwMubAADDEd7UAAA%3D')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Estimate",
    "extensionName": "Com.Contoso.Estimate",
    "companyName": "Contoso",
    "expirationDate": "2016-07-30T11:00:00Z",
    "DealValue": 1010100,
    "Strings@odata.type": "#Collection(String)",
    "topPicks": [
        "Employees only",
        "Add spouse or guest",
        "Add family"
    ]
}

Anforderung 3

Das folgende Beispiel zeigt, wie Sie eine geöffnete Erweiterung auf einem driveItem aktualisieren.

PATCH https://graph.microsoft.com/beta/drive/items/01FWCEC553UUOHTOAGBVE2IXBQTIZY3JZQ/extensions/Com.Contoso.Estimate
Content-type: application/json

{
  "extensionName": "newExtensionName",
  "myCustomString": "Contoso data",
  "myCustomBool": false
}

Antwort 3

Das folgende Beispiel zeigt die Antwort, die den aktualisierten extensionName in der Erweiterung enthält.

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "extensionId",
  "extensionName": "newExtensionName",
  "myCustomString": "Contoso data",
  "myCustomBool": false
}

Anforderung 4

Im folgenden Beispiel wird gezeigt, wie eine geöffnete Erweiterung auf einer Website aktualisiert wird.

PATCH https://graph.microsoft.com/beta/sites/8f52f9ad-4f4f-4739-b682-7c0283207937/extensions/Com.Contoso.Estimate
Content-type: application/json

{
  "extensionName": "newExtensionName",
  "myCustomString": "Contoso data",
  "myCustomBool": false
}

Antwort 4

Das folgende Beispiel zeigt die Antwort, die den aktualisierten extensionName in der Erweiterung enthält.

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "extensionId",
  "extensionName": "newExtensionName",
  "myCustomString": "Contoso data",
  "myCustomBool": false
}