Erstellen von OneNote-SeitenCreate OneNote pages

Gilt für: Heimanwender-Notizbücher in OneDrive | Unternehmensnotizbücher in Office 365Applies to: Consumer notebooks on OneDrive | Enterprise notebooks on Office 365

Zum Erstellen einer OneNote-Seite senden Sie eine POST-Anforderung an einen pages-Endpunkt.To create a OneNote page, you send a POST request to a pages endpoint. Beispiel:For example:

POST ../notes/sections/{id}/pages


Senden Sie den HTML-Code, der die Seite definiert, im Nachrichtentext.Send the HTML that defines the page in the message body. Wenn die Anforderung erfolgreich ist, gibt Microsoft Graph den HTTP-Statuscode 201 zurück.If the request is successful, Microsoft Graph returns a 201 HTTP status code.

Hinweis: Informationen zu den POST-Anforderungen, mit denen Sie Abschnitte, Abschnittsgruppen und Notizbücher erstellen können, finden Sie in der interaktiven REST-Referenz.Note: To learn about the POST requests you can send to create sections, section groups, and notebooks, see our interactive REST reference.

Erstellen des Anforderungs-URIConstruct the request URI

Um den URI der POST-Anforderung zu erstellen, beginnen Sie mit der Stamm-URL des Diensts:To construct the POST request URI, start with the service root URL:

https://graph.microsoft.com/v1.0/me/onenote


Fügen Sie dann den pages-Endpunkt an:Then append the pages endpoint:

  • Erstellen einer Seite in einem beliebigen Abschnitt (angegeben durch den Abschnittsnamen)Create a page in any section (specified by section name)

    .../pages?sectionName=DefaultSection

  • Erstellen einer Seite in einem beliebigen Abschnitt (angegeben durch die ID)Create a page in any section (specified by ID)

    .../sections/{section-id}/pages

Wenn Sie Seiten im persönlichen Notizbuch des Benutzers erstellen, bietet Microsoft Graph auch Endpunkte, die Sie zum Erstellen von Seiten im Standardnotizbuch verwenden können:If you're creating pages in the user's personal notebook, Microsoft Graph also provides endpoints you can use to create pages in the default notebook:

  • Erstellen einer Seite im Standardabschnitt des StandardnotizbuchsCreate a page in the default section of the default notebook

    ../pages

Ihr vollständiger Anforderungs-URI gleicht einem der folgenden Beispiele:Your full request URI will look like one of these examples:

  • https://graph.microsoft.com/v1.0/me/onenote/sections/{id}/pages
  • https://graph.microsoft.com/v1.0/me/onenote/pages?sectionName=Homework

Hier erfahren Sie mehr über die Stamm-URL des Diensts.Learn more about the service root URL.

Verwenden des URL-Parameters sectionNameUsing the sectionName URL parameter

Die folgenden Regeln gelten bei Verwendung des sectionName-Parameters zum Erstellen einer Seite in einem benannten Abschnitt im Standardnotizbuch:The following rules apply when using the sectionName parameter to create a page in a named section in the default notebook:

  • Nur auf Abschnitte auf oberster Ebene kann verwiesen werden (keine Abschnitte in Abschnittsgruppen).Only top-level sections can be referenced (not sections within section groups).

  • Ist im Standardnotizbuch kein Abschnitt mit dem angegebenen Namen vorhanden, wird er von der API erstellt.If a section with the specified name doesn't exist in the default notebook, the API creates it. Die folgenden Zeichen sind für Abschnittsnamen nicht zulässig: ? * \ / : < > | & # " % ~These characters are not allowed for section names: ? * \ / : < > | & # " % ~

  • Beim Abgleich von Abschnittsnamen wird die Groß-und Kleinschreibung nicht beachtet, aber beim Erstellen von Abschnitten bleibt die Groß-/Kleinschreibung erhalten.Section names are case-insensitive for matching, but case is preserved when sections are created. Somit wird z. B. „Mein neuer Abschnitt“ genau so angezeigt, aber „mein neuer abschnitt“ würde bei nachfolgenden Übermittlungen ebenfalls übereinstimmen.So "My New Section" will display like that, but "my new section" would also match on subsequent posts.

  • Abschnittsnamen müssen URL-codiert sein.Section names must be URL-encoded. Z. B. müssen Leerzeichen als %20 codiert werden.For example, spaces must be encoded as %20.

  • Der sectionName-Parameter gilt nur für die Route ../notes/pages (nicht für ../notes/sections/{id}/pages).The sectionName parameter is valid only with the ../notes/pages route (not ../notes/sections/{id}/pages).

