Partilhar via


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.

Crie uma ligação para partilhar um driveItem driveItem.

A ação createLink cria uma nova ligação de partilha se o tipo de ligação especificado ainda não existir para a aplicação de chamada. Se já existir uma ligação de partilha do tipo especificado para a aplicação, é devolvida a ligação de partilha existente.

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

Esta API está disponível nas seguintes implementações de cloud nacionais.

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

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Tipo de permissão Permissões com menos privilégios Permissões com privilégios superiores
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 aceder ao conteúdo do contentor. Esta permissão é diferente das mencionadas anteriormente. Além das permissões do Microsoft Graph, a sua aplicação tem de ter as permissões de tipo de contentor necessárias para chamar esta API. Para obter mais informações, veja Autorização e autenticaçã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, organizationou users
expirationDateTime DateTimeOffset Opcional. Uma Cadeia com o formato aaaa-MM-ddTHH:mm:ssZ de DateTime indica a hora de expiração da permissão.
password String Opcional. O criador define a palavra-passe da ligação de partilha.
destinatários coleção driveRecipient Opcional. Uma coleção de destinatários que recebem acesso à ligação de partilha.
retainInheritedPermissions Booleano Opcional. Se true (predefinição), todas as permissões herdadas existentes forem mantidas no item partilhado ao partilhar este item pela primeira vez. Se false, todas as permissões existentes são removidas ao partilhar pela primeira vez.
sendNotification Booliano Se true, este método envia uma ligação de partilha num e-mail para os utilizadores 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 uma ligação só de leitura para o driveItem.
rever Cria uma ligação de revisão para o driveItem. Esta opção só está disponível para ficheiros no OneDrive for Business e no SharePoint.
edit Cria uma ligação de leitura/escrita para o driveItem.
Incorporar Cria uma ligação incorporáveis para o driveItem.
blocksDownload Cria uma ligação só de leitura que bloqueia a transferência para o driveItem. Esta opção só está disponível para ficheiros no OneDrive for Business e no SharePoint.
criarOnly Cria uma ligação apenas de carregamento para o driveItem. Esta opção só está disponível para pastas no OneDrive for Business e no SharePoint.
barra de endereços Cria a ligação predefinida que é apresentada nas barras de endereço do browser para ficheiros criados recentemente. Disponível apenas no OneDrive for Business e no SharePoint. O administrador da organização configura se este tipo de ligação suporta e especifica que funcionalidades suporta.
adminDefault Cria a ligação predefinida 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 fora da sua organização. Um administrador pode desativar o suporte para ligações anónimas.
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 As pessoas específicas na coleção do destinatário podem utilizar a ligação 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 é se for 201 Created criada uma nova ligação de partilha para o driveItem ou 200 OK se for devolvida uma ligação existente.

Exemplos

O exemplo seguinte pede a criação de uma ligação de partilha para o driveItem especificado por {itemId} no OneDrive do utilizador. O link de compartilhamento é configurado como somente leitura e utilizável por qualquer pessoa com o link. Para OneDrive for Business e utilizadores do SharePoint, utilize o sendNotification parâmetro para criar uma ligação de partilha. A ligação de partilha é, em seguida, enviada aos destinatários por e-mail. Todas as permissões existentes são removidas ao partilhar pela primeira vez se retainInheritedPermissions for falso.

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. São semelhantes a ligações anónimas, exceto que só 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/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 é criada uma ligação de incorporação, a webHtml propriedade contém o código HTML de um <iframe> para alojar 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 uma ligação com base na política predefinida da organização e nas permissões do autor da chamada no driveItem, omita o âmbito e os parâmetros de tipo.
  • As ligações criadas com esta ação não expiram, a menos que seja imposta uma política de expiração predefinida para a organização.
  • As ligações são visíveis nas permissões de partilha do driveItem e podem ser removidas por um proprietário do driveItem.
  • As ligações apontam sempre para a versão atual de um driveItem, a menos que seja dada saída do driveItem (apenas no SharePoint).