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

Berechtigungen für OneNote-Entitäten verwalten

Gilt für: Enterprise Notebooks auf Office 365

Sie können den Endpunkt der Berechtigungen verwenden, um Lese- oder Schreibrechte für Notebooks, Abschnittsgruppen und Abschnitte zu verwalten.

POST ../permissions

GET ../permissions

GET ../permissions/{permission-id}

DELETE ../permissions/{permission-id}

Das Verwalten von Berechtigungen wird für Office 365 für persönliche, für Standort- und Gruppen-Notebooks unterstützt, nicht jedoch für Consumer-Notebooks auf OneDrive.

Erstellen der URI-Anforderung

Um die URI-Anforderung zu erstellen, beginnen Sie mit der Dienst-Root-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/


Fügen Sie anschließend den Pfad zum Ziel-Notebook, zur Abschnittsgruppe oder zur Abschnitts-Entität hinzu, gefolgt von den Berechtigungen oder Berechtigungen/{id} Endpunkt.

Ihre vollständige Anfrage-URI wird ungefähr so aussehen wie diese Beispiele:

https://www.onenote.com/api/v1.0/me/notes/notebooks/{id}/permissions/{id}

https://www.onenote.com/api/v1.0/users/{id}/notes/sectiongroups/{id}/permissions

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

https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/sections/{id}/permissions/{id}

Weitere Informationen zur Stamm-URL des Dienstes.

Berechtigungen erstellen oder aktualisieren

Um Berechtigungen für ein Notebook, eine Abschnittsgruppe oder einen Abschnitt zu erstellen oder zu aktualisieren, senden Sie eine POST-Anfrage an den entsprechenden Endpunkt. Sie können pro Anfrage nur eine Berechtigung erstellen oder aktualisieren.

Berechtigungen werden auf alle OneNote-Elemente entlang der Vererbungsketteangewendet.

Sie können Berechtigungen aktualisieren, um mehr Zugriffsrechte zu gewähren. Aber um den Zugriff einzuschränken, müssen Sie die bestehende Berechtigung löschen und eine neue Berechtigung anlegen. Siehe Berechtigung zu Vererbung und Vorrang.

Berechtigungen für ein Notebook erstellen oder aktualisieren

POST ../notebooks/{notebook-id}/permissions

Berechtigungen für eine Abschnittsgruppe erstellen oder aktualisieren

POST ../sectiongroups/{sectiongroup-id}/permissions

Berechtigungen für einen Abschnitt anlegen oder aktualisieren

POST ../sections/{section-id}/permissions

Senden Sie im Nachrichtentext ein JSON-Objekt mit den erforderlichen Parametern.

{
    "userRole": "user-role", 
    "userId": "user-login-id"
}
ParameterBeschreibung
userRoleDer Typ von Berechtigung: Owner, Contributor, oder Reader.
userIdDie Anmeldung des Benutzers oder der Gruppe, der die Berechtigung zugewiesen werden soll. Die API akzeptiert das Anspruchsformat, das den Namen des Mitgliedschafts-Anbieters (*i:0#.f

Beispiel

Die folgende Anfrage erzeugt eine Berechtigung für das angegebene Notebook.

Anforderung

POST ../v1.0/me/notes/notebooks/{notebook-id}/permissions
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
    "userRole": "Owner", 
    "userId": "i:0#.f|membership|alexd@domainname.com"
}

Antwort

HTTP/1.1 201 Created

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/notebooks('1-313dc828-dd55-4c71-82c3-f9c30a40e7c5')/permissions/$entity",
  "userRole":"Owner",
  "userId":"i:0#.f|membership|alexd@domainname.com",
  "name":"Alex Darrow",
  "id":"1-23",
  "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23",
}

Informationen zu Anforderung und Antwort

Die folgenden Informationen gelten für POST /permissions Anfragen.

Anfragen von DatenBeschreibung
ProtokollAlle Anfragen verwenden das SSL/TLS HTTPS-Protokoll.
Autorisierungs-Header

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 mit Azure AD (Unternehmensanwendungen).

BerechtigungsbereichNotes.ReadWrite.CreatedByApp, Notes.ReadWrite oder Notes.ReadWrite.All
AntwortdatenBeschreibung
ErfolgscodeEin 201 HTTP-Statuscode.
Text der AntwortEine OData-Darstellung der Berechtigung im JSON-Format. Siehe Berechtigungen holen für eine Beschreibung eines Berechtigungsobjekts.
FehlerWenn die Anfrage fehlschlägt, gibt die API Fehler im Antworttext zurück.
X-CorrelationId HeaderEine GUID, die die Anfrage eindeutig identifiziert. Sie können diesen Wert zusammen mit dem Wert des Datums-Headers verwenden, wenn Sie mit der Microsoft-Unterstützung arbeiten, um Probleme zu beheben.

Erhalten von Berechtigungen

Um Berechtigungen für ein Notebook, eine Abschnittsgruppe oder einen Abschnitt zu erstellen oder zu aktualisieren, senden Sie eine POST-Anfrage an den entsprechenden Endpunkt.

