driveItem: createLink

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.

Erstellen Sie einen Link zum Freigeben eines driveItem driveItem.

Die Aktion "Verknüpfung erstellen " erstellt einen neuen Freigabelink, wenn der angegebene Verknüpfungstyp für die aufrufende Anwendung noch nicht vorhanden ist. Wenn bereits ein Freigabelink des angegebenen Typs für die App vorhanden ist, wird der vorhandene Freigabelink zurückgegeben.

DriveItem-Ressourcen erben Berechtigungen zum Teilen von ihren Vorgängern.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Weltweiter Service US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet

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) Files.ReadWrite Files.ReadWrite.All
Anwendung Files.ReadWrite.All Sites.ReadWrite.All

Hinweis

SharePoint Embedded benötigt die FileStorageContainer.Selected Berechtigung für den Zugriff auf den Inhalt des Containers. Diese Berechtigung unterscheidet sich von den zuvor erwähnten. 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/{driveId}/items/{itemId}/createLink
POST /groups/{groupId}/drive/items/{itemId}/createLink
POST /me/drive/items/{itemId}/createLink
POST /sites/{siteId}/drive/items/{itemId}/createLink
POST /users/{userId}/drive/items/{itemId}/createLink

Anforderungsheader

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

Anforderungstext

Der Anforderungstext definiert die Eigenschaften des Links zum Teilen, den Ihre Anwendung anfordert. Bei der Anforderung sollte es sich um ein JSON-Objekt mit folgenden Eigenschaften handeln:

Eigenschaft Typ Beschreibung
Typ Zeichenfolge Optional. Der Typ Freigabelink, der erstellt werden soll.
Bereich String Optional. Der Bereich des zu erstellenden Links. Entweder anonymous, organizationoder users
expirationDateTime DateTimeOffset Optional. Eine Zeichenfolge im Format yyyy-MM-ddTHH:mm:ssZ von DateTime gibt die Ablaufzeit der Berechtigung an.
password String Optional. Der Ersteller legt das Kennwort für den Freigabelink fest.
recipients driveRecipient collection Optional. Eine Sammlung von Empfängern, die Zugriff auf den Freigabelink erhalten.
retainInheritedPermissions Boolescher Wert Optional. Wenn true (Standard), bleiben alle vorhandenen geerbten Berechtigungen für das freigegebene Element erhalten, wenn dieses Element zum ersten Mal freigegeben wird. If false, werden bei der ersten Freigabe alle vorhandenen Berechtigungen entfernt. Nicht unterstützt mit SharePoint Embedded.
sendNotification Boolean Wenn true, sendet diese Methode einen Freigabelink in einer E-Mail an Benutzer, die in angegeben sind recipients. Gilt für OneDrive for Business oder SharePoint. Der Standardwert ist false. Optional.

Für den Parameter type sind die folgenden Werte zulässig:

Typwert Beschreibung
Ansicht Erstellt einen schreibgeschützten Link zum driveItem.
Überprüfung Erstellt einen Überprüfungslink zum driveItem. Diese Option ist nur für Dateien in OneDrive for Business und SharePoint verfügbar.
Bearbeiten Erstellt einen Link mit Lese-/Schreibzugriff auf das driveItem.
einbetten Erstellt einen einbettbaren Link zum driveItem.
blocksDownload Erstellt einen schreibgeschützten Link, der den Download auf das driveItem blockiert. Diese Option ist nur für Dateien in OneDrive for Business und SharePoint verfügbar.
createOnly Erstellt einen Link nur zum Hochladen für das DriveItem. Diese Option ist nur für Ordner in OneDrive for Business und SharePoint verfügbar.
addressBar Erstellt den Standardlink, der in den Adressleisten des Browsers für neu erstellte Dateien angezeigt wird. Nur in OneDrive for Business und SharePoint verfügbar. Der Administrator der organization konfiguriert, ob dieser Linktyp unterstützt wird, und gibt die unterstützten Features an.
adminDefault Erstellt den Standardlink zum driveItem, wie vom Administrator der organization festgelegt. Nur in OneDrive for Business und SharePoint verfügbar. Der Administrator erzwingt die Richtlinie für die organization.

Bereichstypen

Für den Parameter scope sind die nachfolgend aufgeführten Werte zulässig.

