Freigabelink für ein DriveItem erstellenCreate a sharing link for a DriveItem

Wichtig

APIs unter der /beta Version in Microsoft Graph können Änderungen unterworfen werden.APIs under the /beta version in Microsoft Graph are subject to change. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt.Use of these APIs in production applications is not supported.

Sie können die Aktion createLink verwenden, um ein DriveItem über einen Freigabelink freizugeben.You can use createLink action to share a DriveItem via a sharing link.

Die Aktion createLink erstellt einen neuen Freigabelink, falls der angegebene Linktyp für die aufrufende Anwendung noch nicht existiert. Existiert für die App bereits ein Freigabelink des angegebenen Typs, wird dieser bereits vorhandene Freigabelink zurückgegeben.The createLink action will create a new sharing link if the specified link type doesn't already exist for the calling application. If a sharing link of the specified type already exists for the app, the existing sharing link will be returned.

DriveItem-Ressourcen erben Freigabe-Berechtigungen von ihren Vorgängern.DriveItem resources inherit sharing permissions from their ancestors.

BerechtigungenPermissions

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie im Artikel zum Thema Berechtigungen.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

BerechtigungstypPermission type Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)Permissions (from least to most privileged)
Delegiert (Geschäfts-, Schul- oder Unikonto)Delegated (work or school account) Files.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.AllFiles.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.All
Delegiert (persönliches Microsoft-Konto)Delegated (personal Microsoft account) Files.ReadWrite, Files.ReadWrite.AllFiles.ReadWrite, Files.ReadWrite.All
AnwendungApplication Files.ReadWrite.All, Sites.ReadWrite.AllFiles.ReadWrite.All, Sites.ReadWrite.All

HTTP-AnforderungHTTP request

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

AnforderungstextRequest body

Der Anforderungstext definiert die Eigenschaften des Freigabelinks, den Ihre Anwendung anfordert.The body of the request defines properties of the sharing link your application is requesting. Bei der Anforderung sollte es sich um ein JSON-Objekt mit folgenden Eigenschaften handeln:The request should be a JSON object with the following properties.

EigenschaftProperty TypType BeschreibungDescription
typetype stringstring Der Typ Freigabelink, der erstellt werden soll.The type of sharing link to create. Entweder anzeigen, bearbeiten oder einbetten.Either view, edit, or embed.
passwordpassword stringstring Das Kennwort des Freigabelinks, das vom Ersteller festgelegt wird.The password of the sharing link that is set by the creator. Optional und OneDrive nur persönlich.Optional and OneDrive Personal only.
expirationDateTimeexpirationDateTime stringstring Eine Zeichenfolge mit dem Format yyyy-mm-ddThh: mm: SSZ von DateTime gibt die Ablaufzeit der Berechtigung an.A String with format of yyyy-MM-ddTHH:mm:ssZ of DateTime indicates the expiration time of the permission.
scopescope stringstring Optional.Optional. Der Bereich des zu erstellenden Links.The scope of link to create. Entweder anonym oder Organisation.Either anonymous or organization.

Für den Parameter type sind die folgenden Werte zulässig:The following values are allowed for the type parameter.

TypwertType value BeschreibungDescription
Ansichtview Erstellt einen schreibgeschützten Link zum DriveItem.Creates a read-only link to the DriveItem.
Bearbeitenedit Erstellt einen Link mit Lese-/Schreibzugriff zum DriveItem.Creates a read-write link to the DriveItem.
Einbindenembed Erstellt einen einbettbaren Link zum DriveItem.Creates an embeddable link to the DriveItem. Diese Option ist nur für das persönliche OneDrive verfügbar.This option is only available for files in OneDrive personal.

BereichstypenScope types

Für den Parameter scope sind die nachfolgend aufgeführten Werte zulässig.The following values are allowed for the scope parameter. Wenn er scope-Parameter nicht angegeben ist, wird der Standardlinktyp für die Organisation erstellt.If the scope parameter is not specified, the default link type for the organization is created.

