group: delta

Namespace: microsoft.graph

Obtenha grupos recém-criados, atualizados ou excluídos, incluindo alterações de associação de grupo, sem precisar executar uma leitura completa de toda a coleção de grupos. Consulte Usando a Consulta Delta para obter detalhes.

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

GET /groups/delta

Parâmetros de consulta

Controlar alterações em grupos resulta em uma rodada de uma ou mais chamadas de função delta. Se você usar qualquer parâmetro de consulta (diferente de $deltatoken e de $skiptoken), especifique na solicitação inicial delta. O Microsoft Graph codifica automaticamente os parâmetros especificados para a parte de token da URL @odata.nextLink ou @odata.deltaLink fornecida na resposta.

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

Parâmetros de consulta OData

Esse método dá suporte a parâmetros de consulta OData opcionais 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.
  • Você pode usar para $select=members obter alterações de associação. Além disso, você pode acompanhar outras alterações, como propriedade e muito mais, selecionando qualquer relação de grupo do tipo coleção directoryObject.
  • 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/v1.0/groups/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 bem-sucedido, este método retorna o código de resposta 200 OK e uma coleção de objetos group no corpo da resposta. A resposta também inclui um token de estado que é uma @odata.nextLink URL ou uma @odata.deltaLink URL.

  • 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 propriedade , conforme mostrado no segundo exemplo abaixo .

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 terceiro exemplo a seguir.

Exemplo

Solicitação 1

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/v1.0/groups/delta

Resposta 1

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.

Observe a presença da propriedade members@delta que inclui as IDs de objetos membro no grupo.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups","@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvY1FSSc_",
  "value":[
    {
      "createdDateTime":"2021-03-12T10:36:14Z",
      "description":"This is the default group for everyone in the network",
      "displayName":"All Company",
      "groupTypes": [
        "Unified"
      ],
      "mail": "allcompany@contoso.com",
      "members@delta": [
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "693acd06-2877-4339-8ade-b704261fe7a0"
        },
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "49320844-be99-4164-8167-87ff5d047ace"
        }
      ]
    }
  ]
}

Solicitação 2

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

GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,mailNickname

Resposta 2

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 @odata.deltaLink foi obtido.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "All Company",
      "description": null,
      "mailNickname": "allcompany@contoso.com"
    }
  ]
}

Solicitação 3

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/v1.0/groups/delta?$select=displayName,description,mailNickname
Prefer: return=minimal

Resposta 3

A seguir, um exemplo da resposta ao usar @odata.deltaLink obtido da inicialização de consulta. Observe que a propriedade mailNickname não foi incluída, ou seja, não foi alterada desde a última consulta delta; displayName e description 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/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "Everyone",
      "description": null
    }
  ]
}

Confira também