Criar um link de compartilhamento para um DriveItem

  • Artigo

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.

Permissões

Uma das permissões a seguir é necessária para chamar essa API. Para saber mais, incluindo como escolher permissões, confira Permissões.

Tipo de permissão Permissões (da com menos para a com mais privilégios)
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

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.
scope string Opcional. O escopo do link a ser criado. Pode ser anonymous ou organization.

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.

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.

Solicitação

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

{
  "type": "view",
  "scope": "anonymous"
}

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

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 /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.

Solicitar

POST /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://onedive.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).