Berechtigungen für OneNote-Entitäten verwalten

  • Artikel

Gilt für: Unternehmensnotizbücher 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}

Hinweis

Das Verwalten von Berechtigungen wird für Office 365 für persönliche, für Standort- und einheitliche Gruppen-Notebooks unterstützt, nicht jedoch für Consumer-Notebooks 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 anschließend den Pfad zum Ziel-Notebook, zur Abschnittsgruppe oder zur Abschnitts-Entität hinzu, gefolgt vom Endpunkt permissions oder permissions/{id}.

Ihre vollständige Anfrage-URI wird ungefähr so aussehen wie in diesen Beispielen:

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}

Hinweis

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

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"
}
Parameter Beschreibung
userRole Der Typ von Berechtigung: Owner, Contributor, oder Reader.
userId Die 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|membership|username@domainname.com) oder nur den Anmeldenamen des Benutzerprinzipals (username@domainname.com) enthält.

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",
}

Anforderungs- and Antwortinformationen

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

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 mit Azure AD (Unternehmensanwendungen).
Berechtigungsbereich Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, or Notes.ReadWrite.All


Antwortdaten Beschreibung
Erfolgscode HTTP-Statuscode 201.
Antworttext Eine OData-Darstellung der Berechtigung im JSON-Format. Siehe Berechtigungen holen für eine Beschreibung eines Berechtigungsobjekts.
Fehler Wenn die Anfrage fehlschlägt, gibt die API Fehler im Antworttext zurück.
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 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]

Hinweis

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.

Eigenschaft Beschreibung
Name Der Anzeigename des Benutzers oder des Prinzipals der Gruppe. Beispiel: "name":"Everyone"
ID Die eindeutige Kennung der Berechtigung in der Form 1-{principal-member-id}. Beispiel: "id":"1-4"
self Die URL des Berechtigungsobjekts.
userId Die Anmeldung des Benutzers oder der Gruppe, der die Berechtigung zugeordnet ist. Dieser Wert wird z.B. immer im Anspruchsformat zurückgegeben: i:0#.f|membership|username@domainname.com.
userRole Der 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",
  }]
}

Anforderungs- and Antwortinformationen

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

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 mit Azure AD (Unternehmensanwendungen).
Berechtigungsbereich Notes.Read, Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, or Notes.ReadWrite.All


Antwortdaten Beschreibung
Erfolgscode Ein 200-HTTP-Statuscode und die angeforderten Berechtigungen.
Antworttext Eine OData-Darstellung der Berechtigungen im JSON-Format.
Fehler Wenn die Anfrage fehlschlägt, gibt die API Fehler im Antworttext zurück.
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 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

Anforderungs- and Antwortinformationen

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

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 mit Azure AD (Unternehmensanwendungen).
Berechtigungsbereich Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, or Notes.ReadWrite.All


Antwortdaten Beschreibung
Erfolgscode Ein 204 HTTP-Statuscode.
Fehler Wenn die Anfrage fehlschlägt, gibt die API Fehler im Antworttext zurück.
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 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.

Berechtigung Beschreibung
Reader Nur-Lesezugriff auf Notebooks, Abschnittsgruppen und Abschnitte.
Mitwirkender Kann Notebooks, Abschnittsgruppen und Abschnitte hinzufügen, bearbeiten und löschen.
Besitzer Alle 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. 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.

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

Siehe auch