Share via

Enviar um convite de compartilhamento

  • Artigo

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Envia um convite de compartilhamento para um driveItem. Um convite de compartilhamento fornece permissões para os destinatários e, opcionalmente, envia um email aos destinatários para notificá-los de que o item foi compartilhado.

Essa API está disponível nas seguintes implantações nacionais de nuvem.

Serviço global Governo dos EUA L4 GOVERNO DOS EUA L5 (DOD) China operada pela 21Vianet
✅ ✅ ✅ ✅

Permissões

Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão Permissões menos privilegiadas Permissões privilegiadas mais altas
Delegado (conta corporativa ou de estudante) Files.ReadWrite Files.ReadWrite.All, Sites.ReadWrite.All
Delegado (conta pessoal da Microsoft) Files.ReadWrite Files.ReadWrite.All
Aplicativo Files.ReadWrite.All Sites.ReadWrite.All

Solicitação 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

Corpo da solicitação

Forneça um objeto JSON com os seguintes parâmetros no corpo da solicitação.

{
  "requireSignIn": false,
  "sendInvitation": false,
  "roles": [ "read | write"],
  "recipients": [
    { "@odata.type": "microsoft.graph.driveRecipient" },
    { "@odata.type": "microsoft.graph.driveRecipient" }
  ],
  "message": "string"
}
Parâmetro Tipo Descrição
destinatários Coleção(driveRecipient) Uma coleção de destinatários que recebem acesso e o convite de compartilhamento.
mensagem String Uma mensagem de texto sem formatação que está incluída no convite de compartilhamento. Comprimento máximo de 2.000 caracteres.
requireSignIn Booliano Especifica onde o destinatário do convite precisa entrar para exibir o item compartilhado.
sendInvitation Booliano Especifica se um email ou postagem é gerado (false) ou se a permissão foi criada recentemente (true).
funções Collection(String) Especifica as funções concedidas aos destinatários do convite de compartilhamento.
expirationDateTime DateTimeOffset Especifica o dateTime após o qual a permissão expira. Para OneDrive for Business e SharePoint, xpirationDateTime só é aplicável para permissões do sharingLink. Disponível em contas OneDrive for Business, SharePoint e OneDrive pessoais premium.
password String A senha definida no convite pelo criador. Somente Opcional e OneDrive Pessoal
retainInheritedPermissions Booleano Opcional. Se true (padrão), todas as permissões herdadas existentes serão mantidas no item compartilhado ao compartilhar esse item pela primeira vez. Se false, todas as permissões existentes forem removidas ao compartilhar pela primeira vez.

Exemplo

Este exemplo envia um convite de compartilhamento para um usuário com endereço de email "ryan@contoso.org" com uma mensagem sobre um arquivo em que está sendo colaborado. O convite concede acesso de leitura e gravação ao arquivo para Ryan.

Solicitação HTTP

Se bem-sucedido, este método retorna o código de resposta 200 OK e o objeto de coleção permission no corpo da resposta.

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

Resposta

O exemplo a seguir mostra a resposta.

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

Resposta de sucesso parcial

Ao convidar vários destinatários, é possível que a notificação tenha êxito para alguns e falhe para outros. Nesse caso, o serviço retorna uma resposta de sucesso parcial com um código de status HTTP de 207. Quando o sucesso parcial é retornado, a resposta para cada destinatário com falha contém um error objeto com informações sobre o que deu errado e como corrigi-lo.

O exemplo a seguir mostra a resposta 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"
    }
  ]
}

Erros de SendNotification

A seguir estão alguns outros erros que seu aplicativo pode encontrar dentro dos objetos aninhados innererror ao enviar a notificação falhar. Os aplicativos não são necessários para lidar com esses erros.

Código Descrição
accountVerificationRequired A verificação da conta é necessária para desbloquear o envio de notificações.
hipCheckRequired É necessário resolver marcar hip (prevenção contra intrusão de host) para desbloquear o envio de notificações.
exchangeInvalidUser A caixa de correio do usuário atual não foi encontrada.
exchangeOutOfMailboxQuota Fora da cota.
exchangeMaxRecipients Excedeu o número máximo de destinatários que podem ser enviados notificações ao mesmo tempo.

Nota: O serviço pode adicionar novos códigos de erro ou parar de retornar os antigos a qualquer momento.

Comentários

Respostas de erros

Leia o tópico Respostas de erro para obter mais informações sobre como os erros são retornados.