driveItem: lock

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.

Adquira um bloqueio exclusivo em um arquivo representado por um driveItem ou estenda um bloqueio existente que você já possui. Enquanto o bloqueio é mantido, outros usuários são impedidos de adquirir um bloqueio no mesmo arquivo. O bloqueio expira automaticamente após o término da duração especificada na solicitação.

Observação

Essa API se aplica somente a driveItems que representam arquivos. Os bloqueios não podem ser aplicados a pastas ou outros driveItems que não sejam de arquivos. As solicitações direcionadas a um driveItem que não é de arquivo são rejeitadas com 400 Bad Request.

Um único ponto de extremidade lida com a aquisição inicial e a atualização. O servidor determina qual comportamento se aplica com base no estado de bloqueio atual do arquivo e na identidade do chamador. O chamador não precisa rastrear se bloqueou o arquivo anteriormente e não precisa gerenciar um identificador de bloqueio.

No momento, há suporte apenas para bloqueios exclusivos.

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)	Sem suporte.	Sem suporte.
Application	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/{drive-id}/items/{item-id}/lock

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

No corpo da solicitação, forneça uma representação JSON dos parâmetros de bloqueio.

Propriedade	Tipo	Obrigatório	Descrição
durationMinutes	Int32	Sim	Duração do bloqueio em minutos. Deve ser entre 1 e 30 minutos. O bloqueio expira no momento da solicitação mais esse valor.

O identificador de bloqueio e o tipo de bloqueio são determinados pelo servidor e não devem ser fornecidos pelo chamador.

Resposta

O servidor determina se essa solicitação adquire um novo bloqueio ou atualiza um existente com base no estado de bloqueio atual do arquivo e na identidade do chamador:

Estado atual	Identidade do chamador	Ação
O arquivo não está bloqueado ou o bloqueio existente expirou.	Qualquer chamador com permissão.	Adquira um novo bloqueio.
O arquivo está bloqueado e o chamador mantém o bloqueio.	Mesmo chamador que o proprietário do bloqueio.	Atualize o bloqueio existente; expirationDateTime é atualizado.
O arquivo está bloqueado por outro usuário.	Chamador diferente.	Retornar 409 Conflict. O chamador não pode adquirir um bloqueio até que o bloqueio existente seja liberado ou expire.

Se for bem-sucedido, esse método retornará um código de 200 OK resposta e um recurso lockInfo no corpo da resposta.

Esse método retorna os códigos de resposta de erro a seguir.

Código HTTP	Descrição
400	Solicitação incorreta. O durationMinutes está ausente, não é positivo ou excede o máximo de 30 minutos. Também retornado quando o driveItem de destino não é um arquivo (por exemplo, uma pasta).
401	A solicitação não tem credenciais de autenticação válidas.
403	O chamador não tem permissão para bloquear este arquivo.
404	O driveItem não foi encontrado no caminho especificado.
409	O arquivo foi bloqueado por outro usuário. O chamador deve aguardar que o bloqueio existente seja liberado ou expire antes de adquirir um novo bloqueio.

Para obter mais informações sobre como os erros são retornados, consulte Respostas a erros e tipos de recursos para diferenças entre o Microsoft Graph para contas Microsoft e o Microsoft Graph para contas corporativas ou de estudante.

Exemplos

Exemplo 1: Adquirir um bloqueio em um arquivo desbloqueado

Solicitação

O exemplo a seguir mostra uma solicitação.

HTTP

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