Da Abschnitte erstellt werden, wenn sie noch nicht vorhanden sind, ist es sicherer, diesen Aufruf mit jeder Seite zu verwenden, die Ihre App erstellt.Because sections are created if they don't exist, it's safe to use this call with every page your app creates. Benutzer können Abschnitte möglicherweise umbenennen, doch die API erstellt einen neuen Abschnitt mit dem Abschnittsnamen, den Sie angeben.Users might rename sections, but the API will create a new section with the section name that you supply.

Hinweis: Die von der API zurückgegebenen Links für Seiten in einem umbenannten Abschnitt führen weiterhin zu den betreffenden älteren Seiten.Note: The links returned by the API for pages in a renamed section will still reach those older pages.

Erstellen des NachrichtentextsConstruct the message body

Der HTML-Code, der Seiteninhalt definiert, wird als Eingabe-HTML bezeichnet.The HTML that defines page content is called input HTML. Eingabe-HTML unterstützt eine Teilmenge der Standard-HTML und -CSS mit zusätzlichen benutzerdefinierten Attributen.Input HTML supports a subset of standard HTML and CSS, with the addition of custom attributes. (Benutzerdefinierte Attribute, wie data-id und data-render-src, werden in Eingabe- und Ausgabe-HTML beschrieben.)(Custom attributes, like data-id and data-render-src, are described in Input and output HTML.)

Senden Sie die Eingabe-HTML im Nachrichtentext der POST-Anforderung.Send the input HTML in the message body of the POST request. Sie können die Eingabe-HTML direkt im Nachrichtentext mit dem Inhaltstyp application/xhtml+xml oder text/html senden, oder Sie können sie im „Presentation“-Teil einer mehrteiligen Anforderung senden.You can send the input HTML directly in the message body using the application/xhtml+xml or text/html content type, or you can send it in the "Presentation" part of a multipart request.

Das folgende Beispiel sendet die Eingabe-HTML direkt im Nachrichtentext.The following example sends the input HTML directly in the message body.

POST https://graph.microsoft.com/v1.0/me/onenote/pages
Authorization: Bearer {token}
Content-Type: application/xhtml+xml

<!DOCTYPE html>
<html>
  <head>
    <title>A page with a block of HTML</title>
    <meta name="created" content="2015-07-22T09:00:00-08:00" />
  </head>
  <body>
    <p>This page contains some <i>formatted</i> <b>text</b> and an image.</p>
    <img src="https://..." alt="an image on the page" width="500" />
  </body>
</html>

Wenn Sie Binärdaten senden, müssen Sie eine mehrteilige Anforderung verwenden.If you're sending binary data, you must use a multipart request.

Hinweis: Zur Vereinfachung der Programmierung und Konsistenz in Ihrer App können Sie mehrteilige Anforderungen verwenden, um alle Seiten zu erstellen.Note: To simplify programming and consistency in your app, you can use multipart requests to create all pages. Es ist ratsam, eine Bibliothek zu verwenden, um mehrteilige Nachrichten zu erstellen.It's a good idea to use a library to construct multipart messages. Dadurch wird das Risiko der Erstellung von fehlerhaften Nutzlasten reduziert.This reduces the risk of creating malformed payloads.

Anforderungen und Einschränkungen für Eingabe-HTML in POST-AnforderungenRequirements and limitations for input HTML in POST pages requests

