Compartilhar via


Criar um link de compartilhamento para um DriveItem

Namespace: microsoft.graph

Você pode usar a ação createLink para compartilhar um DriveItem por meio de um link de compartilhamento.

A ação createLink criará um novo link de compartilhamento se o tipo de link especificado não existir para o aplicativo de chamada. Se um link de compartilhamento do tipo especificado já existir para o aplicativo, o link de compartilhamento existente será retornado.

Recursos de DriveItem herdam permissões de compartilhamento de seus ancestrais.

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/{driveId}/items/{itemId}/createLink
POST /groups/{groupId}/drive/items/{itemId}/createLink
POST /me/drive/items/{itemId}/createLink
POST /sites/{siteId}/drive/items/{itemId}/createLink
POST /users/{userId}/drive/items/{itemId}/createLink

Cabeçalhos de solicitação

Nome Descrição
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-Type application/json. Obrigatório.

Corpo da solicitação

O corpo da solicitação define as propriedades do link de compartilhamento que seu aplicativo está solicitando. A solicitação deve ser um objeto JSON com as seguintes propriedades.

Nome Tipo Descrição
type string O tipo de link de compartilhamento a ser criado. Pode ser view, edit ou embed.
senha string A senha do link de compartilhamento que é definido pelo criador. Somente Opcional e OneDrive Personal.
expirationDateTime string Uma Cadeia de Caracteres com formato de yyyy-MM-ddTHH:mm:ssZ de DateTime indica a hora de expiração da permissão.
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.
scope string Opcional. O escopo do link a ser criado. Pode ser anonymous, organization ou users.

Os seguintes valores são permitidos para o parâmetro type.

Valor do tipo Descrição
view Cria um link somente leitura para DriveItem.
edit Cria um link de leitura e gravação para DriveItem.
embed Cria um link incorporado para DriveItem. Essa opção só está disponível para arquivos no OneDrive Pessoal.

Tipos de escopo

Os seguintes valores são permitidos para o parâmetro scope. Se o parâmetro scope não for especificado, o tipo de link padrão será criado para a organização.

Valor Descrição
anonymous Qualquer pessoa com o link tem acesso, sem precisar fazer logon. Isso pode incluir pessoas de fora da organização. O suporte para links anônimos pode ser desativado por um administrador.
organization Qualquer pessoa que tenha feito logon em sua organização (locatário) pode usar o link para obter acesso. Disponível apenas no OneDrive for Business e no SharePoint.
users Compartilhe somente com pessoas que você escolher dentro ou fora da organização.

Resposta

Se for bem-sucedido, esse método retornará um único recurso Permission no corpo da resposta, que representa as permissões de compartilhamento solicitadas.

A resposta será 201 Created se um novo link de compartilhamento for criado para o item ou 200 OK se um link existente for retornado.

Exemplo

O exemplo a seguir solicita um link de compartilhamento que será criado para o DriveItem especificado por {itemId} no OneDrive do usuário. O link de compartilhamento é configurado como somente leitura e utilizável por qualquer pessoa com o link. Todas as permissões existentes são removidas ao compartilhar pela primeira vez se retainInheritedPermissions for falso.

Solicitação

POST https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/createLink
Content-type: application/json

{
  "type": "view",
  "password": "ThisIsMyPrivatePassword",
  "scope": "anonymous",
  "retainInheritedPermissions": false
}

Resposta

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["write"],
  "link": {
    "type": "view",
    "scope": "anonymous",
    "webUrl": "https://1drv.ms/A6913278E564460AA616C71B28AD6EB6",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  },
  "hasPassword": true
}

O OneDrive for Business e o SharePoint oferecem suporte a links compartilháveis pela empresa. Estes são semelhantes a links anônimos, com a diferença de que apenas funcionam para membros da organização proprietária. Para criar um link compartilhável pela empresa, use o parâmetro scope com um valor de organization.

Solicitação

POST https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/createLink
Content-Type: application/json

{
  "type": "edit",
  "scope": "organization"
}

Resposta

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["write"],
  "link": {
    "type": "edit",
    "scope": "organization",
    "webUrl": "https://contoso-my.sharepoint.com/personal/ellen_contoso_com/...",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  },
}

Ao usar o tipo de link embed, a webUrl retornada pode ser inserida em um elemento HTML <iframe>. Quando um link de inserção é criado, a propriedade webHtml contém o código HTML de um <iframe> para hospedar o conteúdo.

Observação: os links de inseridos só tem suporte no OneDrive Pessoal.

Solicitação

POST https://graph.microsoft.com/v1.0/me/drive/items/{item-id}/createLink
Content-Type: application/json

{
  "type": "embed"
}

Resposta

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["read"],
  "link": {
    "type": "embed",
    "webHtml": "<IFRAME src=\"https://onedrive.live.com/...\"></IFRAME>",
    "webUrl": "https://onedrive.live.com/...",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  }
}

Comentários

  • Links criados usando esta ação não expiram, a menos que uma política de expiração padrão seja imposta à organização.
  • Os links ficam visíveis nas permissões de compartilhamento do item e podem ser removidos por um proprietário desse item.
  • Os links sempre apontam para a versão atual de um item, a menos que esse item esteja em check-out (apenas no SharePoint).