user: delta

Artigo
07/18/2022
14 minutos para o fim da leitura

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 de versão.

Veja os usuários recém-criados, atualizados ou excluídos sem precisar executar uma leitura completa de toda a coleção de usuários. Consulte o acompanhamento de alterações para obter detalhes.

Observação

As alterações na propriedade licenseAssignmentStates não são controladas no momento.

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)	User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Delegado (conta pessoal da Microsoft)	Sem suporte.
Aplicativo	User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

Solicitação HTTP

Para iniciar o rastreamento de alterações, faça uma solicitação incluindo a função delta no recurso de usuários.

GET /users/delta

Parâmetros de consulta

O rastreamento de alterações nos usuários incorre em uma rodada de uma ou mais chamadas de função delta. Se você usar qualquer parâmetro de consulta (diferente de $deltatoken e $skiptoken), você deve especificá-lo na solicitação delta inicial. O Microsoft Graph codifica automaticamente quaisquer parâmetros especificados na parte do token do URL @odata.nextLink ou @odata.deltaLink fornecido na réplica.

Você só precisa especificar uma vez os parâmetros de consulta desejados antecipadamente.

Em solicitações subsequentes, copie e aplique a URL @odata.nextLink ou @odata.deltaLink da resposta anterior, já que essa URL inclui os parâmetros codificados desejados.

Parâmetro de consulta	Tipo	Descrição
$deltatoken	string	Um token de estado retornado na URL `@odata.deltaLink` da chamada de função delta anterior da mesma coleção de usuários indicando a conclusão da série de controle de alterações. Salve e aplique toda a URL `@odata.deltaLink`, incluindo esse token na primeira solicitação da próxima série de controle de alterações da coleção.
$skiptoken	string	Um token de estado retornado na URL `@odata.nextLink` da chamada de função delta anterior indicando que não há mais alterações a serem controladas na mesma coleção de usuários.

Parâmetros de consulta OData

Este método fornece suporte opcional a Parâmetros de Consulta OData para ajudar a personalizar a resposta.

Você pode usar um parâmetro de consulta $select como em qualquer solicitação GET para especificar somente as propriedades necessárias para obter melhor desempenho. A propriedade id sempre será retornada.
Há suporte limitado para $filter:
- A única expressão $filter suportada é para controlar alterações em um objeto específico: $filter=id+eq+{value}. É possível filtrar vários objetos. Por exemplo, https://graph.microsoft.com/beta/users/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'. Há um limite de 50 objetos filtrados.

Cabeçalhos de solicitação

Nome	Descrição
Autorização	<Token> de portador
Content-Type	application/json
Preferir	return=minimal Especificar este cabeçalho com uma solicitação que utiliza um `@odata.deltaLink` retornaria apenas as propriedades do objeto que foram alteradas desde a última rodada. Opcional.

Corpo da solicitação

Não forneça um corpo de solicitação para esse método.

Resposta

Se for bem-sucedido, esse método retornará o código de resposta 200 OK e o objeto da coleção usuário no corpo da resposta. A resposta também inclui um URL @odata.nextLink ou um URL @odata.deltaLink.

Se uma URL @odata.nextLink for retornada:
- Isso indica que há páginas adicionais de dados a serem recuperados na sessão. O aplicativo continua fazendo solicitações usando o URL @odata.nextLink até que um URL @odata.deltaLink seja incluído na resposta.
- A resposta inclui o mesmo conjunto de propriedades como na solicitação de consulta delta inicial. Assim você pode capturar o estado atual de todos os objetos ao iniciar o ciclo de delta.
Se uma URL @odata.deltaLink for retornada:
- Isso indica que não há mais nenhum dado a retornar sobre o estado do recurso. Salve e use a URL @odata.deltaLink para saber mais sobre alterações ao recurso na próxima fase.
- Você pode especificar o cabeçalho Prefer:return=minimal para incluir somente os valores de resposta das propriedades que foram alteradas desde a hora em que o @odata.deltaLink foi emitido.

Padrão: retornar as mesmas propriedades de uma solicitação delta inicial