Beachten Sie beim Senden von Eingabe-HTML diese allgemeinen Anforderungen und Einschränkungen:When sending input HTML, be aware of these general requirements and limitations:

  • Die Eingabe-HTML sollte UTF-8-codierter und wohlgeformter XHTML-Code sein.Input HTML should be UTF-8 encoded and well-formed XHTML. Für alle Container-Starttags müssen die entsprechenden schließenden Tags vorhanden sein.All container start tags require matching closing tags. Alle Attributwerte müssen in doppelte oder einzelne Anführungszeichen eingeschlossen werden.All attribute values must be surrounded by double- or single-quote marks.

  • JavaScript-Code, hinzugefügte Dateien und CSS werden entfernt.JavaScript code, included files, and CSS are removed.

  • HTML-Formulare werden vollständig entfernt.HTML forms are removed in their entirety.

  • Microsoft Graph unterstützt eine Teilmenge der HTML-Elemente.Microsoft Graph supports a subset of HTML elements.

  • Microsoft Graph unterstützt eine Teilmenge der allgemeinen HTML-Attribute und eine Reihe von benutzerdefinierten Attributen, z. B. das data-id-Attribut, das für das Aktualisieren von Seiten verwendet wird.Microsoft Graph supports a subset of common HTML attributes and a set of custom attributes, such as the data-id attribute used for updating pages. Unterstützte Attribute finden Sie unter Eingabe- und Ausgabe-HTML.For supported attributes, see Input and output HTML.

Unterstützte HTML und CSS für OneNote-SeitenSupported HTML and CSS for OneNote pages

Nicht alle Elemente, Attribute und Eigenschaften werden (in HTML4, XHTML, CSS, HTML5 usw.) unterstützt.Not all elements, attributes, and properties are supported (in HTML4, XHTML, CSS, HTML5, etc.). Stattdessen akzeptiert Microsoft Graph einen eingeschränkten Satz von HTML-Elementen, der der üblichen Verwendung von OneNote besser entspricht.Instead, Microsoft Graph accepts a limited set of HTML that better fits how people use OneNote. Weitere Informationen finden Sie unter Unterstützung von HTML-Tags für Seiten.For more information, see HTML tag support for pages. Wenn ein Tag dort nicht aufgeführt ist, wird es wahrscheinlich ignoriert.If a tag's not listed there, it'll probably be ignored.

Die folgende Liste zeigt die grundlegenden Elementtypen, die Microsoft Graph unterstützt:The following list shows the basic element types that Microsoft Graph supports:

  • <head> und <body><head> and <body>

  • <title> und <meta>, die den Seitentitel und das Erstellungsdatum festlegen<title> and <meta> that set the page title and creation date

  • <h1> bis <h6> für Abschnittsüberschriften<h1> through <h6> for section headings

  • <p> für Absätze<p> for paragraphs

  • <ul>, <ol> und <li> für Listen und Listenelemente<ul>, <ol>, and <li> for lists and list items

  • <table>, <tr> und <td>, einschließlich geschachtelter Tabellen<table>, <tr> and <td>, including nested tables

  • <pre> für vorformatierten Text (behält Leerräume und Zeilenumbrüche bei)<pre> for preformatted text (preserves white space and line breaks)

  • <b> und <i> für fette und kursive Zeichenformate<b> and <i> for bold and italic character styles

Microsoft Graph behält den semantischen Inhalt und die grundlegende Struktur der Eingabe-HTML bei der Seitenerstellung bei, konvertiert jedoch die Eingabe-HTML in die unterstützte Teilmenge von HTML und CSS.Microsoft Graph preserves the semantic content and basic structure of the input HTML when it creates pages, but it converts the input HTML to use the supported set of HTML and CSS. Features, die in OneNote nicht vorhanden sind, können nicht übersetzt werden und werden somit möglicherweise in der HTML-Quelldatei nicht erkannt.Features that don't exist in OneNote have nothing to be translated to, so they might not be recognized in the source HTML.

BeispielanforderungExample request

Dieses Beispiel einer mehrteiligen Anforderung erstellt eine Seite, die Bilder und eine eingebettete Datei enthält.This example multipart request creates a page that contains images and an embedded file. Der erforderliche Presentation-Teil enthält die Eingabe-HTML, die die Seite definiert.The required Presentation part contains the input HTML that defines the page. Der imageBlock1-Teil enthält die binären Bilddaten und fileBlock1 die Binärdateidaten.The imageBlock1 part contains the binary image data, and fileBlock1 contains the binary file data. Datenteile können auch HTML enthalten. In diesem Fall rendert Microsoft Graph den HTML-Code als Bild auf der OneNote-Seite.Data parts can also contain HTML, in which case Microsoft Graph renders the HTML as an image on the OneNote page.

