Aktualisieren der Inhalte von OneNote-Seiten

  • Artikel

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:
'target':'#intro' legt das Element <div data-id="intro" ...> als Ziel fest.
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:
'target':'div:{33f8a2...}{37}' legt das Element <div id="div:{33f8a2...}{37}" ...> als Ziel fest.

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:

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

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“

Bearer {token}, wobei {token} ein gültiges OAuth 2.0-Zugriffstoken für Ihre registrierte App ist.

Wenn dies fehlt oder ungültig ist, schlägt die Anforderung mit dem Statuscode 401 fehl. Siehe Authentifizierung und Berechtigungen.
Header „Content-Type“

application/json für das Array von JSON-Änderungsobjekten, unabhängig davon, ob es direkt im Anforderungstext gesendet wird oder im Pflichtteil „Commands“ einer mehrteiligen Anforderung.

Mehrteilige Anfragen sind erforderlich, wenn Binärdaten gesendet werden sollen. Sie verwenden den Inhaltstyp multipart/form-data; boundary=part-boundary, wobei {part-boundary} eine Zeichenfolge ist, die den Beginn und das Ende jedes Datenteils signalisiert.

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.

Verwandte Inhalte