Enviar una invitación para uso compartidoSend a sharing invitation

Importante

Las API de /beta la versión de Microsoft Graph están sujetas a cambios.APIs under the /beta version in Microsoft Graph are subject to change. No se admite el uso de estas API en aplicaciones de producción.Use of these APIs in production applications is not supported.

Envía una invitación para uso compartido de un objeto DriveItem. Una invitación para uso compartido proporciona permisos a los destinatarios y, de forma opcional, envía un correo electrónico a los destinatarios para notificarles que se ha compartido el elemento.Sends a sharing invitation for a DriveItem. A sharing invitation provides permissions to the recipients and optionally sends an email to the recipients to notify them the item was shared.

PermisosPermissions

Se requiere uno de los siguientes permisos para llamar a esta API. Para obtener más información, incluido cómo elegir permisos, vea Permisos.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Tipo de permisoPermission type Permisos (de menos a más privilegiados)Permissions (from least to most privileged)
Delegado (cuenta profesional o educativa)Delegated (work or school account) Files.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.AllFiles.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.All
Delegado (cuenta personal de Microsoft)Delegated (personal Microsoft account) Files.ReadWrite, Files.ReadWrite.AllFiles.ReadWrite, Files.ReadWrite.All
AplicaciónApplication Files.ReadWrite.All, Sites.ReadWrite.AllFiles.ReadWrite.All, Sites.ReadWrite.All

Solicitud HTTPHTTP request

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

Cuerpo de solicitudRequest body

En el cuerpo de la solicitud, proporcione un objeto JSON con los siguientes parámetros.In the request body, provide a JSON object with the following parameters.

{
  "requireSignIn": false,
  "sendInvitation": false,
  "roles": [ "read | write"],
  "recipients": [
    { "@odata.type": "microsoft.graph.driveRecipient" },
    { "@odata.type": "microsoft.graph.driveRecipient" }
  ],
  "message": "string"
}
ParámetroParameter TipoType DescripciónDescription
destinatariosrecipients Collection(DriveRecipient)Collection(DriveRecipient) Una colección de los destinatarios que recibirán acceso y la invitación para uso compartido.A collection of recipients who will receive access and the sharing invitation.
messagemessage StringString Un mensaje con formato de texto sin formato que se incluye en la invitación para uso compartido. La longitud máxima es de 2000 caracteres.A plain text formatted message that is included in the sharing invitation. Maximum length 2000 characters.
requireSignInrequireSignIn BooleanoBoolean Especifica si el destinatario de la invitación debe iniciar sesión para ver el elemento compartido.Specifies where the recipient of the invitation is required to sign-in to view the shared item.
sendInvitationsendInvitation BooleanBoolean Especifica si se genera un correo electrónico o una publicación (false) o si se acaba de crear el permiso (true).Specifies if an email or post is generated (false) or if the permission is just created (true).
rolesroles Collection(String)Collection(String) Especifica los roles que se conceden a los destinatarios de la invitación para uso compartido.Specify the roles that are be granted to the recipients of the sharing invitation.
expirationDateTimeexpirationDateTime DateTimeOffsetDateTimeOffset Especifica la fecha y hora después de la cual expira el permiso.Specify the DateTime after which the permission expires. Disponible en OneDrive para la empresa, SharePoint y cuentas de OneDrive personales Premium.Available on OneDrive for Business, SharePoint, and premium personal OneDrive accounts.
passwordpassword StringString Contraseña que el creador ha establecido en la invitación.The password set on the invite by the creator. Opcional y solo OneDrive personalOptional and OneDrive Personal only

EjemploExample

Este ejemplo envía una invitación para uso compartido a un usuario con la dirección de correo electrónico "ryan@contoso.org" y un mensaje sobre un archivo en el que se colabora.This example sends a sharing invitation to a user with email address "ryan@contoso.org" with a message about a file being collaborated on. La invitación concede a Ryan acceso de lectura y escritura al archivo.The invitation grants Ryan read-write access to the file.

Solicitud HTTPHTTP request

