driveItem: createLink

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.

Criar um link para compartilhar um driveItem driveItem.

A ação createLink criará um novo link de compartilhamento se o tipo de link especificado ainda 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 de nuvem nacional.

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

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos 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 com privilégios mais elevados
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

Observação

O SharePoint Embedded requer a FileStorageContainer.Selected permissão para acessar o conteúdo do contêiner. Essa permissão é diferente das mencionadas anteriormente. Além das permissões do Microsoft Graph, seu aplicativo deve ter as permissões de tipo de contêiner necessárias para chamar essa API. Para obter mais informações, consulte Autenticação e autorização do SharePoint Embedded.

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.

Propriedade Tipo Descrição
type String Opcional. O tipo de link de compartilhamento a ser criado.
scope String Opcional. O escopo do link a ser criado. Ou anonymous, organization, ou users
expirationDateTime DateTimeOffset Opcional. Uma cadeia de caracteres com formato de aaaa-MM-ddTHH:mm:ssZ de DateTime indica o tempo de expiração da permissão.
password String Opcional. O criador define a senha para o link de compartilhamento.
destinatários coleção driveRecipient Opcional. Um grupo de destinatários que recebem acesso ao link de compartilhamento.
retainInheritedPermissions Booleano Opcional. Se true (padrão), quaisquer permissões herdadas existentes são mantidas no item compartilhado ao compartilhar esse item pela primeira vez. Se false, todas as permissões existentes são removidas ao compartilhar pela primeira vez. Não há suporte com o SharePoint Embedded.
sendNotification Booliano Se true, esse método enviar um link de compartilhamento em um email para os usuários especificados em recipients. Aplicável ao OneDrive for Business ou ao SharePoint. O valor padrão é false. Opcional.

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

Valor do tipo Descrição
modo de exibição Cria um link somente leitura para o driveItem.
Revisão Cria um link de revisão para o driveItem. Essa opção só está disponível para arquivos no OneDrive for Business e no SharePoint.
edit Cria um link de leitura/gravação para o driveItem.
Token de Cria um link incorporável para o driveItem.
blocksDownload Cria um link somente leitura que bloqueia o download para o driveItem. Essa opção só está disponível para arquivos no OneDrive for Business e no SharePoint.
createOnly Cria um link somente para upload para o driveItem. Essa opção só está disponível para pastas no OneDrive for Business e no SharePoint.
addressBar Cria o link padrão mostrado nas barras de endereços do navegador para arquivos recém-criados. Disponível apenas no OneDrive for Business e no SharePoint. O administrador da organização configura se este tipo de link é compatível e especifica a quais recursos ele é compatível.
adminDefault Cria o link padrão para o driveItem, conforme determinado pelo administrador da organização. Disponível apenas no OneDrive for Business e no SharePoint. O administrador impõe a política para a organização.

Tipos de escopo

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

Valor Descrição
anônimo Qualquer pessoa com o link tem acesso, sem precisar fazer logon. Pode incluir pessoas de fora da organização. Um administrador pode desabilitar o suporte para links anônimos.
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.
usuários Pessoas específicas na coleção do destinatário podem 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 é 201 Created se um novo link de compartilhamento for criado para o driveItem ou 200 OK se um link existente for retornado.

Exemplos

O exemplo a seguir solicita que um link de compartilhamento seja 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. Para usuários do OneDrive for Business e do SharePoint, use o sendNotification parâmetro para criar um link de compartilhamento. O link de compartilhamento é enviado aos destinatários por email. Todas as permissões existentes serão removidas ao compartilhar pela primeira vez se retainInheritedPermissions for false.

Solicitação

POST https://graph.microsoft.com/beta/me/drive/items/{itemId}/createLink
Content-Type: application/json

{
  "type": "view",
  "scope": "anonymous",
  "password": "String",
  "recipients": [
    {
      "@odata.type": "microsoft.graph.driveRecipient"
    }
  ],
  "sendNotification": true,
  "retainInheritedPermissions": false
}

Resposta

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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. Eles são semelhantes aos links anônimos, exceto que funcionam apenas 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/beta/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 webHtml propriedade contém o código HTML para <iframe> hospedar o conteúdo.

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

Solicitação

O exemplo a seguir mostra uma solicitação.

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

{
  "type": "embed"
}

Resposta

O exemplo a seguir mostra a solicitação.

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

  • Para criar um link com base na política padrão da organização e nas permissões do chamador no driveItem, omita os parâmetros scope e type.
  • Os links criados usando essa ação não expiram, a menos que uma política de expiração padrão seja imposta para a organização.
  • Os links são visíveis nas permissões de compartilhamento para o driveItem e podem ser removidos por um proprietário do driveItem.
  • Os links sempre apontam para a versão atual de um driveItem , a menos que o driveItem seja verificado (somente SharePoint).