Por padrão, as solicitações usando @odata.deltaLink ou @odata.nextLink retornam as mesmas propriedades selecionadas na consulta delta inicial das seguintes maneiras:

Se a propriedade foi alterada, o novo valor será incluído na resposta. Isso inclui propriedades definidas com valor nulo.
Se a propriedade não foi alterada, o valor antigo será incluído na resposta.
Se a propriedade nunca foi definida anteriormente, de nenhuma forma será incluída na resposta.

Observação: com esse comportamento, ao verificar a resposta, não será possível dizer se uma propriedade foi alterada ou não. Além disso, as respostas delta tendem a ser grandes porque contêm todos os valores de propriedades, como mostrado no Exemplo 2.

Alternativa: retornar somente as propriedades alteradas

Adicionar o cabeçalho prefer:return=minimal opcional na solicitação resulta no comportamento a seguir:

Se a propriedade foi alterada, o novo valor será incluído na resposta. Isso inclui propriedades definidas com valor nulo.
Se a propriedade não foi alterada, a propriedade não será incluído na resposta de forma alguma. (Diferente do comportamento padrão.)

Observação: é possível adicionar o cabeçalho a uma solicitação @odata.deltaLink a qualquer momento no ciclo de delta. O cabeçalho afeta apenas o conjunto de propriedades incluídas na resposta e ele não afeta como a consulta delta é executada. Veja o Exemplo 3.

Exemplos

Exemplo 1: Propriedades padrão

Solicitação

Este é um exemplo de solicitação. Não há nenhum parâmetro $select, assim um conjunto padrão de propriedades será controlado e retornado.

GET https://graph.microsoft.com/beta/users/delta


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Users
    .Delta()
    .Request()
    .GetAsync();

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não dão 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.


const options = {
    authProvider,
};

const client = Client.init(options);

let delta = await client.api('/users/delta')
    .version('beta')
    .get();

Importante

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


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/beta/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/users/delta"]]];
[urlRequest setHTTPMethod:@"GET"];

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

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphUser *user = [[MSGraphUser alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

Importante

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


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

UserDeltaCollectionPage delta = graphClient.users()
    .delta()
    .buildRequest()
    .get();

Importante

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


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

result, err := graphClient.Users().Delta()().Get()

Importante

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


Import-Module Microsoft.Graph.Users.Functions

Get-MgUserDelta

Importante

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

Resposta

A seguir, um exemplo da resposta ao usar @odata.deltaLink obtido da inicialização de consulta.

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

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#users",
  "@odata.nextLink":"https://graph.microsoft.com/beta/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "businessPhones": [
          "+1 425 555 0109"
      ],
      "displayName": "Adele Vance",
      "givenName": "Adele",
      "jobTitle": "Retail Manager",
      "mail": "AdeleV@contoso.onmicrosoft.com",
      "mobilePhone": "+1 425 555 0109",
      "officeLocation": "18/2111",
      "preferredLanguage": "en-US",
      "surname": "Vance",
      "userPrincipalName": "AdeleV@contoso.onmicrosoft.com",
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
    }
  ]
}

Exemplo 2: Escolher três propriedades

Solicitação

O próximo exemplo mostra uma solicitação inicial selecionando três propriedades para controle de alterações com comportamento de resposta padrão.

GET https://graph.microsoft.com/beta/users/delta?$select=displayName,jobTitle,mobilePhone


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Users
    .Delta()
    .Request()
    .Select("displayName,jobTitle,mobilePhone")
    .GetAsync();

Importante

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


const options = {
    authProvider,
};

const client = Client.init(options);

let delta = await client.api('/users/delta')
    .version('beta')
    .select('displayName,jobTitle,mobilePhone')
    .get();