Berechtigungen für ein Notebook einholen

GET ../notebooks/{notebook-id}/permissions

Eine spezielle Berechtigung für ein Notebook erhalten

GET ../notebooks/{notebook-id}/permissions/{permission-id}

Berechtigungen für eine Abschnittsgruppe erhalten

GET ../sectiongroups/{sectiongroup-id}/permissions

Eine bestimmte Berechtigung für eine Abschnittsgruppe erhalten

GET ../sectiongroups/{sectiongroup-id}/permissions/{permission-id}

Berechtigungen für einen Abschnitt erhalten

GET ../sections/{section-id}/permissions

Eine spezielle Berechtigung für einen Abschnitt erhalten

GET ../sections/{section-id}/permissions/{permission-id}


GET-Anforderungen geben die höchste Berechtigung für eine Benutzerrolle auf der Ziel-Entität zurück. Weitere Informationen finden Sie unter Berechtigungs-Vererbung und Vorrang.

GET /permissions Anfragen unterstützen OData-Abfrageoptionen, wie folgt:

GET ../permissions[?filter,orderby,select,top,skip,count]

GET ../permissions/{permission-id}[?select]

Der Endpunkt Berechtigungen unterstützt die Abfrageoption expand nicht.

Weitere Informationen zum Abrufen von OneNote-Entitäten, einschließlich der unterstützten Abfrage zu Optionen der Zeichenfolge und Beispiele, finden Sie unter OneNote-Inhalt und -Struktur abrufen.

Berechtigungsobjekt

Eine Berechtigung enthält die folgenden Eigenschaften.

EigenschaftBeschreibung
NameDer Anzeigename des Benutzers oder des Prinzipals der Gruppe. Beispiel: "name":"Everyone"
IDDie eindeutige Kennung der Berechtigung in der Form 1-{principal-member-id}. Beispiel: "id":"1-4"
selfDie URL des Berechtigungsobjekts.
userIdDie Anmeldung des Benutzers oder der Gruppe, der die Berechtigung zugeordnet ist. Dieser Wert wird z.B. immer im Anspruchsformat zurückgegeben: *i:0#.f
userRoleDer Typ von Berechtigung: Owner, Contributor, oder Reader.

Beispiel

Die folgende Anfrage erhält alle Berechtigungen für das angegebene Notebook.

Anforderung

GET ../v1.0/me/notes/notebooks/{notebook-id}/permissions
Authorization: Bearer {token}
Accept: application/json

Antwort

HTTP/1.1 200

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/notebooks('1-313dc828-dd55-4c71-82c3-f9c30a40e7c5')/permissions",
  "value":[
  {
    "userRole":"Owner",
    "userId":"c:0(.s|true",
    "name":"Everyone",
    "id":"1-4",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/1-4"
  },
  {
    "userRole":"Owner",
    "userId":"c:0-.f|rolemanager|spo-grid-all-users/8461cbdd-15a6-45c8-b177-ac24f48a8bee",
    "name":"Everyone except external users",
    "id":"1-5",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-5"
  },
  {
    "userRole":"Owner",
    "userId":"i:0#.f|membership|alexd@domainname.com",
    "name":"Alex Darrow",
    "id":"1-23",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23",
  }]
}

Informationen zu Anforderung und Antwort

Die folgenden Informationen gelten für GET /permissions Anfragen.

Anfragen von DatenBeschreibung
ProtokollAlle Anfragen verwenden das SSL/TLS HTTPS-Protokoll.
Autorisierungs-Header

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 mit Azure AD (Unternehmensanwendungen).

BerechtigungsbereichNotes.ReadWrite.CreatedByApp, Notes.ReadWrite oder Notes.ReadWrite.All
AntwortdatenBeschreibung
ErfolgscodeEin 200-HTTP-Statuscode und die angeforderten Berechtigungen.
Text der AntwortEine OData-Darstellung der Berechtigungen im JSON-Format.
FehlerWenn die Anforderung fehlschlägt, gibt die API Fehler im Antworttext zurück.
X-CorrelationId HeaderEine GUID, die die Anfrage eindeutig identifiziert. Sie können diesen Wert zusammen mit dem Wert des Datums-Headers verwenden, wenn Sie mit der Microsoft-Unterstützung arbeiten, um Probleme zu beheben.

Berechtigungen löschen

Um eine Berechtigung für ein Notebook, eine Abschnittsgruppe oder einen Abschnitt zu löschen, senden Sie eine DELETE-Anfrage an den entsprechenden Endpunkt. Sie können pro Anforderung eine Berechtigung löschen.

Wenn Sie eine Berechtigung löschen, wird sie aus allen OneNote-Elementen entlang der Vererbungskettegelöscht.

Löschen einer Berechtigung für ein Notebook

DELETE ../notebooks/{notebook-id}/permissions/{permission-id}

Löschen einer Berechtigung für eine Abschnittsgruppe