WertValue BeschreibungDescription
anonymeanonymous Jeder, der über die Verknüpfung verfügt, hat Zugriff, ohne dass Sie sich anmelden müssen.Anyone with the link has access, without needing to sign in. Dies kann Personen außerhalb Ihrer Organisation einschließen.This may include people outside of your organization. Die Unterstützung für anonyme Hyperlinks kann von einem Administrator deaktiviert werden.Anonymous link support may be disabled by an administrator.
Organisationorganization Jeder, der bei Ihrer Organisation (dem Mandanten) angemeldet ist, kann den Link verwenden, um Zugriff zu erhalten.Anyone signed into your organization (tenant) can use the link to get access. Nur verfügbar in OneDrive für Unternehmen und SharePoint.Only available in OneDrive for Business and SharePoint.

AntwortResponse

Bei Erfolg gibt diese Methode eine einzige Ressource des Typs Permission im Antworttext zurück. Dabei handelt es sich um die angeforderten Freigabe-Berechtigungen.If successful, this method returns a single Permission resource in the response body that represents the requested sharing permissions.

Wird ein neuer Freigabelink für das Element erstellt, lautet die Antwort 201 Created. Wird ein bereits vorhandener Link zurückgegeben, lautet die Antwort 200 OK.The response will be 201 Created if a new sharing link is created for the item or 200 OK if an existing link is returned.

BeispielExample

Im folgende Beispiel wird das Erstellen eines Freigabelinks für das DriveItem angefordert, das durch {ItemId} im OneDrive des Benutzers angegeben wurde.The following example requests a sharing link to be created for the DriveItem specified by {itemId} in the user's OneDrive. Der Freigabelink ist schreibgeschützt konfiguriert und kann von allen verwendet werden.The sharing link is configured to be read-only and usable by anyone with the link.

AnforderungRequest

POST /me/drive/items/{itemId}/createLink
Content-type: application/json

{
  "type": "view",
  "password": "ThisIsMyPrivatePassword",
  "scope": "anonymous"
}

AntwortResponse

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 freigegeben sind.OneDrive for Business and SharePoint support company sharable links. Diese ähneln anonymen Links, funktionieren aber nur für Mitglieder der Besitzorganisation.These are similar to anonymous links, except they only work for members of the owning organization. Verwenden Sie den Parameter scope mit dem Wert organization, um einen Link zu erstellen, der nur innerhalb eines Unternehmens freigegeben ist.To create a company sharable link, use the scope parameter with a value of organization.

AnforderungRequest

POST /me/drive/items/{item-id}/createLink
Content-Type: application/json

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

AntwortResponse

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. Wird ein Einbettungslink erstellt, enthält die Eigenschaft webHtml den HTML-Code für einen <iframe>, der den Inhalt hostet.When using the embed link type, the webUrl returned can be embedded in an <iframe> HTML element. When an embed link is created the webHtml property contains the HTML code for an <iframe> to host the content.

Hinweis: Einbettungslinks werden nur fürdas persönlich OneDrive unterstützt.Note: Embed links are only supported for OneDrive personal.

AnfordernRequest

POST /me/drive/items/{item-id}/createLink
Content-Type: application/json

{
  "type": "embed"
}

AntwortResponse

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

BemerkungenRemarks

  • Mit dieser Aktion erstellte Links laufen nicht ab, es sei denn, für die Organisation wird eine Standardablaufrichtlinie erzwungen.Links created using this action do not expire unless a default expiration policy is enforced for the organization.
  • Links sind in den Freigabeberechtigungen für das Element sichtbar und können von einem Besitzer des Elements entfernt werden.Links are visible in the sharing permissions for the item and can be removed by an owner of the item.
  • Links zeigen immer auf die aktuelle Version eines Elements, es sei denn, das Element ist ausgecheckt (nur SharePoint).Links always point to the current version of a item unless the item is checked out (SharePoint only).