Si se ejecuta correctamente, este método devuelve el código de respuesta 200 OK y el objeto de colección permission en el cuerpo de la respuesta.If successful, this method returns 200 OK response code and permission collection object in the response body.

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

{
  "recipients": [
    {
      "email": "ryan@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"
}

RespuestaResponse

Aquí tiene un ejemplo de la respuesta.Here is an example of the response.

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

{
  "value": [
    {
      "grantedTo": {
        "user": {
          "displayName": "Ryan Gregg",
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20"
        }
      },
      "hasPassword": true,
      "id": "CCFC7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "ryan@contoso.com",
        "signInRequired": true
      },
      "roles": [ "write" ],
      "expirationDateTime": "2018-07-15T14:00:00.000Z"
    }
  ]
}

Respuesta parcialmente correctaPartial success response

Al invitar a varios destinatarios, es posible que la notificación se realice correctamente para otros errores.When inviting multiple recipients, it's possible for the notification to succeed for some and fail for others. En este caso, el servicio devuelve una respuesta de éxito parcial con un código de Estado HTTP de 207.In this case, the service returns a partial success response with an HTTP status code of 207. Cuando se devuelve el resultado parcial, la respuesta de cada destinatario que ha producido error un error contendrá un objeto con información sobre el problema y cómo solucionarlo.When partial success is returned, the response for each failed recipient will contain an error object with information about what went wrong and how to fix it.

Este es un ejemplo de la respuesta parcial.Here is an example of the partial response.

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

{
  "value": [
    {
      "grantedTo": {
        "user": {
          "displayName": "John Adams",
          "id": "5D8CA5D0-FFF8-4A97-B0A6-8F5AEA339681"
        }
      },
      "id": "1EFG7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "adams@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": "Ryan Gregg",
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20"
        }
      },
      "id": "CCFC7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "ryan@contoso.com",
        "signInRequired": true
      },
      "roles": [ "write" ],
      "expirationDateTime": "2018-07-15T14:00:00.000Z"
    }
  ]
}

Errores de SendNotificationSendNotification errors

Los siguientes son algunos errores adicionales que la aplicación puede encontrarse dentro de innererror los objetos anidados cuando se produce un error al enviar la notificación.The following are some additional errors that your app might encounter within the nested innererror objects when sending notification fails. No es necesario que las aplicaciones controlen estos.Apps are not required to handle these.

CódigoCode DescripciónDescription
accountVerificationRequiredaccountVerificationRequired La comprobación de la cuenta es necesaria para desbloquear el envío de notificaciones.Account verification is required to unblock sending notifications.
hipCheckRequiredhipCheckRequired Debe resolver la comprobación de la HIP (prevención de intrusiones en el host) para desbloquear el envío de notificaciones.Need to solve HIP (Host Intrusion Prevention) check to unblock sending notifications.
exchangeInvalidUserexchangeInvalidUser No se encontró el buzón del usuario actual.Current user's mailbox was not found.
exchangeOutOfMailboxQuotaexchangeOutOfMailboxQuota Sin cuota.Out of quota.
exchangeMaxRecipientsexchangeMaxRecipients Se ha superado el número máximo de destinatarios a los que se pueden enviar notificaciones al mismo tiempo.Exceeded maximum number of recipients that can be sent notifications at the same time.

Nota: El servicio puede agregar nuevos códigos de error o dejar de devolver los antiguos en cualquier momento.Note: The service can add new error codes or stop returning old ones at any time.

ComentariosRemarks

  • Los objetos Drives con un valor driveType de personal (OneDrive Personal) no pueden crear ni modificar permisos en el objeto DriveItem raíz.Drives with a driveType of personal (OneDrive personal) cannot create or modify permissions on the root DriveItem.
  • Para obtener una lista de los roles disponibles, consulte Enumeración de roles.For a list of available roles, see Roles enumeration.

Respuestas de errorError responses

Lea el tema Respuestas de error para obtener más información sobre la manera en que se devuelven los errores.Read the Error Responses topic for more information about how errors are returned.