DELETE ../sectiongroups/{sectiongroup-id}/permissions/{permission-id}

Löschen einer Berechtigung für einen Abschnitt

DELETE ../sections/{section-id}/permissions/{permission-id}

Beispiel

Die folgende Anfrage löscht eine Berechtigung für das angegebene Notebook.

DELETE ../v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23
Authorization: Bearer {token}
Accept: application/json

Informationen zu Anforderung und Antwort

Die folgenden Informationen gelten für DELETE /permissions Anfragen.

Anfragen von DatenBeschreibung
ProtokollAlle Anfragen verwenden das SSL/TLS HTTPS-Protokoll.
Autorisierungs-Header

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 mit Azure AD (Unternehmensanwendungen).

BerechtigungsbereichNotes.ReadWrite.CreatedByApp, Notes.ReadWrite oder Notes.ReadWrite.All
AntwortdatenBeschreibung
ErfolgscodeEin 204 HTTP-Statuscode.
FehlerWenn die Anfrage fehlschlägt, gibt die API Fehler im Antworttext zurück.
X-CorrelationId HeaderEine GUID, die die Anfrage eindeutig identifiziert. Sie können diesen Wert zusammen mit dem Wert des Datums-Headers verwenden, wenn Sie mit der Microsoft-Unterstützung arbeiten, um Probleme zu beheben.

Berechtigungen, Vererbung und Vorrang

Sie können die folgenden Berechtigungen für Notebooks, Abschnittsgruppen und Abschnitte festlegen.

BerechtigungBeschreibung
ReaderNur-Lesezugriff auf Notebooks, Abschnittsgruppen und Abschnitte.
MitwirkenderKann Notebooks, Abschnittsgruppen und Abschnitte hinzufügen, bearbeiten und löschen.
BesitzerAlle oben genannten Berechtigungen können auch verwaltet werden (holen, erstellen und löschen).

Wenn Sie Berechtigungen für OneNote-Entitäten verwalten, sollten Sie die Vererbung und den Vorrang bei der Berechtigung verstehen.

  • Vererbung. Entitäten erben die Berechtigungen ihrer Eltern. So erben Notebooks die Berechtigungen der Dokumentbibliothek, die das Notebook enthält. Und diese Berechtigungen werden wiederum an die untergeordneten Sektionsgruppen und Sektionen innerhalb des Notebooks vererbt. Wenn Sie explizite Berechtigungen für ein Notebook, eine Abschnittsgruppe oder einen Abschnitt festlegen, werden die Berechtigungen auch auf die untergeordneten Objekte übertragen.

  • Vorrang. Wenn widersprüchliche Berechtigungen auf eine OneNote-Einheit gesetzt werden, wird die höchste (permissivste) Berechtigung berücksichtigt. Benutzern und Gruppen werden möglicherweise widersprüchliche Zugriffsebenen gewährt, wenn mehrere Berechtigungen auf eine Entität angewendet werden (entweder explizit oder geerbt) oder wenn der Benutzer oder die Gruppe zu mehreren Rollen gehört.

Diese Prinzipien bestimmen, wie die OneNote-API Berechtigungen verwaltet. Zum Beispiel:

  • Wenn Sie eine Berechtigung für ein Notizbuch oder eine Abschnittsgruppe anlegen, wird die Berechtigung auf alle Kinder heruntergedrückt.

  • Wenn Sie eine Berechtigung für ein Notebook oder eine Abschnittsgruppe löschen, wird die Berechtigung für alle Kinder gelöscht.

  • Wenn Sie Berechtigungen erhalten, gibt die OneNote-API nur die höchste Berechtigung für Rollen mit widersprüchlichen Berechtigungen zurück.

  • Sie können Berechtigungen aktualisieren, um einem Benutzer oder einer Gruppe einen durchlässigeren Zugriff zu gewähren. Wenn Sie jedoch den Zugriff einschränken möchten, müssen Sie zuerst die freizügigere Berechtigung löschen und dann eine neue Berechtigung mit dem restriktiven Zugriff anlegen. Dies liegt daran, dass eine POST /permissions Anforderung tatsächlich eine Benutzerrolle an die Berechtigungssammlung für die Entität anhängt und der freizügigste Zugriff berücksichtigt wird. Mit anderen Worten, Sie können eine Leseberechtigung aktualisieren, um den Zugriff eines Mitwirkenden oder Besitzers zu haben, aber Sie können eine Mitwirkenden-Berechtigung nicht aktualisieren, um nur Leseberechtigung zu erlauben.

Aufbau der OneNote Service-Root-URL

Die Stamm-URL des OneNote-OneNote-ServiOneNote-OneNote-Services 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 einen stabilen Produktionscode.
  • Verwenden Sie beta, um ein Feature zu testen, das sich in der Entwicklung befindet. Funktionen und Funktionalität 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 Auftenhaltsort der Notebooks, 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 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-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.

Zusätzliche Ressourcen

© 2018 Microsoft