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 |
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
| 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. |
Tipos de link
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
Exemplo 1: criar uma ligação de partilha anónima
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
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Drives.Item.Items.Item.CreateLink;
using Microsoft.Graph.Beta.Models;
var requestBody = new CreateLinkPostRequestBody
{
Type = "view",
Scope = "anonymous",
Password = "String",
Recipients = new List<DriveRecipient>
{
new DriveRecipient
{
OdataType = "microsoft.graph.driveRecipient",
},
},
SendNotification = true,
RetainInheritedPermissions = false,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].CreateLink.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-beta-sdk-go/drives"
graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
//other-imports
)
requestBody := graphdrives.NewCreateLinkPostRequestBody()
type := "view"
requestBody.SetType(&type)
scope := "anonymous"
requestBody.SetScope(&scope)
password := "String"
requestBody.SetPassword(&password)
driveRecipient := graphmodels.NewDriveRecipient()
recipients := []graphmodels.DriveRecipientable {
driveRecipient,
}
requestBody.SetRecipients(recipients)
sendNotification := true
requestBody.SetSendNotification(&sendNotification)
retainInheritedPermissions := false
requestBody.SetRetainInheritedPermissions(&retainInheritedPermissions)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
createLink, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").CreateLink().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.beta.drives.item.items.item.createlink.CreateLinkPostRequestBody createLinkPostRequestBody = new com.microsoft.graph.beta.drives.item.items.item.createlink.CreateLinkPostRequestBody();
createLinkPostRequestBody.setType("view");
createLinkPostRequestBody.setScope("anonymous");
createLinkPostRequestBody.setPassword("String");
LinkedList<DriveRecipient> recipients = new LinkedList<DriveRecipient>();
DriveRecipient driveRecipient = new DriveRecipient();
driveRecipient.setOdataType("microsoft.graph.driveRecipient");
recipients.add(driveRecipient);
createLinkPostRequestBody.setRecipients(recipients);
createLinkPostRequestBody.setSendNotification(true);
createLinkPostRequestBody.setRetainInheritedPermissions(false);
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").createLink().post(createLinkPostRequestBody);
const options = {
authProvider,
};
const client = Client.init(options);
const permission = {
type: 'view',
scope: 'anonymous',
password: 'String',
recipients: [
{
'@odata.type': 'microsoft.graph.driveRecipient'
}
],
sendNotification: true,
retainInheritedPermissions: false
};
await client.api('/me/drive/items/{itemId}/createLink')
.version('beta')
.post(permission);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Drives\Item\Items\Item\CreateLink\CreateLinkPostRequestBody;
use Microsoft\Graph\Beta\Generated\Models\DriveRecipient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new CreateLinkPostRequestBody();
$requestBody->setType('view');
$requestBody->setScope('anonymous');
$requestBody->setPassword('String');
$recipientsDriveRecipient1 = new DriveRecipient();
$recipientsDriveRecipient1->setOdataType('microsoft.graph.driveRecipient');
$recipientsArray []= $recipientsDriveRecipient1;
$requestBody->setRecipients($recipientsArray);
$requestBody->setSendNotification(true);
$requestBody->setRetainInheritedPermissions(false);
$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->createLink()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Files
$params = @{
type = "view"
scope = "anonymous"
password = "String"
recipients = @(
@{
"@odata.type" = "microsoft.graph.driveRecipient"
}
)
sendNotification = $true
retainInheritedPermissions = $false
}
New-MgBetaDriveItemLink -DriveId $driveId -DriveItemId $driveItemId -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.drives.item.items.item.create_link.create_link_post_request_body import CreateLinkPostRequestBody
from msgraph_beta.generated.models.drive_recipient import DriveRecipient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = CreateLinkPostRequestBody(
type = "view",
scope = "anonymous",
password = "String",
recipients = [
DriveRecipient(
odata_type = "microsoft.graph.driveRecipient",
),
],
send_notification = True,
retain_inherited_permissions = False,
)
result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').create_link.post(request_body)
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
}
Exemplo 2: Criar ligações sharable da empresa
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"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Drives.Item.Items.Item.CreateLink;
var requestBody = new CreateLinkPostRequestBody
{
Type = "edit",
Scope = "organization",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].CreateLink.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-beta-sdk-go/drives"
//other-imports
)
requestBody := graphdrives.NewCreateLinkPostRequestBody()
type := "edit"
requestBody.SetType(&type)
scope := "organization"
requestBody.SetScope(&scope)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
createLink, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").CreateLink().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.beta.drives.item.items.item.createlink.CreateLinkPostRequestBody createLinkPostRequestBody = new com.microsoft.graph.beta.drives.item.items.item.createlink.CreateLinkPostRequestBody();
createLinkPostRequestBody.setType("edit");
createLinkPostRequestBody.setScope("organization");
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").createLink().post(createLinkPostRequestBody);
const options = {
authProvider,
};
const client = Client.init(options);
const permission = {
type: 'edit',
scope: 'organization'
};
await client.api('/me/drive/items/{item-id}/createLink')
.version('beta')
.post(permission);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Drives\Item\Items\Item\CreateLink\CreateLinkPostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new CreateLinkPostRequestBody();
$requestBody->setType('edit');
$requestBody->setScope('organization');
$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->createLink()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Files
$params = @{
type = "edit"
scope = "organization"
}
New-MgBetaDriveItemLink -DriveId $driveId -DriveItemId $driveItemId -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.drives.item.items.item.create_link.create_link_post_request_body import CreateLinkPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = CreateLinkPostRequestBody(
type = "edit",
scope = "organization",
)
result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').create_link.post(request_body)
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"
},
}
}
Exemplo 3: Criar ligações incorporáveis
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"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Drives.Item.Items.Item.CreateLink;
var requestBody = new CreateLinkPostRequestBody
{
Type = "embed",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].CreateLink.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphdrives "github.com/microsoftgraph/msgraph-beta-sdk-go/drives"
//other-imports
)
requestBody := graphdrives.NewCreateLinkPostRequestBody()
type := "embed"
requestBody.SetType(&type)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
createLink, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").CreateLink().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.beta.drives.item.items.item.createlink.CreateLinkPostRequestBody createLinkPostRequestBody = new com.microsoft.graph.beta.drives.item.items.item.createlink.CreateLinkPostRequestBody();
createLinkPostRequestBody.setType("embed");
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").createLink().post(createLinkPostRequestBody);
const options = {
authProvider,
};
const client = Client.init(options);
const permission = {
type: 'embed'
};
await client.api('/me/drive/items/{item-id}/createLink')
.version('beta')
.post(permission);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Drives\Item\Items\Item\CreateLink\CreateLinkPostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new CreateLinkPostRequestBody();
$requestBody->setType('embed');
$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->createLink()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Files
$params = @{
type = "embed"
}
New-MgBetaDriveItemLink -DriveId $driveId -DriveItemId $driveItemId -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.drives.item.items.item.create_link.create_link_post_request_body import CreateLinkPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = CreateLinkPostRequestBody(
type = "embed",
)
result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').create_link.post(request_body)
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"
},
}
}
- 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).