Table of contents
TOC
Inhaltsverzeichnis reduzieren
Inhaltsverzeichnis erweitern
Zuletzt aktualisiert: 25.07.2018

Aktualisieren der Inhalte von OneNote-Seiten

Gilt für: Heimanwender-Notizbücher in OneDrive | Unternehmensnotizbücher in Office 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

Senden Sie ein JSON-Änderungsobjekt im Nachrichtentext. Wenn die Anfrage erfolgreich war, gibt die OneNote-API den HTTP-Statuscode 204 zurück.

Erstellen des Anforderungs-URI

Um die Anforderungs-URI zu erstellen, beginnen Sie mit der Dienst-Root-URL:

Notebooks auf OneDrive
https://www.onenote.com/api/v1.0/me/notes/

Notebooks auf OneDrive for Business
https://www.onenote.com/api/v1.0/me/notes/
https://www.onenote.com/api/v1.0/users/{id}/notes/

SharePoint Website-Notebooks
https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/

Vereinheitlichte Gruppen-Notebooks
https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/


Fügen Sie dann den Endpunkt der Seite Inhalt an:

HTML-Seite und alle definierten data-id Werte erhalten

../pages/{id}/content

Ermittelt die Seite HTML, alle definierten data-id Werte und alle generierten id Werte.

../pages/{page-id}/content?includeIDs=true

Die Werte data-id und id werden als ZielIDs für die Elemente verwendet, die aktualisiert werden sollen.


Ihre vollständige Anfrage-URI wird wie eine von diesen aussehen:

https://www.onenote.com/api/v1.0/me/notes/pages/{id}/content

https://www.onenote.com/api/v1.0/myorganization/sitecollections/{id}/sites/{id}/notes/pages/{id}/content

https://www.onenote.com/api/v1.0/myorganization/groups/{id}/notes/pages/{id}/content

Weitere Informationen zur Stamm-URL des Dienstes.

Erstellen Sie den Nachrichtentext

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. Um den Inhalt einer OneNote-Seite zu aktualisieren, fügen Sie HTML-Elemente auf der Seite hinzu und ersetzen diese.

Ihre Änderungen werden im Nachrichtentext als Array von JSON-Änderungsobjekten 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.

[
   {
    'target':'#para-id',
    'action':'insert',
    'position':'before',
    'content':'<img src="image-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>'
  }
]

Siehe weitere Beispiele.

Attribute für JSON-Änderungsobjekte

Verwenden Sie die Attribute target, action, positionund content, um JSON-Objekte für PATCH-Anfragen zu definieren.

Ziel
Das zu aktualisierende Element. Der Wert muss einer der folgenden Bezeichner sein:

BezeichnerBeschreibung
#{data-id}

Diese ID wird optional auf Elementen im Eingabe-HTML definiert, wenn Erstellung einer Seite oder Aktualisierung einer Seite. Dem Wert wird ein # vorangestellt.

Beispiel: 'target':'#intro' zielt auf das Element <div data-id="intro" ...>

id

Dies ist die generierte ID aus der OneNote-API und wird für die meisten Ersetzungsoperationen benötigt. Kein # voranstellen.

Beispiel: 'target':'div:{33f8a2...}{37}' zielt auf das Element <div id="div:{33f8a2...}{37}" ...>

Verwechseln Sie diese nicht mit den ID -Werten, die in der Eingabe-HTMLdefiniert sind. Alle ID Werte, die im Eingabe-HTML gesendet werden, werden verworfen.

TextDas Schlüsselwort, das auf das erste div auf der Seite abzielt. Kein # voranstellen.
TitelDas Schlüsselwort, das auf den Seitentitel abzielt. Kein # voranstellen.

Aktion
Die für das Zielelement auszuführende Aktion. Siehe Unterstützte Aktionen für Elemente.

AktionBeschreibung
anfügen

Fügt den angegebenen Inhalt als erstes oder letztes untergeordnetes Element zum Ziel hinzu, je nach dem im Attribut position festgelegten Wert.

