Aktualisieren der Inhalte von OneNote-Seiten
Gilt für Heimanwender-Notizbücher auf OneDrive | Enterprise-Notizbücher auf Microsoft 365
Sollen die Inhalte einer OneNote-Seite aktualisiert werden, senden Sie eine PATCH-Anforderung an den Endpunkt content der Seite:
PATCH ../notes/pages/{id}/content
Im Anforderungstext senden Sie ein JSON-Änderungsobjekt. Wenn die Anforderung erfolgreich ist, gibt Microsoft Graph den HTTP-Statuscode 204 zurück.
Zusammensetzen des Anforderungs-URI
Beginnen Sie bei der Zusammensetzung des Anforderungs-URI mit der Stamm-URL des Diensts:
https://graph.microsoft.com/v1.0/me/onenote
Fügen Sie dann den Endpunkt content der Seite an:
Abrufen des HTML-Codes der Seite und aller definierten Werte des Typs data-id
../pages/{id}/content
Abrufen des HTML-Codes der Seite, aller definierten Werte des Typs data-id und aller generierten Werte des Typs id
../pages/{page-id}/content?includeIDs=true
Die Werte des Typs data-id und des Typs id dienen als Bezeichner für die Elemente mit dem Attribut target, also die Elemente, die aktualisiert werden sollen.
Der vollständige Anforderungs-URI sieht so aus:https://graph.microsoft.com/v1.0/me/onenote/pages/{id}/content
Weitere Informationen zur Stamm-URL des Service finden Sie unter diesem Link.
Erstellen des Anforderungstexts
Der HTML-Code einer OneNote-Seite enthält Text, Bilder und andere Inhalte, die in Strukturen wie Elementen des Typs div, img oder ol organisiert sind. Sollen die Inhalte einer OneNote-Seite aktualisiert werden, fügen Sie der Seite HTML-Elemente hinzu oder ersetzen vorhandene HTML-Elemente.
Ihre Änderungen werden als Array von JSON-Änderungsobjekten im Anforderungstext gesendet. Jedes Objekt definiert das Zielelement, neue HTML-Inhalte und die auf die Inhalte anzuwendende Aktion.
Das folgende Array definiert zwei Änderungen. Bei der ersten wird ein Bild über einem Absatz als gleichgeordnetes Element eingefügt, bei der zweiten wird ein Element an eine Liste als letztes untergeordnetes Element angefügt.
Hinweis
Wenn Sie ein Bild auf einer OneNote-Seite aktualisieren, können Sie keine WWW-Links verwenden. Der Dienst versucht nicht, zufällige Ressourcen herunterzuladen. Stattdessen muss das Bild Teil der Anforderung sein, entweder durch eine image-data-url oder einen Teilnamen einer mehrteiligen Anforderung.
[
{
'target':'#para-id',
'action':'insert',
'position':'before',
'content':'<img src="image-data-url-or-part-name" alt="Image above the target paragraph" />'
},
{
'target':'#list-id',
'action':'append',
'content':'<li>Item at the end of the list</li>'
}
]
Weitere Beispiele finden Sie hier.
Attribute für JSON-Änderungsobjekte
JSON-Objekte für PATCH-Anforderungen werden mithilfe der Attribute target, action, position und content definiert.
target
Das zu aktualisierende Element. Der Wert muss einer der folgenden Bezeichner sein:
Bezeichner | Beschreibung |
---|---|
#{data-id} | Diese ID wird bei der Erstellung einer Seite oder der Aktualisierung einer Seite optional den Elementen im Eingabe-HTML-Code zugewiesen. Setzen Sie vor den Wert als Präfix das Symbol #. Beispiel: |
id | Hierbei handelt es sich um die von Microsoft Graph generierte ID. Sie ist für die meisten Ersetzungsvorgänge erforderlich. Setzen Sie hier kein Symbol # als Präfix. Beispiel: Verwechseln Sie IDs dieses Typs nicht mit den Werten des Typs id im Eingabe-HTML-Code. Alle im Eingabe-HTML-Code gesendeten Werte des Typs id werden verworfen. |
body | Das Schlüsselwort, dass als Ziel das erste „div“-Element auf der Seite festlegt. Setzen Sie hier kein Symbol # als Präfix. |
title | Das Schlüsselwort, das als Ziel den Seitentitel festlegt. Setzen Sie hier kein Symbol # als Präfix. |
Aktion
Die für das Zielelement auszuführende Aktion. Siehe Unterstützte Aktionen für Elemente.
Aktion | Beschreibung |
---|---|
append | Fügt den angegebenen Inhalt als erstes oder letztes untergeordnetes Element zum Ziel hinzu, je nach dem im Attribut position festgelegten Wert. Kann nur auf Elemente des Typs body, div, ol oder ul angewendet werden. |
insert | Fügt den angegebenen Inhalt als gleichgeordnetes Element vor oder nach dem Ziel hinzu, je nach dem im Attribut position festgelegten Wert. |
prepend | Fügt den angegebenen Inhalt als erstes untergeordnetes Element zum Ziel hinzu. Kurzbefehl als Ersatz für append + before. Kann nur auf Elemente des Typs body, div, ol oder ul angewendet werden. |
replace | Ersetzt das Ziel durch den angegebenen Inhalt. Für die meisten Aktionen des Typs replace muss das Ziel in Form der generierten ID angegeben werden. (Ausnahme: Elemente des Typs img oder object innerhalb eines „div“-Elements. Sie können auch per data-id angegeben werden.) |
position
Die Position, an der der angegebene Inhalt hinzugefügt werden soll, relativ zum Zielelement. Wenn der Wert weggelassen wird, gilt der Standardwert after.
Position | Beschreibung |
---|---|
after (Standard) | Mit append: das letzte untergeordnete Element des Zielelements Mit insert: das nachfolgende gleichgeordnete Element des Zielelements |
before | Mit append: das erste untergeordnete Element des Zielelements Mit insert: das vorhergehende gleichgeordnete Element des Zielelements |
content
Eine Zeichenfolge aus wohlgeformtem HTML-Code, die der Seite hinzugefügt werden soll, sowie alle Bild- oder Dateibinärdaten. Wenn der Inhalt Binärdaten enthält, muss die Anforderung unter Verwendung des Inhaltstyps multipart/form-data
in einem Teil „Commands“ gesendet werden (siehe Beispiel).
Generierte IDs
Microsoft Graph generiert Werte des Typs id für alle Seitenelemente, die aktualisiert werden können. Abrufen können Sie die generierten IDs über den Abfragezeichenfolgenausdruck includeIDs=true
in der GET-Anforderung:
GET ../notes/pages/{page-id}/content?includeIDs=true
Hinweis
Die API verwirft alle ID-Werte , die im Eingabe-HTML-Code von Create-Page- und Update-Page-Anforderungen definiert sind.
Das folgende Beispiel zeigt generierte IDs für einen Absatz und ein Bild im Ausgabe-HTML-Code einer Seite.
<p id="p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}">Some text on the page</p>
<img id="img:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{45}" ... />
Generierte id-Werte ändern sich nach dem Aktualisieren einer Seite möglicherweise, Sie sollten daher die aktuellen Werte abrufen, bevor Sie eine PATCH-Anforderung erstellen, die diese verwendet.
Angeben können Sie Zielelemente in Form eines Werts des Typs data-id oder eines Werts des Typs id. Dabei gilt:
- Bei Aktionen des Typs append oder des Typs insert können Sie beide ID-Typen als Zielwert verwenden.
- Bei Aktionen des Typs replace müssen Sie für alle Elemente die generierte ID verwenden. Ausgenommen hiervon sind lediglich der Seitentitel sowie Bilder und Objekte innerhalb von „div“-Elementen.
- Ersetzen eines Titels: Verwenden Sie das Schlüsselwort title.
- Ersetzen von Bildern und Objekten in einem „div“-Element: Verwenden Sie entweder data-id oder id.
Im folgenden Beispiel wird das Ziel in Form eines Werts des Typs id angegeben. Setzen Sie vor generierten IDs niemals das Präfix #.
[
{
'target':'p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}',
'action':'insert',
'position':'before',
'content':'<p>This paragraph goes above the target paragraph.</p>'
}
]
Unterstützte Elemente und Aktionen
Viele Elemente auf einer Seite lassen sich aktualisieren, doch unterstützt jeder Elementtyp nur bestimmte Aktionen. In der folgenden Tabelle sind die unterstützten Zielelemente aufgeführt sowie die Aktualisierungsaktionen, die sie unterstützen.
Element | Ersetzen | Untergeordnetes Element anfügen | Gleichgeordnetes Element einfügen |
---|---|---|---|
body (Ziel: erstes „div“-Element auf der Seite) |
Nein | Ja | Nein |
div (absolut positioniert) |
Nein | Ja | Nein |
div (in einem anderen „div“-Element) |
Ja (nur per „id“) |
Ja | Ja |
img, object (in einem anderen „div“-Element) |
Ja | Nein | Ja |
ol, ul |
Ja (nur per „id“) |
Ja | Ja |
table |
Ja (nur per „id“) |
Nein | Ja |
p, li, h1-h6 |
Ja (nur per „id“) |
Nein | Ja |
title | Ja | Nein | Nein |
Die folgenden Elemente unterstützen keinerlei Aktualisierungsaktionen:
- img (absolut positioniert)
- object (absolut positioniert)
- tr, td
- meta
- head
- span
- a
- „style“-Tags
Beispielanforderungen
Eine Aktualisierungsanforderung enthält eine oder mehrere Änderungen, jeweils dargestellt als JSON-Änderungsobjekt. Diese Objekte können unterschiedliche Ziele auf der Seite sowie unterschiedliche Aktionen und Inhalte für diese Ziele definieren.
Die folgenden Beispiele zeigen JSON-Objekte, die in PATCH-Anforderungen verwendet werden, sowie vollständige PATCH-Anforderungen:
- Anfügen von untergeordneten Elementen
- Einfügen von gleichgeordneten Elementen
- Ersetzen von Elementen
- Vollständige PATCH-Anforderungen
Anfügen von untergeordneten Elementen
Die append-Aktion fügt ein untergeordnetes Element zu einem body-, div- (innerhalb eines div-Elements), ol- oder ul-Element hinzu. Das position-Attribut bestimmt, ob das untergeordnete Element vor oder nach dem Tag angefügt wird. Die Standardposition ist after.
Anfügen an ein „div“-Element
Das folgende Beispiel fügt dem Element div1 zwei untergeordnete Knoten hinzu. Als erstes untergeordnetes Element wird ein Bild hinzugefügt, als letztes untergeordnetes Element ein Absatz.
[
{
'target':'#div1',
'action':'append',
'position':'before',
'content':'<img data-id="first-child" src="image-url-or-part-name" />'
},
{
'target':'#div1',
'action':'append',
'content':'<p data-id="last-child">New paragraph appended to the div</p>'
}
]
Anfügen an das body-Element
Sie können body als schnellen Weg verwenden, um ein untergeordnetes Element im ersten „div“-Element auf der Seite anzufügen.
Im folgenden Beispiel werden dem ersten „div“-Element auf der Seite zwei Absätze hinzugefügt, einer als erstes untergeordnetes Element und einer als letztes untergeordnetes Element. Setzen Sie vor ein Ziel des Typs body niemals das Präfix #. In diesem Beispiel verwenden wir die Aktion prepend als Kurzversion von append + before.
[
{
'target':'body',
'action':'prepend',
'content':'<p data-id="first-child">New paragraph as first child in the first div</p>'
},
{
'target':'body',
'action':'append',
'content':'<p data-id="last-child">New paragraph as last child in the first div</p>'
}
]
Anfügen an eine Liste
Im folgenden Beispiel wird ein Listenelement als letztes untergeordnetes Element zur Zielliste hinzugefügt. Die list-style-type-Eigenschaft ist definiert, da das Element einen nicht standardmäßigen Listenstil verwendet.
[
{
'target':'#circle-ul',
'action':'append',
'content':'<li style="list-style-type:circle">Item at the end of the list</li>'
}
]
Einfügen von gleichgeordneten Elementen
Die Aktion insert fügt dem Zielelement ein gleichgeordnetes Element hinzu. Das Attribut position legt fest, ob das gleichgeordnete Element vor oder nach dem Ziel eingefügt wird. Die Standardposition ist after. In diesem Abschnitt finden Sie alle Elemente, die insert unterstützen.
Einfügen von gleichgeordneten Elementen
Im folgenden Beispiel werden zwei gleichgeordnete Knoten zu der Seite hinzugefügt. Über dem para1-Element wird ein Bild und über dem para2-Element wird ein Absatz hinzugefügt.
[
{
'target':'#para1',
'action':'insert',
'position':'before',
'content':'<img src="image-data-url-or-part-name" alt="Image inserted above the target" />'
},
{
'target':'#para2',
'action':'insert',
'content':'<p data-id="next-sibling">Paragraph inserted below the target</p>'
}
]
Ersetzen von Elementen
Sie können entweder den Wert data-id oder den generierten Wert id als Zielwert nutzen, wenn Sie Elemente des Typs img oder object in einem „div“-Element ersetzen möchten. Verwenden Sie das Schlüsselwort title, wenn der Seitentitel ersetzt werden soll. Bei allen anderen Elementen, die replace unterstützen, müssen Sie die generierte ID verwenden.
Ersetzen eines Bilds
Im folgenden Beispiel wird ein Bild durch ein „div“-Element ersetzt. Als Zielwert wird der Wert data-id des Bilds verwendet.
[
{
'target':'#img1',
'action':'replace',
'content':'<div data-id="new-div"><p>This div replaces the image</p></div>'
}
]
Aktualisieren einer Tabelle
In diesem Beispiel wird gezeigt, wie eine Tabelle mithilfe ihrer generierten ID aktualisiert wird. Das Ersetzen von tr- und td-Elementen wird nicht unterstützt, Sie können jedoch die gesamte Tabelle ersetzen.
[
{
'target':'table:{de3e0977-94e4-4bb0-8fee-0379eaf47486}{11}',
'action':'replace',
'content':'<table data-id="football">
<tr><td><p><b>Brazil</b></p></td><td><p>Germany</p></td></tr>
<tr><td><p>France</p></td><td><p><b>Italy</b></p></td></tr>
<tr><td><p>Netherlands</p></td><td><p><b>Spain</b></p></td></tr>
<tr><td><p>Argentina</p></td><td><p><b>Germany</b></p></td></tr></table>'
}
]
Ändern des Titels
Dieses Beispiel demonstriert, wie Sie den Titel einer Seite ändern. Verwenden Sie zum Ändern des Titels als Zielwert das Schlüsselwort title. Setzen Sie vor ein Ziel des Typs „title“ niemals das Präfix #.
[
{
'target':'title',
'action':'replace',
'content':'New title'
}
]
Aktualisieren eines Aufgabenelements
Im folgenden Beispiel wird die Aktion „replace“ verwendet, um das Kontrollkästchen eines Aufgabenelements auf „Abgeschlossen“ zu setzen.
[
{
'target':'p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}',
'action':'replace',
'content':'<p data-tag="to-do:completed" data-id="task1">First task</p>'
}
]
Weitere Informationen zum Verwenden des Attributs data-tag finden Sie im Artikel zum Thema Verwenden von Notiztags.
Beispiele für vollständige PATCH-Anforderungen
Die folgenden Beispiele zeigen vollständige PATCH-Anforderungen.
Anforderung ausschließlich mit Textinhalten
Das folgende Beispiel zeigt eine PATCH-Anforderung, die den Inhaltstyp application/json verwendet. Dieses Format können Sie verwenden, wenn Ihr Inhalt keine Binärdaten enthält.
PATCH https://graph.microsoft.com/v1.0/me/onenote/notebooks/pages/{page-id}/content
Content-Type: application/json
Authorization: Bearer {token}
[
{
'target':'#para-id',
'action':'insert',
'position':'before',
'content':'<img src="image-data-url" alt="New image from a URL" />'
},
{
'target':'#list-id',
'action':'append',
'content':'<li>Item at the bottom of the list</li>'
}
]
Mehrteilige Anforderung mit Binärinhalten
Das folgende Beispiel zeigt eine mehrteilige PATCH-Anforderung, die Binärdaten enthält. Mehrteilige Anforderungen müssen einen Teil „Commands“ enthalten, in dem der Inhaltstyp application/json angegeben ist und der das Array von JSON-Änderungsobjekten enthält. Andere Datenteile dürfen Binärdaten enthalten. Die Namen von Teilen sind in der Regel Zeichenfolgen, an die die aktuelle Zeit in Millisekunden oder eine zufällige GUID angefügt ist.
PATCH https://graph.microsoft.com/v1.0/me/onenote/notebooks/pages/{page-id}/content
Content-Type: multipart/form-data; boundary=PartBoundary123
Authorization: Bearer {token}
--PartBoundary123
Content-Disposition: form-data; name="Commands"
Content-Type: application/json
[
{
'target':'img:{2998967e-69b3-413f-a221-c1a3b5cbe0fc}{42}',
'action':'replace',
'content':'<img src="name:image-part-name" alt="New binary image" />'
},
{
'target':'#list-id',
'action':'append',
'content':'<li>Item at the bottom of the list</li>'
}
]
--PartBoundary123
Content-Disposition: form-data; name="image-part-name"
Content-Type: image/png
... binary image data ...
--PartBoundary123--
Anforderungs- and Antwortinformationen in PATCH-Anforderungen
Daten in der Anforderung | Beschreibung |
---|---|
Protokoll | Alle Anforderungen verwenden das SSL/TLS HTTPS-Protokoll. |
Header „Authorization“ |
Wenn dies fehlt oder ungültig ist, schlägt die Anforderung mit dem Statuscode 401 fehl. Siehe Authentifizierung und Berechtigungen. |
Header „Content-Type“ |
Mehrteilige Anfragen sind erforderlich, wenn Binärdaten gesendet werden sollen. Sie verwenden den Inhaltstyp |
Antwortdaten | Beschreibung |
---|---|
Erfolgscode | Ein 204 HTTP-Statuscode. Für eine PATCH-Anforderung werden keine JSON-Daten zurückgegeben. |
Fehler | Informationen zu OneNote-Fehlern, die Microsoft Graph zurückgeben kann, finden Sie unter Fehlercodes für OneNote-APIs in Microsoft Graph. |
Zusammensetzen der Stamm-URL des Microsoft Graph-Diensts
Die Stamm-URL des OneNote-Diensts verwendet das folgende Format für alle Aufrufe der OneNote-API:
https://graph.microsoft.com/{version}/me/onenote/
Das Segment version
in der URL ist die Version von Microsoft Graph, die verwendet werden soll. Setzen Sie v1.0
für stabilen Produktionscode. Setzen Sie beta
, wenn Sie ein Feature testen möchten, das sich noch in der Entwicklung befindet. Features und Funktionen in der Betaphase werden möglicherweise noch geändert und sollten daher nicht in Produktionscode verwendet werden.
Setzen Sie me
für OneNote-Inhalte, auf die der aktuelle Benutzer zugreifen kann (eigene und freigegebene Inhalte). Setzen Sie users/{id}
für OneNote-Inhalte, die der (in der URL) angegebene Benutzer für den aktuellen Benutzer freigegeben hat. Verwenden der Benutzer-API.
Hinweis
Sie können Benutzer-IDs abrufen, indem Sie eine GET-Anforderung für ausführen https://graph.microsoft.com/v1.0/users
.
Berechtigungen
Zum Aktualisieren von OneNote-Seiten müssen Sie die entsprechenden Berechtigungen anfordern. Wählen Sie die niedrigste Berechtigungsstufe, die erforderlich ist, damit Ihre App korrekt funktioniert.
- Notes.ReadWrite
- Notes.ReadWrite.All
Weitere Informationen zu Berechtigungsbereichen und deren Funktionsweise finden Sie unter OneNote-Berechtigungsbereiche.