Importante

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


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/beta/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/users/delta?$select=displayName,jobTitle,mobilePhone"]]];
[urlRequest setHTTPMethod:@"GET"];

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

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphUser *user = [[MSGraphUser alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

Importante

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


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

UserDeltaCollectionPage delta = graphClient.users()
    .delta()
    .buildRequest()
    .select("displayName,jobTitle,mobilePhone")
    .get();

Importante

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


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.DeltaRequestBuilderGetQueryParameters{
    Select: "displayName,jobTitle,mobilePhone",
}
options := &msgraphsdk.DeltaRequestBuilderGetRequestConfiguration{
    QueryParameters: requestParameters,
}
result, err := graphClient.Users().Delta()().GetWithRequestConfigurationAndResponseHandler(options, nil)

Importante

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


Import-Module Microsoft.Graph.Users.Functions

Get-MgUserDelta -Property "displayName,jobTitle,mobilePhone"

Importante

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

Resposta

A seguir, um exemplo da resposta ao usar @odata.deltaLink obtido da inicialização de consulta. Observe que todas as três propriedades foram incluídas na resposta e não se sabe quais foram alteradas desde que o @odata.deltaLink foi obtido.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#users",
  "@odata.nextLink":"https://graph.microsoft.com/beta/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "Adele Vance",
      "jobTitle": "Retail Manager",
      "mobilePhone": "+1 425 555 0109"
    }
  ]
}

Exemplo 3: Comportamento de resposta mínimo alternativo

Solicitação

O exemplo a seguir mostra uma solicitação inicial selecionando três propriedades para controle de alterações com o comportamento de resposta mínima alternativa.

GET https://graph.microsoft.com/beta/users/delta?$select=displayName,jobTitle,mobilePhone
Prefer: return=minimal


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Users
    .Delta()
    .Request()
    .Header("Prefer","return=minimal")
    .Select("displayName,jobTitle,mobilePhone")
    .GetAsync();

Importante

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


const options = {
    authProvider,
};

const client = Client.init(options);

let delta = await client.api('/users/delta')
    .version('beta')
    .header('Prefer','return=minimal')
    .select('displayName,jobTitle,mobilePhone')
    .get();

Importante

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


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/beta/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/users/delta?$select=displayName,jobTitle,mobilePhone"]]];
[urlRequest setHTTPMethod:@"GET"];
[urlRequest setValue:@"return=minimal" forHTTPHeaderField:@"Prefer"];

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

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphUser *user = [[MSGraphUser alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

Importante

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


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

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("Prefer", "return=minimal"));

UserDeltaCollectionPage delta = graphClient.users()
    .delta()
    .buildRequest( requestOptions )
    .select("displayName,jobTitle,mobilePhone")
    .get();

Importante

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


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.DeltaRequestBuilderGetQueryParameters{
    Select: "displayName,jobTitle,mobilePhone",
}
headers := map[string]string{
    "Prefer": "return=minimal"
}
options := &msgraphsdk.DeltaRequestBuilderGetRequestConfiguration{
    QueryParameters: requestParameters,
    Headers: headers,
}
result, err := graphClient.Users().Delta()().GetWithRequestConfigurationAndResponseHandler(options, nil)

Importante

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


Import-Module Microsoft.Graph.Users.Functions

Get-MgUserDelta -Property "displayName,jobTitle,mobilePhone"

Importante

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

Resposta

A seguir, um exemplo da resposta ao usar @odata.deltaLink obtido da inicialização de consulta. Observe que a propriedade mobilePhone não foi incluída, ou seja, não foi alterada desde a última consulta delta; displayName e jobTitle foram incluídas, o que significa que os valores foram alterados.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#users",
  "@odata.nextLink":"https://graph.microsoft.com/beta/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "Vance Adele",
      "jobTitle": "Product Marketing Manager"
    }
  ]
}

user: delta

Permissões

Solicitação HTTP

Parâmetros de consulta

Parâmetros de consulta OData

Cabeçalhos de solicitação

Corpo da solicitação

Resposta

Padrão: retornar as mesmas propriedades de uma solicitação delta inicial

Alternativa: retornar somente as propriedades alteradas

Exemplos

Exemplo 1: Propriedades padrão

Solicitação

Resposta

Exemplo 2: Escolher três propriedades

Solicitação

Resposta

Exemplo 3: Comportamento de resposta mínimo alternativo

Solicitação

Resposta

Confira também

Comentários