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.

Permissões

Uma das seguintes permissões é obrigatória para chamar esta 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.
password	cadeia de caracteres	A senha do link de compartilhamento definido pelo criador. Opcional e OneDrive somente pessoal.
expirationDateTime	cadeia de caracteres	Uma cadeia de caracteres com formato de yyyy-MM-ddTHH:mm:ssZ de DateTime indica o tempo de expiração da permissão.
scope	string	Opcional. O escopo do link a ser criado. Pode ser anonymous ou organization.

Tipos de link

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

HTTP

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

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

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var type = "view";

var password = "ThisIsMyPrivatePassword";

var scope = "anonymous";

await graphClient.Me.Drive.Items["{driveItem-id}"]
    .CreateLink(type,scope,null,password,null,null)
    .Request()
    .PostAsync();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

JavaScript

const options = {
    authProvider,
};

const client = Client.init(options);

const permission = {
  type: 'view',
  password: 'ThisIsMyPrivatePassword',
  scope: 'anonymous'
};

await client.api('/me/drive/items/{item-id}/createLink')
    .post(permission);

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Objective-C

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/drive/items/{item-id}/createLink"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

NSMutableDictionary *payloadDictionary = [[NSMutableDictionary alloc] init];

NSString *type = @"view";
payloadDictionary[@"type"] = type;

NSString *password = @"ThisIsMyPrivatePassword";
payloadDictionary[@"password"] = password;

NSString *scope = @"anonymous";
payloadDictionary[@"scope"] = scope;

NSData *data = [NSJSONSerialization dataWithJSONObject:payloadDictionary options:kNilOptions error:&error];
[urlRequest setHTTPBody:data];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        //Request Completed

}];

[meDataTask execute];

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

String type = "view";

String password = "ThisIsMyPrivatePassword";

String scope = "anonymous";

graphClient.me().drive().items("{item-id}")
    .createLink(DriveItemCreateLinkParameterSet
        .newBuilder()
        .withType(type)
        .withScope(scope)
        .withExpirationDateTime(null)
        .withPassword(password)
        .withMessage(null)
        .withRetainInheritedPermissions(null)
        .build())
    .buildRequest()
    .post();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

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
}

Criando links compartilháveis pela empresa

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

HTTP

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

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

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var type = "edit";

var scope = "organization";

await graphClient.Me.Drive.Items["{driveItem-id}"]
    .CreateLink(type,scope,null,null,null,null)
    .Request()
    .PostAsync();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

JavaScript

const options = {
    authProvider,
};

const client = Client.init(options);

const permission = {
  type: 'edit',
  scope: 'organization'
};

await client.api('/me/drive/items/{item-id}/createLink')
    .post(permission);

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Objective-C

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/drive/items/{item-id}/createLink"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

NSMutableDictionary *payloadDictionary = [[NSMutableDictionary alloc] init];

NSString *type = @"edit";
payloadDictionary[@"type"] = type;

NSString *scope = @"organization";
payloadDictionary[@"scope"] = scope;

NSData *data = [NSJSONSerialization dataWithJSONObject:payloadDictionary options:kNilOptions error:&error];
[urlRequest setHTTPBody:data];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        //Request Completed

}];

[meDataTask execute];

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

String type = "edit";

String scope = "organization";

graphClient.me().drive().items("{item-id}")
    .createLink(DriveItemCreateLinkParameterSet
        .newBuilder()
        .withType(type)
        .withScope(scope)
        .withExpirationDateTime(null)
        .withPassword(null)
        .withMessage(null)
        .withRetainInheritedPermissions(null)
        .build())
    .buildRequest()
    .post();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

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

Criar links inseríveis

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

HTTP

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

{
  "type": "embed"
}

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var type = "embed";

await graphClient.Me.Drive.Items["{driveItem-id}"]
    .CreateLink(type,null,null,null,null,null)
    .Request()
    .PostAsync();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

JavaScript

const options = {
    authProvider,
};

const client = Client.init(options);

const permission = {
  type: 'embed'
};

await client.api('/me/drive/items/{item-id}/createLink')
    .post(permission);

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Objective-C

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/drive/items/{item-id}/createLink"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

NSMutableDictionary *payloadDictionary = [[NSMutableDictionary alloc] init];

NSString *type = @"embed";
payloadDictionary[@"type"] = type;

NSData *data = [NSJSONSerialization dataWithJSONObject:payloadDictionary options:kNilOptions error:&error];
[urlRequest setHTTPBody:data];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        //Request Completed

}];

[meDataTask execute];

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

String type = "embed";

graphClient.me().drive().items("{item-id}")
    .createLink(DriveItemCreateLinkParameterSet
        .newBuilder()
        .withType(type)
        .withScope(null)
        .withExpirationDateTime(null)
        .withPassword(null)
        .withMessage(null)
        .withRetainInheritedPermissions(null)
        .build())
    .buildRequest()
    .post();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

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