Gilt nur für Körper, div, olund ul Elemente.

einfügenFügt den angegebenen Inhalt als gleichgeordnetes Element vor oder nach dem Ziel hinzu, je nach dem im Attribut position festgelegten Wert.
Voranstellen

Fügt den gelieferten Inhalt dem Ziel als erstes Kind hinzu. Abkürzung für Anhängen + vorher.

Gilt nur für Körper, div, olund ul Elemente.

ersetzen

Ersetzt das Ziel durch den mitgelieferten Inhalt.

Die meisten Ersetzen -Aktionen erfordern die Verwendung der generierten ID für das Ziel (außer img und Objekt Elemente innerhalb eines div, die auch data-idunterstützen).

Position
Die Position, an der der angegebene Inhalt hinzugefügt werden soll, relativ zum Zielelement. Wenn der Wert weggelassen wird, gilt der Standardwert after.

PositionBeschreibung
nach (Standard)

Mit Append: Das letzte Kind des Zielelements.

- Mit insert: das nachfolgende gleichgeordnete Element des Zielelements

Vor

Mit Anfügen: Das letzte Kind des Zielelements.

- Mit insert: das vorhergehende gleichgeordnete Element des Zielelements

Inhalt
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

Die OneNote-API generiert id Werte für die Elemente auf der Seite, 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

Die API verwirft alle id Werte, die in HTML-Eingaben, die für Anforderungen zur Seitenerstellung oder zum Update erforderlich 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.
    • Um einen Titel zu ersetzen, verwenden Sie dasTitel- Schlüsselwort.
    • Um Bilder und Objekte zu ersetzen, die innerhalb eines Divs liegen, 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.

ElementErsetzenUntergeordnetes Element anfügenGleichgeordnetes Element einfügen
Text
(Ziel: erstes „div“-Element auf der Seite)
NeinJaNein
div
(absolut positioniert)
NeinJaNein
div
(innerhalb eines div)
ja (nur id)JaJa
div, img, objekt
(innerhalb eines div)
JaNeinJa
ol, ulja (nur id)JaJa
Tabelleja (nur id)NeinJa
p, li, h1-h6ja (nur id)NeinJa
TitelJaNeinNein

Die folgenden Elemente unterstützen keinerlei Aktualisierungsaktionen:

Beispielanforderungen

Ein -Update-Auftrag enthält eine oder mehrere Änderungen, die als JSON-Änderungsobjekte dargestellt werden. 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:

Kinderelemente anhängen  |  Geschwisterelemente einfügen  |  Elemente ersetzen  |  PATCH-Abfragen vervollständigen

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>'
  }
]

Anhängen 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. Verwenden Sie kein # mit dem Body Ziel. Dieses Beispiel verwendet die Aktion vorstellen als Abkürzung für anhängen + vorne.