{
  "durationMinutes": 30
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Drives.Item.Items.Item.Lock;

var requestBody = new LockPostRequestBody
{
	DurationMinutes = 30,
};

// 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}"].Lock.PostAsync(requestBody);

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

Ir

// 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.NewLockPostRequestBody()
durationMinutes := int32(30)
requestBody.SetDurationMinutes(&durationMinutes) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
lock, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Lock().Post(context.Background(), requestBody, nil)

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

Java

// 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.lock.LockPostRequestBody lockPostRequestBody = new com.microsoft.graph.beta.drives.item.items.item.lock.LockPostRequestBody();
lockPostRequestBody.setDurationMinutes(30);
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").lock().post(lockPostRequestBody);

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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 lockInfo = {
  durationMinutes: 30
};

await client.api('/drives/{drive-id}/items/{item-id}/lock')
	.version('beta')
	.post(lockInfo);

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

PHP

<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Drives\Item\Items\Item\Lock\LockPostRequestBody;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new LockPostRequestBody();
$requestBody->setDurationMinutes(30);

$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->lock()->post($requestBody)->wait();

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

PowerShell

Import-Module Microsoft.Graph.Beta.Files

$params = @{
	durationMinutes = 30
}

Lock-MgBetaDriveItem -DriveId $driveId -DriveItemId $driveItemId -BodyParameter $params

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

Python

# 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.lock.lock_post_request_body import LockPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = LockPostRequestBody(
	duration_minutes = 30,
)

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').lock.post(request_body)

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "lockType": "exclusive",
  "expirationDateTime": "2026-05-13T14:30:00Z",
  "createdDateTime": "2026-05-13T14:00:00Z"
}

Exemplo 2: atualizar um bloqueio existente que o chamador já possui

O corpo da solicitação é idêntico ao caso de aquisição; Somente o estado atual do arquivo é diferente.

Solicitação

O exemplo a seguir mostra uma solicitação.

HTTP

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

{
  "durationMinutes": 10
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Drives.Item.Items.Item.Lock;

var requestBody = new LockPostRequestBody
{
	DurationMinutes = 10,
};

// 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}"].Lock.PostAsync(requestBody);

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

Ir

// 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.NewLockPostRequestBody()
durationMinutes := int32(10)
requestBody.SetDurationMinutes(&durationMinutes) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
lock, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Lock().Post(context.Background(), requestBody, nil)

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

Java

// 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.lock.LockPostRequestBody lockPostRequestBody = new com.microsoft.graph.beta.drives.item.items.item.lock.LockPostRequestBody();
lockPostRequestBody.setDurationMinutes(10);
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").lock().post(lockPostRequestBody);

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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 lockInfo = {
  durationMinutes: 10
};

await client.api('/drives/{drive-id}/items/{item-id}/lock')
	.version('beta')
	.post(lockInfo);

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

PHP

<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Drives\Item\Items\Item\Lock\LockPostRequestBody;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new LockPostRequestBody();
$requestBody->setDurationMinutes(10);

$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->lock()->post($requestBody)->wait();

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

PowerShell

Import-Module Microsoft.Graph.Beta.Files

$params = @{
	durationMinutes = 10
}

Lock-MgBetaDriveItem -DriveId $driveId -DriveItemId $driveItemId -BodyParameter $params

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

Python

# 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.lock.lock_post_request_body import LockPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = LockPostRequestBody(
	duration_minutes = 10,
)

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').lock.post(request_body)

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

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

Resposta

O exemplo a seguir mostra a resposta. A expirationDateTime é atualizada.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "lockType": "exclusive",
  "expirationDateTime": "2026-05-13T14:39:00Z",
  "createdDateTime": "2026-05-13T14:00:00Z"
}

Comentários

• No momento, há suporte apenas para bloqueios exclusivos. O lockType na resposta é sempre exclusive.
• A duração do bloqueio é limitada a 30 minutos por solicitação. Para retenções mais longas, chame essa API novamente antes que o bloqueio existente expire; A chamada é tratada automaticamente como uma atualização.
• O novo expirationDateTime é calculado como o tempo da solicitação mais durationMinutes; Ela substitui a expiração anterior em vez de estendê-la. Chamar com uma duração menor do que o tempo restante reduz efetivamente a janela de bloqueio.
• createdDateTime e expirationDateTime são retornados em UTC.
• Essa API é idempotente e segura para novas tentativas: se uma falha de rede deixar o chamador incerto se o bloqueio foi bem-sucedido, a repetição naturalmente resultará em uma atualização (se a primeira chamada for bem-sucedida) ou em uma nova aquisição (se não tiver ocorrido).