POST https://graph.microsoft.com/v1.0/me/onenote/pages
Authorization: Bearer {token}
Content-Type: multipart/form-data; boundary=MyPartBoundary198374

--MyPartBoundary198374
Content-Disposition:form-data; name="Presentation"
Content-Type:text/html

<!DOCTYPE html>
<html>
  <head>
    <title>A page with rendered images and an attached file</title>
    <meta name="created" content="2015-07-22T09:00:00-08:00" />
  </head>
  <body>
    <p>Here's an image from an <i>online source</i>:</p>
    <img src="https://..." alt="an image on the page" width="500" />
    <p>Here's an image uploaded as <b>binary data</b>:</p>
    <img src="name:imageBlock1" alt="an image on the page" width="300" />
    <p>Here's a file attachment:</p>
    <object data-attachment="FileName.pdf" data="name:fileBlock1" type="application/pdf" />
  </body>
</html>

--MyPartBoundary198374
Content-Disposition:form-data; name="imageBlock1"
Content-Type:image/jpeg

... binary image data ...

--MyPartBoundary198374
Content-Disposition:form-data; name="fileBlock1"
Content-Type:application/pdf

... binary file data ...

--MyPartBoundary198374--

Weitere Beispiele für die Erstellung von Seiten, die Bilder und andere Dateien enthalten, finden Sie unter Hinzufügen von Bildern und Dateien sowie in unseren Lernprogrammen und Beispielen.For more examples that show how to create pages that contain images and other files, see Add images and files, our tutorials, and our samples. Außerdem finden Sie Informationen zum Erstellen absolut positionierter Elemente, Verwenden von Notiztags und Extrahieren von Daten für Visitenkarten und Onlinerezept- und Produktlisten.Also, learn how to create absolute positioned elements, use note tags, and extract data for business card captures and online recipe and product listings.

Microsoft Graph hat in einigen Formaten strenge Anforderungen, z. B. CRLF-Zeilenumbrüche in einem mehrteiligen Nachrichtentext.Microsoft Graph is strict about some formats, such as CRLF newlines in a multipart message body. Um das Risiko fehlerhafter Nutzlasten zu reduzieren, sollten Sie eine Bibliothek verwenden, um mehrteilige Nachrichten zu erstellen.To reduce the risk of creating malformed payloads, you should use a library to construct multipart messages.

Wenn Sie eine Statusmeldung 400 für eine fehlerhafte Nutzlast erhalten, überprüfen Sie die Formatierung der Zeilenumbrüche und Leerräume, und achten Sie auf Codierungsprobleme.If you do receive a 400 status for a malformed payload, check the formatting of newlines and whitespaces, and check for encoding issues. Versuchen Sie beispielsweise die Verwendung von charset=utf-8 (Beispiel: Content-Type: text/html; charset=utf-8).For example, try using charset=utf-8 (example: Content-Type: text/html; charset=utf-8).

Siehe Anforderungen und Einschränkungen für Eingabe-HTML und Größenbeschränkungen für POST-Anforderungen.See requirements and limitations for input HTML and size limits for POST requests.

Anforderungs- und Antwortinformationen für POST pages-AnforderungenRequest and response information for POST pages requests

AnforderungsdatenRequest data BeschreibungDescription
ProtokollProtocol Alle Anforderungen verwenden das SSL/TLS HTTPS-Protokoll.All requests use the SSL/TLS HTTPS protocol.
Header „Authorization“Authorization header

Bearer {token}, wobei {token} ein gültiges OAuth 2.0-Zugriffstoken für Ihre registrierte App ist.Bearer {token}, where {token} is a valid OAuth 2.0 access token for your registered app.

Wenn dies fehlt oder ungültig ist, schlägt die Anforderung mit dem Statuscode 401 fehl.If missing or invalid, the request fails with a 401 status code. Siehe Authentifizierung und Berechtigungen.See Authentication and permissions.

