发送访问项目的邀请 - Microsoft Graph beta

项目
12/01/2021

命名空间：microsoft.graph

重要

Microsoft Graph版本下的 /beta API 可能会发生更改。不支持在生产应用程序中使用这些 API。若要确定 API 是否在 v1.0 中可用，请使用版本选择器。

发送 DriveItem 的共享邀请。共享邀请为收件人提供权限，也可以选择向收件人发送电子邮件以通知他们项目已共享。

Permissions

要调用此 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	指定是否生成电子邮件或帖子 (false)，或是否仅创建权限 (true)。
角色	集合（字符串）	指定授予共享邀请收件人的角色。
expirationDateTime	DateTimeOffset	指定权限过期的 DateTime。可用于OneDrive for Business、SharePoint和高级个人OneDrive帐户。
密码	String	创建者邀请上设置的密码。可选和OneDrive个人

示例

本示例向电子邮件地址为“ryan@contoso.org”的用户发送共享邀请，其中包含关于协作文件的讯息。此邀请授予 Ryan 对该文件的读写访问权限。

HTTP 请求

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

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

{
  "recipients": [
    {
      "email": "robin@contoso.org"
    }
  ],
  "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"
}


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

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

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();

重要

Microsoft Graph SDK 默认使用 v1.0 版本的 API，并且不支持 beta 版本中提供的所有类型、属性和 API。有关使用 SDK 访问 beta API 的详细信息，请参阅将 Microsoft Graph SDK 与 beta API 配合使用。

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


const options = {
    authProvider,
};

const client = Client.init(options);

const permission = {
  recipients: [
    {
      email: 'robin@contoso.org'
    }
  ],
  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')
    .version('beta')
    .post(permission);

重要

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


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/beta/";
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:@"robin@contoso.org"];
[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 文档。


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

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

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

部分成功响应

邀请多个收件人时，某些收件人的通知可能会成功，而其他收件人可能会失败。在这种情况下，该服务返回 HTTP 状态代码为 207 的部分成功响应。返回部分成功后，每个失败收件人的响应将包含一个对象，其中包含有关错误 error 及其修复方法的信息。

下面是部分响应的示例。

HTTP/1.1 207 Multi-Status
Content-type: application/json

{
  "value": [
    {
      "grantedTo": {
        "user": {
          "displayName": "Helga Hammeren",
          "id": "5D8CA5D0-FFF8-4A97-B0A6-8F5AEA339681"
        }
      },
      "id": "1EFG7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "helga@contoso.com",
        "signInRequired": true
      },
      "roles": [ "write" ],
      "error": {
        "code":"notAllowed",
        "message":"Account verification needed to unblock sending emails.",
        "localizedMessage": "Kontobestätigung erforderlich, um das Senden von E-Mails zu entsperren.",
        "fixItUrl":"http://g.live.com/8SESkydrive/VerifyAccount",
        "innererror":{  
          "code":"accountVerificationRequired" 
        }
      }
    },
    {
      "grantedTo": {
        "user": {
          "displayName": "Robin Danielsen",
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20"
        }
      },
      "id": "CCFC7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "robin@contoso.com",
        "signInRequired": true
      },
      "roles": [ "write" ],
      "expirationDateTime": "2018-07-15T14:00:00.000Z"
    }
  ]
}

SendNotification 错误

下面是应用在发送通知失败时在嵌套对象中 innererror 可能会遇到的一些其他错误。应用不需要处理它们。

代码	说明
accountVerificationRequired	需要帐户验证才能取消阻止发送通知。
hipCheckRequired	需要解决 HIP (主机入侵防护) 以取消阻止发送通知。
exchangeInvalidUser	未找到当前用户的邮箱。
exchangeOutOfMailboxQuota	配额不足。
exchangeMaxRecipients	超出了可以同时发送通知的最大收件人数。

注意： 该服务可以添加新的错误代码或随时停止返回旧的错误代码。

备注

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

错误响应

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

发送共享邀请

Permissions

HTTP 请求

请求正文

示例

HTTP 请求

响应

部分成功响应

SendNotification 错误

备注

错误响应

反馈