group: delta
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.
Obtenha grupos recentemente criados, atualizados ou eliminados, incluindo alterações de associação a grupos, sem ter de efetuar uma leitura completa de toda a coleção de grupos . Para obter mais informações, consulte Utilizar a consulta delta para controlar as alterações nos dados do Microsoft Graph para obter detalhes.
Esta API está disponível nas seguintes implementações de cloud nacionais.
Serviço global | US Government L4 | US Government L5 (DOD) | China operada pela 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Permissões
Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.
Tipo de permissão | Permissões com menos privilégios | Permissões com privilégios superiores |
---|---|---|
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 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
O registo de alterações em grupos implica uma ronda 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 devolvido no @odata.deltaLink URL da chamada de função delta anterior para a mesma coleção de grupo, indicando a conclusão dessa ronda de controlo 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
Este método suporta 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. - Pode utilizar
$select=members
para obter alterações de associação. Além disso, pode controlar outras alterações, como a propriedade e muito mais, selecionando qualquer relação de grupo do tipo directoryObject collection. - Existe 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/groups/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'
. Existe 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 é um @odata.nextLink
URL ou um @odata.deltaLink
URL.
Se uma URL
@odata.nextLink
for retornada:- Isto indica que há mais páginas de dados a obter 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.
- Isto indica que há mais páginas de dados a obter na sessão. O aplicativo continua fazendo solicitações usando a URL
Se uma URL
@odata.deltaLink
for retornada:- Isto indica que não existem mais dados sobre o estado existente do recurso a ser devolvido. 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.
- Isto indica que não existem mais dados sobre o estado existente do recurso a ser devolvido. 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 existe nenhum $select
parâmetro, pelo que um conjunto predefinido de propriedades é controlado e devolvido.
GET https://graph.microsoft.com/beta/groups/delta
Resposta 1
Eis um exemplo da resposta ao utilizar @odata.deltaLink
obtido a partir da inicialização da consulta.
Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.
Tenha em atenção a presença da propriedade members@delta que inclui os IDs dos objetos membros no grupo.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
"@odata.nextLink":"https://graph.microsoft.com/beta/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 exemplo seguinte mostra o pedido inicial a selecionar três propriedades para controlo de alterações, com o comportamento de resposta predefinido:
GET https://graph.microsoft.com/beta/groups/delta?$select=displayName,description,mailNickname
Resposta 2
Eis um exemplo da resposta ao utilizar @odata.deltaLink
obtido a partir da inicialização da consulta. As três propriedades estão incluídas na resposta e não se sabe quais foram alteradas desde que foi @odata.deltaLink
obtida.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
"@odata.nextLink":"https://graph.microsoft.com/beta/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
"value": [
{
"displayName": "All Company",
"description": null,
"mailNickname": "allcompany@contoso.com"
}
]
}
Solicitação 3
O exemplo seguinte mostra o pedido inicial a selecionar três propriedades para o controlo de alterações, com um comportamento de resposta mínimo alternativo:
GET https://graph.microsoft.com/beta/groups/delta?$select=displayName,description,mailNickname
Prefer: return=minimal
Resposta 3
Eis um exemplo da resposta ao utilizar @odata.deltaLink
obtido a partir da inicialização da consulta. A mailNickname
propriedade não está incluída, o que significa que não foi alterada desde a última consulta delta; displayName
e description
estão incluídas, o que significa que os respetivos valores foram alterados.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
"@odata.nextLink":"https://graph.microsoft.com/beta/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
"value": [
{
"displayName": "Everyone",
"description": null
}
]
}