Header „Content-Type“Content-Type header

text/html oder application/xhtml+xml für den HTML-Inhalt, unabhängig davon, ob er direkt im Nachrichtentext oder im erforderlichen „Presentation“-Teil einer mehrteiligen Anforderung gesendet wird.text/html or application/xhtml+xml for the HTML content, whether it's sent directly in the message body or in the required "Presentation" part of multipart requests.

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.Multipart requests are required when sending binary data, and use the multipart/form-data; boundary=part-boundary content type, where {part-boundary} is a string that signals the start and end of each data part.

Header „Accept“Accept header application/json

AntwortdatenResponse data BeschreibungDescription
ErfolgscodeSuccess code HTTP-Statuscode 201.A 201 HTTP status code.
AntworttextResponse body Eine OData-Darstellung der neuen Seite im JSON-Format.A OData representation of the new page in JSON format.
FehlerErrors Wenn die Anforderung nicht erfüllt wird, gibt die API Fehler im **@api.diagnostics**-Objekt im Antworttext zurück.If the request fails, the API returns errors in the **@api.diagnostics** object in the response body.
Header „Location“Location header Die URL der Ressource für die neue Seite.The resource URL for the new page.
Header „X-CorrelationId“X-CorrelationId header Ein globaler Bezeichner (GUID), über den die Anforderung eindeutig identifiziert wird.A GUID that uniquely identifies the request. Sie können diesen Wert zusammen mit dem Wert des Date-Headers verwenden, um zusammen mit dem Microsoft Support Probleme zu behandeln.You can use this value along with the value of the Date header when working with Microsoft support to troubleshoot issues.

Zusammensetzen der Stamm-URL des Microsoft Graph-DienstsConstructing the Microsoft Graph service root URL

Die Stamm-URL des Microsoft Graph-Diensts verwendet das folgende Format für alle Aufrufe von Microsoft Graph:The Microsoft Graph service root URL uses the following format for all calls to Microsoft Graph:

https://graph.microsoft.com/{version}/me/onenote/

Das Segment version in der URL ist die Version von Microsoft Graph, die verwendet werden soll.The version segment in the URL represents the version of Microsoft Graph that you want to use. Verwenden Sie v1.0 für stabilen Produktionscode.Use v1.0 for stable production code. Verwenden Sie beta, um ein Feature zu testen, das sich in der Entwicklung befindet.Use beta to try out a feature that's in development. Features und Funktionen in der Betaversion ändern sich möglicherweise, sodass Sie es nicht in Ihrem Produktionscode verwenden sollten.Features and functionality in beta may change, so you shouldn't use it in your production code.

Verwenden Sie me für OneNote-Inhalt, auf den der aktuelle Benutzer zugreifen kann (eigene und freigegebene Inhalte).Use me for OneNote content that the current user can access (owned and shared). Verwenden Sie users/{id} für OneNote-Inhalte, die der (in der URL) angegebene Benutzer für den aktuellen Benutzer freigegeben hat.Use users/{id} for OneNote content that the specified user (in the URL) has shared with the current user. Verwenden Sie Microsoft Graph, um Benutzer-IDs abzurufen.Use Microsoft Graph to get user IDs.

BerechtigungenPermissions

Zum Erstellen von OneNote-Seiten müssen Sie die entsprechenden Berechtigungen anfordern.To create OneNote pages, you'll need to request appropriate permissions. Wählen Sie die niedrigste Berechtigungsstufe, die Ihre App zur Erledigung ihrer Aufgaben benötigt.Choose the lowest level of permissions that your app needs to do its work.

Wählen Sie zwischen:Choose from:

  • Notes.CreateNotes.Create
  • Notes.ReadWriteNotes.ReadWrite
  • Notes.ReadWrite.AllNotes.ReadWrite.All

Weitere Informationen zu Berechtigungsbereichen und deren Funktionsweise finden Sie in der Microsoft Graph-Berechtigungsreferenz.For more information about permission scopes and how they work, see Microsoft Graph permissions reference.

Siehe auchSee also