Отправка приглашения к совместному использованию

  • Статья

Пространство имен: microsoft.graph

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

Отправляет приглашение на общий доступ для элемента driveItem. Приглашение к совместному использованию предоставляет получателям разрешения и при необходимости отправляет им на электронную почту уведомления, что к элементу был предоставлен общий доступ.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба Правительство США L4 Правительство США L5 (DOD) Китай управляется 21Vianet
✅ ✅ ✅ ✅

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения Разрешения с наименьшими привилегиями Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись) Files.ReadWrite Files.ReadWrite.All, Sites.ReadWrite.All
Делегированные (личная учетная запись Майкрософт) 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).
roles Collection(String) Указывает роли, предоставляемые получателям приглашения на общий доступ.
expirationDateTime DateTimeOffset Указывает дату и время, по истечении которого истекает срок действия разрешения. Для OneDrive для бизнеса и SharePoint xpirationDateTime применяется только для разрешений sharingLink. Доступно для OneDrive для бизнеса, SharePoint и личных учетных записей OneDrive уровня "Премиум".
password Строка Пароль, заданный в приглашении создателем. Необязательный и только OneDrive Personal
retainInheritedPermissions Boolean Необязательное свойство. Если true (по умолчанию) все существующие унаследованные разрешения сохраняются для общего элемента при первом предоставлении общего доступа к этому элементу. Если falseзадано значение , все существующие разрешения удаляются при первом предоставлении общего доступа.

Пример

В этом примере пользователю отправляется приглашение на общий доступ с адресом электронной почты "ryan@contoso.org" с сообщением о совместном использовании файла. Приглашение предоставляет пользователю Ryan доступ для чтения и записи к файлу.

HTTP-запрос

При успешном выполнении этот метод возвращает код ответа 200 OK и объект коллекции permission в теле ответа.

POST https://graph.microsoft.com/beta/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"
}

Отклик

Ниже показан пример отклика.

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 Превышено максимальное число получателей, которым можно одновременно отправлять уведомления.

Примечание: Служба может добавить новые коды ошибок или прекратить возврат старых в любое время.

Замечания

  • Диски с типом driveTypepersonal (oneDrive personal) не могут создавать или изменять разрешения на корневой элемент DriveItem.
  • Список доступных ролей см. в разделе Значения свойств ролей.

Ответы с ошибками

Дополнительные сведения о том, как возвращаются ошибки, см. в разделе Ответы на ошибки.