driveItem: sperren

Namespace: microsoft.graph

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

Rufen Sie eine exklusive Sperre für eine Datei ab, die durch ein driveItem dargestellt wird, oder erweitern Sie eine vorhandene Sperre, die Sie bereits besitzen. Während die Sperre beibehalten wird, werden andere Benutzer daran gehindert, eine Sperre für dieselbe Datei zu erhalten. Die Sperre läuft automatisch ab, nachdem die in der Anforderung angegebene Dauer abgelaufen ist.

Hinweis

Diese API gilt nur für driveItems , die Dateien darstellen. Sperren können nicht auf Ordner oder andere nicht dateibezogene DriveItems angewendet werden. Anforderungen, die auf ein nicht dateibasiertes driveItem abzielen, werden mit 400 Bad Requestabgelehnt.

Ein einzelner Endpunkt verarbeitet sowohl den anfänglichen Abruf als auch die Aktualisierung. Der Server bestimmt basierend auf dem aktuellen Sperrstatus der Datei und der Identität des Aufrufers, welches Verhalten zutrifft. Der Aufrufer muss nicht nachverfolgen, ob er die Datei zuvor gesperrt hat, und muss keinen Sperrbezeichner verwalten.

Derzeit werden nur exklusive Sperren unterstützt.

Berechtigungen

Wählen Sie die Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Files.ReadWrite Files.ReadWrite.All, Sites.ReadWrite.All
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Anwendung Files.ReadWrite.All Sites.ReadWrite.All

Hinweis

SharePoint Embedded erfordert die FileStorageContainer.Selected Berechtigung für den Zugriff auf den Inhalt des Containers. Diese Berechtigung unterscheidet sich von den zuvor erwähnten Berechtigungen. Zusätzlich zu den Microsoft Graph-Berechtigungen muss Ihre App über die erforderlichen Containertypberechtigungen verfügen , um diese API aufzurufen. Weitere Informationen finden Sie unter SharePoint Embedded-Authentifizierung und -Autorisierung.

HTTP-Anforderung

POST /drives/{drive-id}/items/{item-id}/lock

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung.
Content-Type application/json. Erforderlich.

Anforderungstext

Geben Sie im Anforderungstext eine JSON-Darstellung der Sperrparameter an.

Eigenschaft Typ Erforderlich Beschreibung
durationMinutes Int32 Ja Sperrdauer in Minuten. Muss zwischen 1 und 30 Minuten dauern. Die Sperre läuft zum Zeitpunkt der Anforderung plus diesem Wert ab.

Der Sperrbezeichner und der Sperrtyp sind vom Server bestimmt und dürfen nicht vom Aufrufer bereitgestellt werden.

Antwort

Der Server bestimmt basierend auf dem aktuellen Sperrstatus der Datei und der Identität des Aufrufers, ob diese Anforderung eine neue Sperre abruft oder eine vorhandene aktualisiert:

Aktueller Status Anruferidentität Aktion
Die Datei ist nicht gesperrt, oder die vorhandene Sperre ist abgelaufen. Jeder Aufrufer mit Berechtigung. Rufen Sie eine neue Sperre ab.
Die Datei ist gesperrt, und der Aufrufer hält die Sperre. Derselbe Aufrufer wie der Sperrbesitzer. Aktualisieren der vorhandenen Sperre; expirationDateTime wird aktualisiert.
Die Datei wird von einem anderen Benutzer gesperrt. Unterschiedlicher Aufrufer. Gibt zurück 409 Conflict. Der Aufrufer kann eine Sperre erst abrufen, wenn die vorhandene Sperre aufgehoben wird oder abläuft.

Wenn die Methode erfolgreich verläuft, werden der 200 OK Antwortcode und eine lockInfo-Ressource im Antworttext zurückgegeben.

Diese Methode gibt die folgenden Fehlerantwortcodes zurück.

HTTP-Code Beschreibung
400 Ungültige Anforderung. Die dauerMinutes fehlt, ist nicht positiv oder überschreitet den Maximalwert von 30 Minuten. Wird auch zurückgegeben, wenn das driveItem-Ziel keine Datei ist (z. B. ein Ordner).
401 Für die Anforderung fehlen gültige Anmeldeinformationen für die Authentifizierung.
403 Der Aufrufer verfügt nicht über die Berechtigung, diese Datei zu sperren.
404 Das driveItem-Objekt wurde am angegebenen Pfad nicht gefunden.
409 Die Datei wird von einem anderen Benutzer gesperrt. Der Aufrufer muss warten, bis die vorhandene Sperre aufgehoben oder abläuft, bevor eine neue Sperre abgerufen wird.

Weitere Informationen zur Rückgabe von Fehlern finden Sie unter Fehlerantworten und Ressourcentypen für Unterschiede zwischen Microsoft Graph für Microsoft-Konten und Microsoft Graph für Geschäfts-, Schul- oder Unikonten.

Beispiele

Beispiel 1: Abrufen einer Sperre für eine entsperrte Datei

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

POST https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/lock
Content-Type: application/json

{
  "durationMinutes": 30
}

Antwort

Das folgende Beispiel zeigt die Antwort.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "lockType": "exclusive",
  "expirationDateTime": "2026-05-13T14:30:00Z",
  "createdDateTime": "2026-05-13T14:00:00Z"
}

Beispiel 2: Aktualisieren einer vorhandenen Sperre, die der Aufrufer bereits hält

Der Anforderungstext ist identisch mit dem Acquire-Fall. nur der aktuelle Status der Datei unterscheidet sich.

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

POST https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/lock
Content-Type: application/json

{
  "durationMinutes": 10
}

Antwort

Das folgende Beispiel zeigt die Antwort. Der expirationDateTime-Wert wird aktualisiert.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "lockType": "exclusive",
  "expirationDateTime": "2026-05-13T14:39:00Z",
  "createdDateTime": "2026-05-13T14:00:00Z"
}

Hinweise

  • Derzeit werden nur exklusive Sperren unterstützt. Der lockType in der Antwort ist immer exclusive.
  • Die Sperrdauer ist auf 30 Minuten pro Anforderung begrenzt. Bei längeren Haltebereichen rufen Sie diese API erneut auf, bevor die vorhandene Sperre abläuft. der Aufruf wird automatisch als Aktualisierung behandelt.
  • Die neue expirationDateTime wird als Anforderungszeit plus durationMinutes berechnet. er ersetzt den vorherigen Ablauf, anstatt ihn zu erweitern. Das Aufrufen von mit einer kürzeren Dauer als die verbleibende Zeit reduziert effektiv das Sperrfenster.
  • Die createdDateTime - und expirationDateTime-Werte werden in UTC zurückgegeben.
  • Diese API ist idempotent und wiederholungssicher: Wenn ein Netzwerkfehler den Aufrufer unsicher macht, ob die Sperre erfolgreich war, führt ein erneutes Wiederholen natürlich zu einer Aktualisierung (wenn der erste Aufruf erfolgreich war) oder zu einem neuen Abrufen (falls dies nicht der Fall war).
  • Last updated on