Kopieren von Notizbüchern, Abschnitten und Seiten

  • Artikel

Gilt für: Unternehmens-Notizbücher auf Office 365

Um ein OneNote-Notizbuch, einen Abschnitt oder eine Seite zu kopieren, senden Sie eine POST-Anfrage an den entsprechenden Kopieren-Aktionsendpunkt. Beispiel:

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

Senden Sie ein JSON-Kopierobjekt im Nachrichtentext. Wenn die Anfrage erfolgreich war, gibt die OneNote-API einen 202 HTTP-Statuscode und einen Operation-Location -Header zurück. Anschließend können Sie den Operationsendpunkt für das Ergebnis abfragen.

Hinweis

Die Kopierfunktionalität wird für Office 365 für persönliche, für Standort- und einheitliche Gruppen-Notizbücher unterstützt, nicht jedoch für Consumer-Notizbücher auf OneDrive.

Zusammensetzen des Anforderungs-URI

  1. Um die URI-Anforderung zu erstellen, beginnen Sie mit der Stamm-Dienst-URL für Ihre Plattform:

    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/

  2. Fügen Sie dann den entsprechenden Kopieren-Aktionsendpunkt hinzu:

    Kopieren einer Seite in einen Abschnitt

    ../pages/{id}/copyToSection

    Kopieren eines Abschnitts in ein Notizbuch

    ../sections/{id}/copyToNotebook

    Kopieren eines Abschnitts in eine Abschnittsgruppe

    ../sections/{id}/copyToSectionGroup

    Ein Notizbuch kopieren

    ../notebooks/{id}/copyNotebook

Das Notizbuch wird in den Ordner "Notizbücher" in der Zielbibliothek "Dokumente" kopiert. Der Ordner "Notizbücher" wird erstellt, wenn er nicht existiert.

Ihr vollständiger Anforderungs-URI gleicht einem der folgenden Beispiele:

https://www.onenote.com/api/v1.0/me/notes/sections/{id}/copyToNotebook

https://www.onenote.com/api/v1.0/users/{id}/notes/sections/{id}/copytosectiongroup

https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/pages/{id}/copyToSection

https://www.onenote.com/api/v1.0/groups/{id}/notes/notebooks/{id}/copyNotebook

Hinweis

Weitere Informationen zur Stamm-URL des Service finden Sie unter diesem Link.

Erstellen des Anforderungstexts

Senden Sie im Nachrichtentext ein JSON-Objekt, das die Parameter enthält, die Ihre Operation benötigt. Es ist in Ordnung, einen leeren Text zu senden, wenn keine Parameter benötigt werden.

Parameter Beschreibung
ID Die ID des Ziel-Notizbuchs oder der Sektionsgruppe (für Sektionen); oder die ID des Zielabschnitts (für Seiten).

Wird nur mit copyToNotebook, copyToSectionGroupund copyToSection verwendet.
siteSammlungId Die ID der SharePoint-Websitesammlung, die die Site enthält, in die das Element kopiert werden soll.

Wird mit siteIdverwendet und nur beim Kopieren auf eine SharePoint-Site.
siteId Die ID der SharePoint-Website, auf die das Element kopiert werden soll.

Wird mit siteIdverwendet und nur beim Kopieren auf eine SharePoint-Site.
groupId Die ID der Gruppe, in die das Element kopiert werden soll.

Wird nur beim Kopieren in eine einheitliche Gruppe verwendet.
renameAs Der Name der Kopie.

Wird nur mit copyNotebook, copyToNotebookund copyToSectionGroup verwendet. Standardmäßig wird der Name des vorhandenen Elements verwendet.

Lernen Sie, wie man Notizbücher, Sektionsgruppen und Sektions-IDs und Websitesammlung und Site-IDs anfordert. Informationen zum Abrufen von Gruppen-IDs finden Sie in der Azure AD Graph API-Dokumentation.

Beispiel für den Ablauf eines Kopiervorgangs

Zuerst senden Sie eine POST-Anfrage an die Aktion copy auf das zu kopierende Objekt. Sie können von Notizbüchern kopieren, auf die der Benutzer Zugriff hat (als Besitzer oder als Freigabe), solange sich Quelle und Ziel im selben Mandanten befinden.

Das folgende Beispiel kopiert ein persönliches Notizbuch auf eine SharePoint-Teamseite. Die Anfrage enthält nicht den Parameter renameAs, sodass das neue Notizbuch den vorhandenen Namen verwendet.

POST https://www.onenote.com/api/v1.0/me/notes/notebooks/1-db247796-f4d1-4972-a869-942919bf9923/copyNotebook
Authorization: Bearer {token}
Content-Type: application/json 

{
  "siteCollectionId":"0f6dbd5d-d179-49c6-aabd-15830ea90ca8",
  "siteId":"3ba679cf-4470-466e-bc20-053bdfec75bf"
}

