使用链接共享文件 - Microsoft Graph v1.0

项目
09/13/2021

命名空间：microsoft.graph

可以使用 createLink 操作通过共享链接共享 DriveItem。

如果调用应用程序指定的链接类型尚不存在，CreateLink 操作将创建新的共享链接。如果应用程序指定的共享链接类型已存在，则返回现有的共享链接。

DriveItem 资源从其上级继承共享权限。

权限

要调用此 API，需要以下权限之一。要了解详细信息，包括如何选择权限的信息，请参阅权限。

权限类型	权限（从最低特权到最高特权）
委派（工作或学校帐户）	Files.ReadWrite、Files.ReadWrite.All、Sites.ReadWrite.All
委派（个人 Microsoft 帐户）	Files.ReadWrite、Files.ReadWrite.All
应用程序	Files.ReadWrite.All、Sites.ReadWrite.All

HTTP 请求

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

请求正文

请求正文定义应用程序正在请求的共享链接的属性。请求应为具有以下属性的 JSON 对象。

名称	类型	说明
类型	string	要创建的共享链接的类型。`view`、`edit` 或 `embed`。
password	string	创建者设置的共享链接的密码。可选且OneDrive个人。
expirationDateTime	string	DateTime 格式为 yyyy-MM-ddTHH：mm：ssZ 的 String 表示权限的过期时间。
scope	string	可选。要创建的链接的范围。 `anonymous` 或 `organization`。

链接类型

type 参数允许使用以下值：

类型值	说明
`view`	创建到 DriveItem 的只读链接。
`edit`	创建到 DriveItem 的读写链接。
`embed`	创建到 DriveItem 的可嵌入链接。此选项仅适用于 OneDrive 个人版中的文件。

范围类型

scope 参数允许使用以下值。如果未指定 scope 参数，则为组织创建默认的链接类型。

值	说明
`anonymous`	拥有该链接的任何人都可以访问，无需登录。这可能包括组织外部的人员。管理员可能会禁用匿名链接支持。
`organization`	登录到组织（租户）的任何人都可以使用该链接获取访问权限。仅适用于 OneDrive for Business 和 SharePoint。

响应

如果成功，此方法将在响应正文中返回单个 Permission 资源，此响应正文表示请求的共享权限。

如果已经为此项目创建新的共享链接，则响应为 201 Created；如果返回现有链接，则为 200 OK。

示例

下面的示例请求为在用户的 OneDrive 中按 {itemId} 指定的 DriveItem 创建共享链接。共享链接配置为只读并且可由具有该链接的任何用户使用。

请求

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

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


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var type = "view";

var password = "ThisIsMyPrivatePassword";

var scope = "anonymous";

await graphClient.Me.Drive.Items["{driveItem-id}"]
    .CreateLink(type,scope,null,password,null,null)
    .Request()
    .PostAsync();


const options = {
    authProvider,
};

const client = Client.init(options);

const permission = {
  type: 'view',
  password: 'ThisIsMyPrivatePassword',
  scope: 'anonymous'
};

await client.api('/me/drive/items/{item-id}/createLink')
    .post(permission);


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/drive/items/{item-id}/createLink"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

NSMutableDictionary *payloadDictionary = [[NSMutableDictionary alloc] init];

NSString *type = @"view";
payloadDictionary[@"type"] = type;

NSString *password = @"ThisIsMyPrivatePassword";
payloadDictionary[@"password"] = password;

NSString *scope = @"anonymous";
payloadDictionary[@"scope"] = scope;

NSData *data = [NSJSONSerialization dataWithJSONObject:payloadDictionary options:kNilOptions error:&error];
[urlRequest setHTTPBody:data];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        //Request Completed

}];

[meDataTask execute];


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

String type = "view";

String password = "ThisIsMyPrivatePassword";

String scope = "anonymous";

graphClient.me().drive().items("{item-id}")
    .createLink(DriveItemCreateLinkParameterSet
        .newBuilder()
        .withType(type)
        .withScope(scope)
        .withExpirationDateTime(null)
        .withPassword(password)
        .withMessage(null)
        .withRetainInheritedPermissions(null)
        .build())
    .buildRequest()
    .post();

响应

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 和 SharePoint 都支持公司可共享的链接。此类链接与匿名链接类似，只不过仅适用于拥有组织的成员。若要创建公司可共享的链接，请使用值为 organization 的 scope 参数。

请求

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

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


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var type = "edit";

var scope = "organization";

await graphClient.Me.Drive.Items["{driveItem-id}"]
    .CreateLink(type,scope,null,null,null,null)
    .Request()
    .PostAsync();


const options = {
    authProvider,
};

const client = Client.init(options);

const permission = {
  type: 'edit',
  scope: 'organization'
};

await client.api('/me/drive/items/{item-id}/createLink')
    .post(permission);


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/drive/items/{item-id}/createLink"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

NSMutableDictionary *payloadDictionary = [[NSMutableDictionary alloc] init];

NSString *type = @"edit";
payloadDictionary[@"type"] = type;

NSString *scope = @"organization";
payloadDictionary[@"scope"] = scope;

NSData *data = [NSJSONSerialization dataWithJSONObject:payloadDictionary options:kNilOptions error:&error];
[urlRequest setHTTPBody:data];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        //Request Completed

}];

[meDataTask execute];


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

String type = "edit";

String scope = "organization";

graphClient.me().drive().items("{item-id}")
    .createLink(DriveItemCreateLinkParameterSet
        .newBuilder()
        .withType(type)
        .withScope(scope)
        .withExpirationDateTime(null)
        .withPassword(null)
        .withMessage(null)
        .withRetainInheritedPermissions(null)
        .build())
    .buildRequest()
    .post();

响应

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

创建可嵌入的链接

使用 embed 链接类型时，可以在 <iframe> HTML 元素中嵌入返回的 webUrl。创建嵌入链接时，webHtml 属性包含 <iframe> 的 HTML 代码以托管内容。

注意： 仅 OneDrive 个人版支持嵌入链接。

请求

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

{
  "type": "embed"
}


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var type = "embed";

await graphClient.Me.Drive.Items["{driveItem-id}"]
    .CreateLink(type,null,null,null,null,null)
    .Request()
    .PostAsync();


const options = {
    authProvider,
};

const client = Client.init(options);

const permission = {
  type: 'embed'
};

await client.api('/me/drive/items/{item-id}/createLink')
    .post(permission);


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/drive/items/{item-id}/createLink"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

NSMutableDictionary *payloadDictionary = [[NSMutableDictionary alloc] init];

NSString *type = @"embed";
payloadDictionary[@"type"] = type;

NSData *data = [NSJSONSerialization dataWithJSONObject:payloadDictionary options:kNilOptions error:&error];
[urlRequest setHTTPBody:data];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        //Request Completed

}];

[meDataTask execute];


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

String type = "embed";

graphClient.me().drive().items("{item-id}")
    .createLink(DriveItemCreateLinkParameterSet
        .newBuilder()
        .withType(type)
        .withScope(null)
        .withExpirationDateTime(null)
        .withPassword(null)
        .withMessage(null)
        .withRetainInheritedPermissions(null)
        .build())
    .buildRequest()
    .post();

响应

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://onedrive.live.com/...",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  }
}

注解

使用此操作创建的链接不会过期，除非对组织强制执行了默认过期策略。
链接在项的共享权限中可见，可以由该项的所有者删除。
除非项已被签出，否则链接始终指向该项的最新版本（仅限 SharePoint）。

为 DriveItem 创建共享链接

此页面有帮助吗?

权限