[
  {
    '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 Geschwisterelement hinzu. Das Attribut Position bestimmt, ob die Geschwister vor oder nach dem Ziel eingefügt werden sollen. Die Standardposition ist nachher. Siehe Elemente, die eingesetztwerden sollen.

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-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. Um einen Titel zu ersetzen, verwenden Sie dasTitel- Schlüsselwort. Für alle anderen Elemente, die ersetzenmü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 zeigt, wie man den Titel einer Seite ändert. Um den Titel zu ändern, verwenden Sie das Schlüsselwort Titel als Zielwert. Verwenden Sie kein # mit dem Titelziel.

[
  {
    'target':'title',
    'action':'replace',
    'content':'New title'
  }
]

Aktualisieren eines Aufgabenelements

Das folgende Beispiel verwendet die Aktion "Ersetzen", um ein zu erledigendes Kontrollkästchen in einen abgeschlossenen Zustand zu ändern.

[
  {
    'target':'#task1',
    '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.

Komplette PATCH-Anforderungsbeispiele

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://www.onenote.com/api/v1.0/me/notes/pages/{page-id}/content

Content-Type: application/json
Authorization: Bearer {token}

[
   {
    'target':'#para-id',
    'action':'insert',
    'position':'before',
    'content':'<img src="image-url" alt="New image from a URL" />'
  }, 
  {
    'target':'#list-id',
    'action':'append',
    'content':'<li>Item at the bottom of the list</li>'
  }
]

Mehrteilige Anfrage mit binärem Inhalt
Das folgende Beispiel zeigt eine mehrteilige PATCH-Anfrage, die binäre Daten enthält. Multipart-Anfragen erfordern einen "Befehls"-Teil, der den Inhaltstyp application/json angibt und das Array der JSON-Änderungsobjekte enthält. Andere Datenteile können Binärdaten enthalten. Bauteilnamen sind typischerweise Strings, die mit der aktuellen Zeit in Millisekunden oder einer zufälligen GUID angehängt werden.

PATCH https://www.onenote.com/api/v1.0/me/notes/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--

Anfrage- und Antwortinformationen für PATCH-Anfragen

Daten in der AnforderungBeschreibung
ProtokollAlle Anforderungen verwenden das SSL/TLS HTTPS-Protokoll.
Header „Authorization“

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

Bei Fehlen oder Ungültigkeit schlägt die Anfrage mit einem 401-Statuscode fehl. Siehe Authentifizierung und Berechtigungen.

Header „Content-Type“

application/json für das Array der JSON-Änderungsobjekte, ob direkt im Nachrichtentext oder im benötigten "Commands"-Teil von multipart requests.

Mehrteilige Anforderungen werden beim Senden von Binärdaten benötigt und verwenden den Inhaltstyp multipart/form-data; boundary=part-boundary, wobei {part-boundary} eine Zeichenfolge ist, der den Anfang und das Ende jedes Datenteils anzeigt.

Daten in der AntwortBeschreibung
Erfolgscode204 HTTP-Statuscode. Für eine PATCH-Anforderung werden keine JSON-Daten zurückgegeben.
FehlerWenn die Aktualisierungsanfrage fehlschlägt, gibt die API eine Fehlermeldung im Objekt @api.diagnostics im Antworttext zurück. Die Anfrage wird fehlschlagen, wenn:
- Das JSON-Objekt enthält ungültige Attribute oder ist fehlerhaft.
- Das Ziel-, die Aktion- oder das Inhalt-Attribut fehlt.
- Das Zielelement ist nicht vorhanden.
- Das Format des Zielwertes ist ungültig. Beispiel: Eine data-id wird nicht mit einem # vorangestellt.
- Das Zielelement untersützt die angegebene Aktion nicht.
- Der Wert für Aktion oder Position ist ungültig.
Header „X-CorrelationId“Ein globaler Bezeichner (GUID), über den die Anforderung eindeutig identifiziert wird. Sie können diesen Wert zusammen mit dem Wert des Datums-Headers verwenden, wenn Sie mit Microsoft-Support arbeiten, um Probleme zu beheben.

Aufbau der OneNote Stamm-Dienst-URL

Die Stamm-URL des OneNote-Diensts verwendet das folgende Format für alle Aufrufe der OneNote-API.

https://www.onenote.com/api/{version}/{location}/notes/


Das version Segment in der URL steht für die Version der OneNote-API, die Sie verwenden möchten.

  • Verwenden Sie v1.0 für stabilen Produktionscode.
  • Verwenden Sie beta, um ein Feature zu testen, das sich in der Entwicklung befindet. Features und Funktionen in der Betaversion ändern sich möglicherweise, sodass Sie sie nicht in Ihrem Produktionscode verwenden sollten.


Das location Segment in der URL steht für den Auftenhaltsort der Notebooks, auf die Sie zugreifen möchten.

Notebooks auf OneDrive (Consumer)
Verwenden Sie me für OneNote-Inhalt, auf den der aktuelle Benutzer zugreifen kann (eigene und freigegebene Inhalte).

Notebooks auf OneDrive for Business
Verwenden Sie me für OneNote-Inhalte, die dem aktuellen Benutzer gehören.

Verwenden Sie users/{id} für OneNote-Inhalte, die der (in der URL) angegebene Benutzer für den aktuellen Benutzer freigegeben hat. Verwenden Sie die Azure AD Graph API, um Benutzer-IDs zu erhalten.

SharePoint Website-Notebooks
Teamwebsites und andere SharePoint-Websites können OneNote-Notebooks in ihren Dokumentbibliotheken enthalten.

Verwenden Sie myOrganization/siteCollections/{id}/sites/{id} für OneNote-Inhalte auf einer Website des Mandanten, bei dem der aktuelle Benutzer angemeldet ist. Es wird nur der aktuelle Mandant unterstützt, auf den über das Schlüsselwort myOrganization zugegriffen wird. Erfahren Sie, wie Sie Website-IDs erhalten.

Office 365 Gruppen-Notebooks
Office 365 Gruppen sind Teil der vernetzten Office 365 Erfahrung. Gruppenmitglieder können Notebooks, Dateien und E-Mails freigeben.

Verwenden Sie myOrganization/groups/{id} für OneNote-Inhalte in der angegebenen Gruppe, in der der aktuelle Benutzer Mitglied ist. Office 365 Gruppen (die den vereinheitlichten groupType zurückgeben) sind der einzige unterstützte Gruppentyp. Verwenden Sie die Azure AD Graph API, um Gruppen-IDs zu erhalten.


Verwenden Sie die Methode FromUrl, um die Websitesammlung und die Site-IDs zu erhalten

Sie können die Methode FromUrl verwenden, um die Websitesammlung und die Site-IDs für eine angegebene absolute Site-URL zu erhalten. Sie sollten diesen Aufruf nur bei Bedarf durchführen und dann die Werte für die zukünftige Verwendung speichern.

Das Format der Site-URL hängt von Ihrer Konfiguration ab, zum Beispiel https://domain.sharepoint.com/site-a oder https://domain.com/sites/site-a.

Beispielanfrage:

GET https://www.onenote.com/api/v1.0/myOrganization/siteCollections/FromUrl(url='{full-path-to-SharePoint-site}')
Authorization: Bearer {token}
Accept: application/json

Beispielantwort:

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Microsoft.OneNote.Api.SiteMetadata",
  "siteCollectionId":"09d1a587-a84b-4264-3d15-669429be8cc5",
  "siteId":"d9e4d5c8-683f-4363-89ae-18c4e3da91e9"
}

Voraussetzungen für die Verwendung von FromUrl und die Arbeit mit SharePoint Site Notebooks:

  • Sie können nur OneNote-Notebooks, Abschnittsgruppen, Abschnitte und Seiten auf Websites erstellen, die über eine Standarddokumentbibliothek verfügen. (Einige Site-Vorlagen erstellen keine Standarddokumentbibliothek.) GET-Anfragen liefern jedoch OneNote-Inhalte aus allen Dokumentbibliotheken auf der Website.
  • Die Stamm-Url des OneNote-Diensts ist unveränderlich, d. h. Sie können keinen SharePoint REST-API-Site-Pfad verwenden und dann den notes Endpunkt darauf anheften.
  • Der Benutzer, in dessen Namen Sie aufrufen, muss Mitglied der Site sein.
  • FromUrl arbeitet nur mit indizierten Sites. Es kann mehrere Stunden dauern, eine neue Site zu indizieren.

Berechtigungen

Sie müssen zum Erstellen oder Aktualisieren der OneNote-Seiten die entsprechenden Berechtigungen anfordern. Wählen Sie die unterste Ebene an Berechtigungen aus, die Ihre App für ihre Arbeit benötigt.

PlattformBerechtigungsbereich
Consumeroffice.onenote_update_by_app, office.onenote_update
UnternehmenNotes.ReadWrite.CreatedByApp, Notes.ReadWrite, Notes.ReadWrite.All

Weitere Informationen zu Berechtigungsbereichen und deren Funktionsweise finden Sie unter OneNote-Berechtigungsbereiche.

Weitere Ressourcen

© 2018 Microsoft