Hinweis

Kopiervorgänge berücksichtigen die Berechtigungen der Quell-Notizbücher, sodass der authentifizierte Benutzer in der Lage sein muss, auf das Quell-Notizbuch zuzugreifen, um es zu kopieren. Kopien behalten jedoch nicht die Rechte der Quelle. Die Kopie hat Berechtigungen, als ob der Benutzer sie gerade erstellt hätte.

Wenn die Anfrage erfolgreich war, gibt die OneNote-API einen 202 HTTP-Statuscode und einen Operation-Location -Header zurück. Hier ist ein Auszug aus der Antwort:

HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/notebooks/1-db247796-f4d1-4972-a869-942919bf9923
X-CorrelationId: 8a211d7c-220b-413d-8022-9a946499fcfb
Operation-Location: https://www.onenote.com/api/beta/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/notes/operations/copy-8a211d7c-220b-413d-8022-9a946499fcfb
...

Dann fragen Sie den Operation-Location-Endpunkt ab, um den Status des Kopiervorgangs zu erhalten:

GET https://www.onenote.com/api/beta/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/notes/operations/copy-8a211d7c-220b-413d-8022-9a946499fcfb
Authorization: Bearer {token}
Accept: application/json

Die OneNote-API gibt ein OperationModel-Objekt zurück, das den aktuellen Status anzeigt. Die folgende Beispielantwort wird zurückgegeben, wenn der Status abgeschlossen ist.

{
  "@odata.context":"https://www.onenote.com/api/beta/$metadata#myOrganization/siteCollections('0f6dbd5d-d179-49c6-aabd-15830ea90ca8')/sites('0f6dbd5d-d179-49c6-aabd-15830ea90ca8')/notes/operations/$entity",
  "id":"copy-1c5be75c-e7db-4219-8145-a2d6c3f171a33ec9f3da-2b24-4fb1-a776-fe8c8cd1410f",
  "status":"completed",
  "createdDateTime":"2015-09-16T17:32:07.048Z",
  "lastActionDateTime":"2015-09-16T17:32:17.7777639Z",
  "resourceLocation":"https://www.onenote.com/api/v1.0/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/3ba679cf-4470-466e-bc20-053bdfec75bf/notes/notebooks/1-bde29eeb-66e2-4fed-8d48-51cd1bf32511",
  "resourceId":null,"
  "error":null
}

Der Status kann abgeschlossen, wird ausgeführt, oder fehlerhaftsein.

  • Wenn abgeschlossen, enthält die Eigenschaft resourceLocation den Ressourcenendpunkt für die neue Kopie.
  • Wenn wird ausgeführt, zeigt die Eigenschaft percentComplete den ungefähr abgeschlossenen Prozentsatz an.
  • Wenn fehlerhaft, liefern die Eigenschaften fehler und @api.diagnostics -Fehlerinformationen.

Sie können den Operationsendpunkt abfragen, bis die Operation abgeschlossen oder fehlgeschlagen ist.

Anforderungs- and Antwortinformationen

Anforderungsdaten 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 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
Header „Accept“ application/json


Antwortdaten Beschreibung
Erfolgscode Ein 202-Status-HTTP-Statuscode.
Operation-Location-Header Die URL, die nach dem Status der Operation abgefragt werden soll.

Das Abfragen des Operationsendpunkts liefert ein OperationModel-Objekt, das den Status der Operation und andere Informationen enthält.
Header „X-CorrelationId“ Ein globaler Bezeichner (GUID), über den die Anforderung eindeutig identifiziert wird. Sie können diesen Wert zusammen mit dem Wert des Date-Headers verwenden, um zusammen mit dem Microsoft Support Probleme zu behandeln.

Erstellen Sie die OneNote-Stamm-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 es nicht in Ihrem Produktionscode verwenden sollten.

Das location Segment in der URL steht für den Aufenthaltsort der Notizbücher, auf die Sie zugreifen möchten:

  • 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 der 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.

  • Vereinheitlichte Gruppen-Notebooks

    • Einheitliche Gruppen (auch als Office 365-Gruppenbezeichnet) sind Bestandteil 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. Einheitliche Gruppen 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.

Beispielanforderung

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-Services 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

Um OneNote-Notizbücher, Abschnitte und Seiten zu kopieren, müssen Sie entsprechende Berechtigungen anfordern. Wählen Sie die unterste Ebene an Berechtigungen aus, die Ihre App für ihre Arbeit benötigt.

Plattform Berechtigungsbereich
Verbraucher office.onenote_create, office.onenote_update_by_app, office.onenote_update
Unternehmen Notes.Create, Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, Notes.ReadWrite.All

Weitere Informationen zu Berechtigungsbereichen und deren Funktionsweise finden Sie im Artikel zum Thema OneNote-Berechtigungsbereiche.

Siehe auch