Wert Beschreibung
Anonym Jeder Benutzer, der über den Link verfügt, hat Zugriff, ohne sich anmelden zu müssen. Unter Umständen befinden sich Personen außerhalb Ihrer Organization. Ein Administrator kann die Unterstützung für anonyme Links deaktivieren.
Organisation Jede Person, die bei Ihrer Organisation (Mandant) angemeldet ist, kann den Link verwenden, um Zugriff zu erhalten. Nur in OneDrive for Business und SharePoint verfügbar.
users Bestimmte Personen in der Sammlung des Empfängers können den Link verwenden, um Zugriff zu erhalten. Nur in OneDrive for Business und SharePoint verfügbar.

Antwort

Bei Erfolg gibt diese Methode eine einzige Ressource des Typs Permission im Antworttext zurück. Dabei handelt es sich um die angeforderten Berechtigungen zum Teilen.

Die Antwort lautet 201 Created , ob ein neuer Freigabelink für das driveItem erstellt wird oder 200 OK wenn ein vorhandener Link zurückgegeben wird.

Beispiele

Im folgenden Beispiel wird angefordert, dass ein Freigabelink für das driveItem erstellt wird, das von {itemId} im OneDrive des Benutzers angegeben wird. Der Link zum Teilen ist schreibgeschützt konfiguriert und kann von allen verwendet werden. Verwenden Sie für OneDrive for Business- und SharePoint-Benutzer den sendNotification Parameter, um einen Freigabelink zu erstellen. Der Freigabelink wird dann per E-Mail an die Empfänger gesendet. Alle vorhandenen Berechtigungen werden bei der ersten Freigabe entfernt, wenn retainInheritedPermissions der Wert falsch ist.

Anforderung

POST https://graph.microsoft.com/beta/me/drive/items/{itemId}/createLink
Content-Type: application/json

{
  "type": "view",
  "scope": "anonymous",
  "password": "String",
  "recipients": [
    {
      "@odata.type": "microsoft.graph.driveRecipient"
    }
  ],
  "sendNotification": true,
  "retainInheritedPermissions": false
}

Antwort

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["write"],
  "link": {
    "type": "view",
    "scope": "anonymous",
    "webUrl": "https://1drv.ms/A6913278E564460AA616C71B28AD6EB6",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  },
  "hasPassword": true
}

OneDrive for Business und SharePoint unterstützen Links, die nur innerhalb eines Unternehmens geteilt werden können. Sie ähneln anonymen Links, funktionieren aber nur für Mitglieder der besitzenden organization. Verwenden Sie den Parameter scope mit dem Wert organization, um einen Link zu erstellen, der nur innerhalb eines Unternehmens geteilt werden kann.

Anforderung

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

{
  "type": "edit",
  "scope": "organization"
}

Antwort

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["write"],
  "link": {
    "type": "edit",
    "scope": "organization",
    "webUrl": "https://contoso-my.sharepoint.com/personal/ellen_contoso_com/...",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  }
}

Bei Verwendung des Linktyps embed kann der zurückgegebene Wert für „webUrl“ in ein HTML-Element des Typs <iframe> eingebettet werden. Wenn ein Einbettungslink erstellt wird, enthält die webHtml Eigenschaft den HTML-Code für an <iframe> zum Hosten des Inhalts.

Hinweis: Einbettungslinks werden nur für das persönliche OneDrive unterstützt.

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

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

{
  "type": "embed"
}

Antwort

Das folgende Beispiel zeigt die Antwort.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["read"],
  "link": {
    "type": "embed",
    "webHtml": "<IFRAME src=\"https://onedrive.live.com/...\"></IFRAME>",
    "webUrl": "https://onedive.live.com/...",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  }
}

Hinweise

  • Um einen Link basierend auf der Standardrichtlinie der organization und den Berechtigungen des Aufrufers für das driveItem zu erstellen, lassen Sie die Parameter für den Bereich und den Typ weg.
  • Mit dieser Aktion erstellte Links laufen nur ab, wenn eine Standardablaufrichtlinie für die organization erzwungen wird.
  • Links sind in den Freigabeberechtigungen für das driveItem sichtbar und können von einem Besitzer des driveItem entfernt werden.
  • Links verweisen immer auf die aktuelle Version eines driveItems , es sei denn, das driveItem ist ausgecheckt (nur SharePoint).