发送共享邀请

命名空间：microsoft.graph

发送 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/{drive-id}/items/{item-id}/invite
POST /groups/{group-id}/drive/items/{item-id}/invite
POST /me/drive/items/{item-id}/invite
POST /sites/{siteId}/drive/items/{itemId}/invite
POST /users/{userId}/drive/items/{itemId}/invite

请求正文

在请求正文中，提供具有以下参数的 JSON 对象。

{
  "requireSignIn": false,
  "sendInvitation": false,
  "roles": [ "read | write"],
  "recipients": [
    { "@odata.type": "microsoft.graph.driveRecipient" },
    { "@odata.type": "microsoft.graph.driveRecipient" }
  ],
  "message": "string"
}

参数	类型	说明
recipients	Collection(DriveRecipient)	将获得访问权限和共享邀请的收件人的集合。
message	String	共享邀请中包含的纯文本格式的邮件。最大长度为 2000 个字符。
requireSignIn	Boolean	指定邀请的收件人是否需要登录才能查看共享项。
sendInvitation	Boolean	如果为 true，则向收件人发送共享链接。 否则，直接授予权限，而不发送通知。
角色	集合（字符串）	指定要授予共享邀请收件人的角色。
expirationDateTime	DateTimeOffset	指定权限过期的 DateTime。 可用于OneDrive for Business、SharePoint和高级个人OneDrive帐户。
密码	String	创建者邀请上设置的密码。 可选且OneDrive个人。

示例

此示例向电子邮件地址为 "ryan@contoso.com> 的用户发送共享邀请包含有关要协作处理的文件的消息。该邀请授予Ryan对文件的读写访问权限。

HTTP 请求

如果成功，此方法在响应正文中返回 200 OK 响应代码和 permission 集合对象。

HTTP

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

{
  "recipients": [
    {
      "email": "ryan@contoso.com"
    }
  ],
  "message": "Here's the file that we're collaborating on.",
  "requireSignIn": true,
  "sendInvitation": true,
  "roles": [ "write" ],
  "password": "password123",
  "expirationDateTime": "2018-07-15T14:00:00.000Z"
}

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var recipients = new List<DriveRecipient>()
{
    new DriveRecipient
    {
        Email = "ryan@contoso.com"
    }
};

var message = "Here's the file that we're collaborating on.";

var requireSignIn = true;

var sendInvitation = true;

var roles = new List<String>()
{
    "write"
};

var password = "password123";

var expirationDateTime = "2018-07-15T14:00:00Z";

await graphClient.Me.Drive.Items["{driveItem-id}"]
    .Invite(recipients,requireSignIn,roles,sendInvitation,message,null,expirationDateTime,password)
    .Request()
    .PostAsync();

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

JavaScript

const options = {
    authProvider,
};

const client = Client.init(options);

const permission = {
  recipients: [
    {
      email: 'ryan@contoso.com'
    }
  ],
  message: 'Here\'s the file that we\'re collaborating on.',
  requireSignIn: true,
  sendInvitation: true,
  roles: [ 'write' ],
  password: 'password123',
  expirationDateTime: '2018-07-15T14:00:00.000Z'
};

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

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

Objective-C

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}/invite"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

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

NSMutableArray *recipientsList = [[NSMutableArray alloc] init];
MSGraphDriveRecipient *recipients = [[MSGraphDriveRecipient alloc] init];
[recipients setEmail:@"ryan@contoso.com"];
[recipientsList addObject: recipients];
payloadDictionary[@"recipients"] = recipientsList;

NSString *message = @"Here's the file that we're collaborating on.";
payloadDictionary[@"message"] = message;

BOOL requireSignIn = YES;
payloadDictionary[@"requireSignIn"] = requireSignIn;

BOOL sendInvitation = YES;
payloadDictionary[@"sendInvitation"] = sendInvitation;

NSMutableArray *rolesList = [[NSMutableArray alloc] init];
[rolesList addObject: @"write"];
payloadDictionary[@"roles"] = rolesList;

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

NSString *expirationDateTimeDateTimeString = @"07/15/2018 14:00:00";
NSDate *expirationDateTime = [NSDate ms_dateFromString: expirationDateTimeDateTimeString];
payloadDictionary[@"expirationDateTime"] = expirationDateTime;

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];

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

Java

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

LinkedList<DriveRecipient> recipientsList = new LinkedList<DriveRecipient>();
DriveRecipient recipients = new DriveRecipient();
recipients.email = "ryan@contoso.com";

recipientsList.add(recipients);

String message = "Here's the file that we're collaborating on.";

Boolean requireSignIn = true;

Boolean sendInvitation = true;

LinkedList<String> rolesList = new LinkedList<String>();
rolesList.add("write");

String password = "password123";

String expirationDateTime = "07/15/2018 14:00:00";

graphClient.me().drive().items("{item-id}")
    .invite(DriveItemInviteParameterSet
        .newBuilder()
        .withRequireSignIn(requireSignIn)
        .withRoles(rolesList)
        .withSendInvitation(sendInvitation)
        .withMessage(message)
        .withRecipients(recipientsList)
        .withRetainInheritedPermissions(null)
        .withExpirationDateTime(expirationDateTime)
        .withPassword(password)
        .build())
    .buildRequest()
    .post();

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

响应

下面是一个响应示例。

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

{
  "value": [
    {
      "@deprecated.GrantedTo": "GrantedTo has been deprecated. Refer to GrantedToV2",
      "grantedTo": {
        "user": {
          "displayName": "Robin Danielsen",
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20"
        }
      },
      "grantedToV2": {
        "user": {
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20",
          "displayName": "Robin Danielsen"
        },
        "siteUser": {
          "id": "1",
          "displayName": "Robin Danielsen",
          "loginName": "Robin Danielsen"
        }
      },
      "hasPassword": true,
      "id": "CCFC7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "robin@contoso.com",
        "signInRequired": true
      },
      "roles": [ "write" ],
      "expirationDateTime": "2018-07-15T14:00:00.000Z"
    }
  ]
}

备注

• driveType 为 personal 的 Drives（OneDrive 个人版）无法创建或修改根 DriveItem 上的权限。
• 有关可用角色的列表，请参阅 roles 属性值。

错误响应

请阅读 错误响应 主题，了解有关如何返回错误的详细信息。