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.
Essa API está disponível nas seguintes implantações nacionais de nuvem.
Serviço global | Governo dos EUA L4 | GOVERNO DOS EUA L5 (DOD) | China operada pela 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Permissões
Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas 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 privilegiadas mais altas |
---|---|---|
Delegado (conta corporativa ou de estudante) | GroupMember.Read.All | Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, Group.ReadWrite.All |
Delegado (conta pessoal da Microsoft) | Sem suporte. | Sem suporte. |
Application | GroupMember.Read.All | Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, Group.ReadWrite.All |
Solicitação HTTP
Para começar a acompanhar as alterações, você faz uma solicitação e inclui a função delta no recurso de grupos.
GET /groups/delta
Parâmetros de consulta
O acompanhamento de alterações em grupos 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
), especifique-o na primeira solicitação delta. O Microsoft Graph codifica automaticamente todos os parâmetros especificados na parte do 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 @odata.deltaLink URL da chamada de função delta anterior para a mesma coleção de grupo, indicando a conclusão dessa rodada de rastreamento 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 desse conjunto. |
$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 opcionais 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. - Você pode usar
$select=members
para 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 da coleção type 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.
- A única expressão
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 |
Preferir | return=minimal Especificar esse cabeçalho com uma solicitação que usa @odata.deltaLink retorna somente as propriedades do objeto que foram alteradas desde a última vez. 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á mais páginas de dados a serem recuperadas na sessão. O aplicativo continua fazendo solicitações usando a URL
@odata.nextLink
até uma URL@odata.deltaLink
ser incluída 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.
- Isso indica que há mais páginas de dados a serem recuperadas na sessão. O aplicativo continua fazendo solicitações usando a URL
Se uma URL
@odata.deltaLink
for retornada:- Isso indica que não há mais dados sobre o estado existente do recurso a ser retornado. 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.
- Isso indica que não há mais dados sobre o estado existente do recurso a ser retornado. Salve e use a URL
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 tiver sido 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 tiver sido alterada, a propriedade não será incluída na resposta. (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
O exemplo a seguir mostra uma solicitação. Não há parâmetro $select
, portanto, um conjunto padrão de propriedades é rastreado e retornado.
GET https://graph.microsoft.com/v1.0/groups/delta
Resposta 1
Aqui está um exemplo da resposta ao usar @odata.deltaLink
obtido da inicialização da 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 membros 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 a solicitação inicial selecionando três propriedades para controle de alterações, com comportamento de resposta padrão:
GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,mailNickname
Resposta 2
Aqui está um exemplo da resposta ao usar @odata.deltaLink
obtido da inicialização da consulta. Todas as três propriedades estão incluídas na resposta e não se sabe quais foram alteradas desde que a @odata.deltaLink
foi obtida.
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 próximo exemplo mostra a solicitação inicial selecionando três propriedades para controle de alterações, com um comportamento de resposta mínimo alternativo:
GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,mailNickname
Prefer: return=minimal
Resposta 3
Aqui está um exemplo da resposta ao usar @odata.deltaLink
obtido da inicialização da consulta. A mailNickname
propriedade não está incluída, o que significa que ela não foi alterada desde a última consulta delta; displayName
e description
está incluída, o que significa que seus 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
}
]
}