Espacio de nombres: microsoft.graph
Importante
Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.
Enviar una invitación para compartir para un elemento de unidad. Una invitación para uso compartido proporciona permisos a los destinatarios y, opcionalmente, les envía un correo electrónico para informarles de que el elemento se ha compartido.
Importante
- Los permisos no se pueden crear ni modificar en la unidad raízElemento de unidades con un tipo de unidad (
personal OneDrive para el hogar).
-
No se puede invitar a nuevos invitados con el acceso solo de aplicación. Se puede invitar a los invitados existentes mediante solicitudes solo de aplicación.
Esta API está disponible en las siguientes implementaciones en la nube nacional.
| Servicio global |
Administración pública de EE. UU. |
Gobierno de EE. UU. L5 (DOD) |
China operado por 21Vianet |
| ✅ |
✅ |
✅ |
✅ |
Permissions
Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use uno o varios permisos con privilegios más altos solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.
| Tipo de permiso |
Permisos con privilegios mínimos |
Permisos con privilegios más altos |
| Delegado (cuenta profesional o educativa) |
Files.ReadWrite |
Files.ReadWrite.All, Sites.ReadWrite.All |
| Delegado (cuenta personal de Microsoft) |
Files.ReadWrite |
Files.ReadWrite.All |
| Aplicación |
Files.ReadWrite.All |
Sites.ReadWrite.All |
Nota:
SharePoint Embedded requiere permiso FileStorageContainer.Selected para acceder al contenido del contenedor. Este permiso es diferente de los mencionados anteriormente. Además de los permisos de Microsoft Graph, la aplicación debe tener los permisos de tipo de contenedor necesarios para llamar a esta API. Para obtener más información, consulte Autenticación y autorización de SharePoint Embedded.
Solicitud 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
Cuerpo de la solicitud
En el cuerpo de la solicitud, proporcione un objeto JSON con los siguientes parámetros.
{
"requireSignIn": false,
"sendInvitation": false,
"roles": [ "read | write"],
"recipients": [
{ "@odata.type": "microsoft.graph.driveRecipient" },
{ "@odata.type": "microsoft.graph.driveRecipient" }
],
"message": "string"
}
| Parámetro |
Tipo |
Descripción |
| destinatarios |
colección driveRecipient |
Colección de destinatarios que reciben acceso y la invitación para uso compartido. |
| message |
String |
Un mensaje con formato de texto sin formato que se incluye en la invitación para uso compartido. Longitud máxima: 2000 caracteres. |
| requireSignIn |
Boolean |
Especifica si el destinatario de la invitación debe iniciar sesión para ver el elemento compartido. |
| sendInvitation |
Boolean |
Especifica si se genera un correo electrónico o una publicación (false) o si el permiso se crea recientemente (true). |
| roles |
Colección de cadenas |
Especifica los roles que se conceden a los destinatarios de la invitación de uso compartido. |
| expirationDateTime |
DateTimeOffset |
Especifica la fecha y hora después de la cual expira el permiso. Para OneDrive para el trabajo o la escuela y SharePoint, expirationDateTime solo se aplica a los permisos de sharingLink . Disponible en OneDrive para el trabajo o la escuela, SharePoint y cuentas personales premium de OneDrive. |
| password |
String |
La contraseña establecida en la invitación por el creador. Opcional y solo OneDrive para el hogar. |
| retainInheritedPermissions |
Booleano |
Opcional. Si true es (predeterminado), los permisos heredados existentes se conservan en el elemento compartido al compartir este elemento por primera vez. Si false, todos los permisos existentes se quitan al compartir por primera vez. No es compatible con SharePoint Embedded. |
Respuesta
Si tiene éxito, este método devuelve un 200 OK código de respuesta y una colección de objetos de permiso en el cuerpo de la respuesta.
Para obtener más información sobre cómo se devuelven los errores, consulte Respuestas de error.
Respuesta de éxito parcial
Al invitar a varios destinatarios, es posible que la notificación se realice correctamente para algunos y no para otros. En este caso, el servicio devuelve una respuesta satisfactoria parcial con un código de 207 Multi-Status estado. Cuando se devuelve un éxito parcial, la respuesta de cada destinatario con errores contiene un objeto de error con información sobre los errores y cómo corregirlos. Para obtener más información, vea el ejemplo 2.
Enviar errores de notificación de invitación
En la tabla siguiente se muestran algunos otros errores que la aplicación puede encontrar dentro de los objetos innererror anidados cuando se produce un error en el envío de notificaciones. Las aplicaciones no son necesarias para controlar estos errores.
| Código |
Descripción |
| accountVerificationRequired |
Se requiere la verificación de la cuenta para desbloquear el envío de notificaciones. |
| hipCheckRequired |
Necesito resolver la comprobación HIP (Host Intrusion Prevention) para desbloquear el envío de notificaciones. |
| exchangeInvalidUser |
No se encontró el buzón del usuario actual. |
| exchangeOutOfMailboxQuota |
Fuera de cuota. |
| exchangeMaxRecipients |
Se ha superado el número máximo de destinatarios a los que se pueden enviar notificaciones al mismo tiempo. |
Nota: El servicio puede agregar nuevos códigos de error o dejar de devolver los antiguos en cualquier momento.
Ejemplos
Ejemplo 1: Enviar una invitación para uso compartido
En el ejemplo siguiente se muestra cómo enviar una invitación para compartir a un usuario con la dirección robin@contoso.orgde correo electrónico , incluido un mensaje sobre un archivo en proceso de colaboración. La invitación concede a Robin acceso de lectura y escritura al archivo.
Solicitud
En el ejemplo siguiente se muestra la solicitud.
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"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Drives.Item.Items.Item.Invite;
using Microsoft.Graph.Beta.Models;
var requestBody = new InvitePostRequestBody
{
Recipients = new List<DriveRecipient>
{
new DriveRecipient
{
Email = "robin@contoso.org",
},
},
Message = "Here's the file that we're collaborating on.",
RequireSignIn = true,
SendInvitation = true,
Roles = new List<string>
{
"write",
},
Password = "password123",
ExpirationDateTime = "2018-07-15T14:00:00.000Z",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Invite.PostAsInvitePostResponseAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-beta-sdk-go/drives"
graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
//other-imports
)
requestBody := graphdrives.NewInvitePostRequestBody()
driveRecipient := graphmodels.NewDriveRecipient()
email := "robin@contoso.org"
driveRecipient.SetEmail(&email)
recipients := []graphmodels.DriveRecipientable {
driveRecipient,
}
requestBody.SetRecipients(recipients)
message := "Here's the file that we're collaborating on."
requestBody.SetMessage(&message)
requireSignIn := true
requestBody.SetRequireSignIn(&requireSignIn)
sendInvitation := true
requestBody.SetSendInvitation(&sendInvitation)
roles := []string {
"write",
}
requestBody.SetRoles(roles)
password := "password123"
requestBody.SetPassword(&password)
expirationDateTime := "2018-07-15T14:00:00.000Z"
requestBody.SetExpirationDateTime(&expirationDateTime)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
invite, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Invite().PostAsInvitePostResponse(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.beta.drives.item.items.item.invite.InvitePostRequestBody invitePostRequestBody = new com.microsoft.graph.beta.drives.item.items.item.invite.InvitePostRequestBody();
LinkedList<DriveRecipient> recipients = new LinkedList<DriveRecipient>();
DriveRecipient driveRecipient = new DriveRecipient();
driveRecipient.setEmail("robin@contoso.org");
recipients.add(driveRecipient);
invitePostRequestBody.setRecipients(recipients);
invitePostRequestBody.setMessage("Here's the file that we're collaborating on.");
invitePostRequestBody.setRequireSignIn(true);
invitePostRequestBody.setSendInvitation(true);
LinkedList<String> roles = new LinkedList<String>();
roles.add("write");
invitePostRequestBody.setRoles(roles);
invitePostRequestBody.setPassword("password123");
invitePostRequestBody.setExpirationDateTime("2018-07-15T14:00:00.000Z");
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").invite().post(invitePostRequestBody);
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);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Drives\Item\Items\Item\Invite\InvitePostRequestBody;
use Microsoft\Graph\Beta\Generated\Models\DriveRecipient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new InvitePostRequestBody();
$recipientsDriveRecipient1 = new DriveRecipient();
$recipientsDriveRecipient1->setEmail('robin@contoso.org');
$recipientsArray []= $recipientsDriveRecipient1;
$requestBody->setRecipients($recipientsArray);
$requestBody->setMessage('Here\'s the file that we\'re collaborating on.');
$requestBody->setRequireSignIn(true);
$requestBody->setSendInvitation(true);
$requestBody->setRoles(['write', ]);
$requestBody->setPassword('password123');
$requestBody->setExpirationDateTime('2018-07-15T14:00:00.000Z');
$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->invite()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Files
$params = @{
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"
}
Invoke-MgBetaInviteDriveItem -DriveId $driveId -DriveItemId $driveItemId -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.drives.item.items.item.invite.invite_post_request_body import InvitePostRequestBody
from msgraph_beta.generated.models.drive_recipient import DriveRecipient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = InvitePostRequestBody(
recipients = [
DriveRecipient(
email = "robin@contoso.org",
),
],
message = "Here's the file that we're collaborating on.",
require_sign_in = True,
send_invitation = True,
roles = [
"write",
],
password = "password123",
expiration_date_time = "2018-07-15T14:00:00.000Z",
)
result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').invite.post(request_body)
Respuesta
En el ejemplo siguiente se muestra la respuesta.
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"
}
]
}
Ejemplo 2: Enviar invitación para uso compartido con éxito parcial
En el ejemplo siguiente se muestra una solicitud que se realiza parcialmente correctamente.
Solicitud
En el ejemplo siguiente se muestra la solicitud.
POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/invite
Content-type: application/json
{
"recipients": [
{
"email": "helga@contoso.com"
},
{
"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"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Drives.Item.Items.Item.Invite;
using Microsoft.Graph.Beta.Models;
var requestBody = new InvitePostRequestBody
{
Recipients = new List<DriveRecipient>
{
new DriveRecipient
{
Email = "helga@contoso.com",
},
new DriveRecipient
{
Email = "robin@contoso.org",
},
},
Message = "Here's the file that we're collaborating on.",
RequireSignIn = true,
SendInvitation = true,
Roles = new List<string>
{
"write",
},
Password = "password123",
ExpirationDateTime = "2018-07-15T14:00:00.000Z",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Invite.PostAsInvitePostResponseAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-beta-sdk-go/drives"
graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
//other-imports
)
requestBody := graphdrives.NewInvitePostRequestBody()
driveRecipient := graphmodels.NewDriveRecipient()
email := "helga@contoso.com"
driveRecipient.SetEmail(&email)
driveRecipient1 := graphmodels.NewDriveRecipient()
email := "robin@contoso.org"
driveRecipient1.SetEmail(&email)
recipients := []graphmodels.DriveRecipientable {
driveRecipient,
driveRecipient1,
}
requestBody.SetRecipients(recipients)
message := "Here's the file that we're collaborating on."
requestBody.SetMessage(&message)
requireSignIn := true
requestBody.SetRequireSignIn(&requireSignIn)
sendInvitation := true
requestBody.SetSendInvitation(&sendInvitation)
roles := []string {
"write",
}
requestBody.SetRoles(roles)
password := "password123"
requestBody.SetPassword(&password)
expirationDateTime := "2018-07-15T14:00:00.000Z"
requestBody.SetExpirationDateTime(&expirationDateTime)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
invite, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Invite().PostAsInvitePostResponse(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.beta.drives.item.items.item.invite.InvitePostRequestBody invitePostRequestBody = new com.microsoft.graph.beta.drives.item.items.item.invite.InvitePostRequestBody();
LinkedList<DriveRecipient> recipients = new LinkedList<DriveRecipient>();
DriveRecipient driveRecipient = new DriveRecipient();
driveRecipient.setEmail("helga@contoso.com");
recipients.add(driveRecipient);
DriveRecipient driveRecipient1 = new DriveRecipient();
driveRecipient1.setEmail("robin@contoso.org");
recipients.add(driveRecipient1);
invitePostRequestBody.setRecipients(recipients);
invitePostRequestBody.setMessage("Here's the file that we're collaborating on.");
invitePostRequestBody.setRequireSignIn(true);
invitePostRequestBody.setSendInvitation(true);
LinkedList<String> roles = new LinkedList<String>();
roles.add("write");
invitePostRequestBody.setRoles(roles);
invitePostRequestBody.setPassword("password123");
invitePostRequestBody.setExpirationDateTime("2018-07-15T14:00:00.000Z");
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").invite().post(invitePostRequestBody);
const options = {
authProvider,
};
const client = Client.init(options);
const permission = {
recipients: [
{
email: 'helga@contoso.com'
},
{
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);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Drives\Item\Items\Item\Invite\InvitePostRequestBody;
use Microsoft\Graph\Beta\Generated\Models\DriveRecipient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new InvitePostRequestBody();
$recipientsDriveRecipient1 = new DriveRecipient();
$recipientsDriveRecipient1->setEmail('helga@contoso.com');
$recipientsArray []= $recipientsDriveRecipient1;
$recipientsDriveRecipient2 = new DriveRecipient();
$recipientsDriveRecipient2->setEmail('robin@contoso.org');
$recipientsArray []= $recipientsDriveRecipient2;
$requestBody->setRecipients($recipientsArray);
$requestBody->setMessage('Here\'s the file that we\'re collaborating on.');
$requestBody->setRequireSignIn(true);
$requestBody->setSendInvitation(true);
$requestBody->setRoles(['write', ]);
$requestBody->setPassword('password123');
$requestBody->setExpirationDateTime('2018-07-15T14:00:00.000Z');
$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->invite()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Files
$params = @{
recipients = @(
@{
email = "helga@contoso.com"
}
@{
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"
}
Invoke-MgBetaInviteDriveItem -DriveId $driveId -DriveItemId $driveItemId -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.drives.item.items.item.invite.invite_post_request_body import InvitePostRequestBody
from msgraph_beta.generated.models.drive_recipient import DriveRecipient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = InvitePostRequestBody(
recipients = [
DriveRecipient(
email = "helga@contoso.com",
),
DriveRecipient(
email = "robin@contoso.org",
),
],
message = "Here's the file that we're collaborating on.",
require_sign_in = True,
send_invitation = True,
roles = [
"write",
],
password = "password123",
expiration_date_time = "2018-07-15T14:00:00.000Z",
)
result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').invite.post(request_body)
Respuesta
En el ejemplo siguiente se muestra la respuesta parcial.
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"
}
]
}
Contenido relacionado
Para obtener una lista de los roles disponibles, consulte los valores de propiedad de los roles.