Práticas recomendadas para descobrir arquivos e detectar alterações em escala

O Microsoft Office SharePoint Online e o OneDrive armazenam milhões de arquivos. É fundamental usar os padrões de chamada corretos ao tentar entender todos os arquivos e alterações em escala. Historicamente, há muitas APIs para acessar arquivos em um nível atômico. Muitas dessas APIs não são eficientes em grande escala, mas funcionam bem para uma única interação do usuário. Essas diretrizes explicam como monitorar um locatário do Office 365 ou o OneDrive para que seu aplicativo se integre ao Office 365 com o máximo de desempenho e eficiência. Os aplicativos que normalmente têm esse tipo de necessidade são mecanismos de sincronização, provedores de backup, indexadores de pesquisa, mecanismos de classificação e provedores de prevenção contra perda de dados.

Obtendo as permissões corretas

Para criar confiança com os usuários, é importante usar o conjunto mínimo correto de escopos de permissão necessários para que um aplicativo funcione. A maioria dos aplicativos de verificação desejará operar com permissões de aplicativo, isso indica que seu aplicativo está sendo executado independentemente de qualquer usuário específico. Para acessar arquivos, você deve solicitar o escopo Files.Read.All ou Files.ReadWrite.All. Para obter acesso aos recursos do Microsoft Office SharePoint Online, incluindo a lista de todos os conjuntos de sites, Sites.Read.All ou Sites.ReadWrite.All é apropriado. Para processar as permissões corretamente, você também precisará solicitar Sites.FullControl.All.

Tipos de autorização, escopos de permissão e usuários

Ao configurar as permissões de um aplicativo no Microsoft Azure você pode escolher entre permissões de aplicativo e permissões delegadas. Conforme observado acima, a maioria dos aplicativos de verificação deseja permissões de aplicativo. As permissões delegadas exigem que seu aplicativo opere no contexto de um usuário conectado em vez de globalmente. No modelo delegado, você está restrito ao conteúdo ao qual o usuário atual tem acesso.

Um aspecto importante das permissões a serem observadas é que quando um administrador concede permissões a um aplicativo que solicita permissões de aplicativo (em vez de permissões delegadas), a concessão de permissão está sendo associada ao locatário e ao aplicativo, em vez do usuário administrador. Embora um administrador seja necessário para conceder o acesso, a concessão de acesso não confere permissões administrativas especiais ao aplicativo, além do acesso aos escopos de recurso solicitados pelo aplicativo.

Padrão de chamada recomendado

Para aplicativos que processam grandes quantidades de dados do Microsoft Office SharePoint Online e do OneDrive, você deve seguir um padrão de chamada consistente como o seguinte.

1. Descobrir – Configura os locais que você deseja verificar.
2. Rastrear – Descobre e processa todo o conjunto de arquivos nos quais você está interessado.
3. Notificar – Monitora as alterações nesses arquivos por meio de notificação.
4. Processar alterações – Reprocessa somente os arquivos que foram alterados usando a consulta delta.

O padrão será semelhante ao diagrama a seguir. Este artigo apresenta detalhes sobre cada etapa para implementação.

Cada um desses elementos pode ter vários mecanismos para fazer isso na API do Microsoft Graph e APIs existentes do Microsoft Office SharePoint Online. O objetivo deste artigo é fornecer a melhor maneira de concluir cada tarefa.

Descobrir locais para verificar

Configurar os locais que você deseja que seu aplicativo examine é um processo manual hoje. Em muitos casos, você desejará fornecer uma experiência de aplicativo voltada para o usuário para esta etapa; como você expõe essa funcionalidade e se ela é exposta a todos os usuários ou apenas administradores é sua compatibilidade. Você desejará determinar quais usuários OneDrives e quais conjuntos de sites e subsites do Microsoft Office SharePoint Online você está verificando.

O OneDrive de cada usuário contém um único drive que você pode monitorar. Os conjuntos de sites e subsites do Microsoft Office SharePoint Online podem ter várias unidades, uma para cada biblioteca de documentos no site. Você pode descobrir cada unidade em um site usando o ponto de extremidade /drives. Por exemplo, para obter todas as unidades no site raiz do locatário, você pode usar:

https://graph.microsoft.com/v1.0/sites/root/drives

A unidade é o ponto de partida para atividades de arquivo em grande escala. Você usará essas unidades para obter listas completas de arquivos, conectar webhooks para notificações e usar a consulta delta para obter conjuntos de alterações em itens nas unidades.

Como localizar conjuntos de sites do Microsoft Office SharePoint Online e unidades OneDrive for Business

Usando Microsoft Graph com permissões de aplicativo, você pode obter a lista completa de conjuntos de sites, incluindo sites que contêm unidades OneDrive for Business. Para obter essa lista, use a seguinte chamada à API:

GET /sites

A API de enumeração de sites também dá suporte à consulta delta para obter informações sobre novos sites criados ou alterações na estrutura do site. No momento, o suporte à consulta delta para enumeração de site está sendo distribuído para a versão Microsoft Graph Beta. Continue lendo para obter mais informações sobre a consulta delta.

Para receber notificações sobre novos conjuntos de sites, você pode assinar webhooks usando o ponto de extremidade assinaturas do Microsoft Graph. O recurso de destino para essas notificações é /sites. Você receberá notificações quando novos conjuntos de sites forem criados ou excluídos, bem como quando subsites ou listas forem criados.

Rastrear e processar usando a consulta delta

Para obter a lista inicial de arquivos em uma unidade, faça uma única chamada de consulta delta sem parâmetros. A consulta delta fornece aos aplicativos um rastreamento inicial de todo o conteúdo e, em seguida, alterações subsequentes de um ponto no tempo. A consulta delta retorna o link necessário para obter alterações futuras sempre que for chamada.

Por exemplo, se você quisesse obter todos os arquivos na biblioteca de documentos padrão em um site do Microsoft Office SharePoint Online, poderia usar esta consulta:

/sites/{siteId}/drive/root/delta

Essa API retorna páginas de resultados que representam todos os arquivos na unidade. Depois de recuperar todas as páginas de arquivos usando o retornado @odata.nextLink, você poderá fazer a consulta delta novamente com o retornado @odata.deltaLink para obter alterações desde a última vez que você chamou a consulta delta. Lembre-se sempre de manter a URL retornada para @odata.deltaLink que você possa verificar com eficiência as alterações posteriormente.

Os links retornados pela consulta delta terão esta aparência:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(driveItem)",
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?$select=*%2csharepointIds&token=MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM2NzExNzY2MzIxMDcwMDAwOzE5ODAzMzU5ODslMjM7JTIzOyUyMzQ",
    "value": [
        {
            "@odata.type": "#microsoft.graph.driveItem",
            "createdDateTime": "2017-07-27T02:41:36Z",
…
}

Para obter um exemplo mais detalhado, consulte a consulta delta documentação.

A consulta delta retorna uma matriz de driveItems. Se você souber antecipadamente que deseja informações específicas, poderá incluí-la em uma instrução com a consulta delta. Você também pode acompanhar a chamada delta com uma solicitação para um driveItem específico, caso precise dele. A consulta delta ainda ajudará a restringir o número de itens aos quais você precisa consultar alterações, tornando seu aplicativo mais eficiente.

Ser notificado sobre alterações usando webhooks

Para fazer o melhor uso da consulta delta para alterações que ocorrem em uma unidade, você precisa de uma estratégia eficaz para saber quando voltar e solicitar as alterações. No passado, você pode ter escrito seu aplicativo para sondar o OneDrive e o Microsoft Office SharePoint Online em algum intervalo fixo e enumerado as alterações por conta própria. Com a consulta delta, a parte de enumeração é feita para você, portanto, você só precisa saber quando voltar. Os webhooks permitem que você evite sondar o serviço e, em vez disso, recebem uma notificação quando algo foi alterado no qual você está interessado. Sondar o serviço repetidamente ou a altas taxas faz com que seu aplicativo seja limitado devido a padrões excessivos de chamada.

Os webhooks são anexados usando a API de assinaturas para Microsoft Graph. Você pode encontrar a documentação completa para webhooks Microsoft Graph e a API de Assinaturas no site do Microsoft Graph.

Você precisará criar uma assinatura associada a um recurso específico (nesse caso, uma unidade). As unidades dão suporte ao tipo de alteração "atualização" para webhooks. Uma "atualização" indica que o conteúdo dentro da unidade foi alterado ou que o novo conteúdo foi adicionado ou excluído. As assinaturas de webhook têm um tempo limite associado que precisa ser atualizado periodicamente. Consulte a documentação mencionada anteriormente sobre como atualizar suas assinaturas. É recomendável usar a consulta delta com seu último token de alteração imediatamente após assinar webhooks para garantir que você não perca as alterações que ocorreram entre o rastreamento inicial e a configuração de seus webhooks.

Mesmo com webhooks enviando notificações do aplicativo, talvez você queira fornecer uma consulta delta periódica para garantir que nenhuma alteração seja perdida se parece ter sido há muito tempo desde que uma notificação foi recebida. Recomendamos não mais do que uma vez por dia para essa verificação periódica. A consulta delta ainda permite que você se atualize facilmente e não perca nenhuma alteração no sistema.

Recebendo notificações de webhook para eventos de segurança

O OneDrive e o Microsoft Office SharePoint Online dão suporte ao envio de notificações de eventos de segurança ao aplicativo. Para assinar esses eventos, você precisará adicionar o cabeçalho "prefer:includesecuritywebhooks" a sua solicitação para registrar um webhook. Depois que o webhook for registrado, você receberá notificações quando as permissões em um item mudarem. Este cabeçalho é aplicável às contas Microsoft Office SharePoint Online e OneDrive for Business, mas não às contas OneDrive de consumo.

Processar alterações

Depois que seu aplicativo receber uma notificação por meio de um webhook, você precisará confirmar a notificação enviando imediatamente um código 202 aceito de volta para o Microsoft Graph. Você deve enviar esse código antes de iniciar qualquer processamento demorado. Não fazer isso resulta em tentativas adicionais sendo enviadas, que seu aplicativo pode exibir como notificações falsas.

Acompanhe a confirmação com uma consulta delta para as alterações mais recentes e seu aplicativo deve estar atualizado. Se você estiver esperando padrões de tráfego intensos em uma determinada unidade, considere chamar a consulta delta em um intervalo reduzido em vez de após cada notificação de alteração. Além disso, certifique-se de armazenar o novo valor retornado no parâmetro deltaLink para obter um novo token para chamar a API novamente.

Se o processamento exigir o download do conteúdo de um arquivo individual, você poderá usar a propriedade cTag para determinar se o conteúdo do arquivo foi alterado desde a última vez que o baixou. Depois de saber que deseja baixar o arquivo, você pode acessar a propriedade /content do DriveItem retornado em uma resposta de consulta delta.

Examinando hierarquias de permissões

Por padrão, a resposta da consulta delta incluirá informações de compartilhamento de itens, mesmo que eles herdem suas permissões do pai e não tenham alterações diretas de compartilhamento por conta própria. Observe que a resposta da consulta delta inclui apenas itens com alterações diretas em seu conteúdo ou metadados e a hierarquia pai dos itens alterados. Isso normalmente resulta em uma chamada de acompanhamento para obter os detalhes da permissão de cada item, e não apenas daqueles cujas informações de compartilhamento foram alteradas. Você pode otimizar sua compreensão de como as alterações de permissão ocorrem adicionando o cabeçalho "Prefer: hierarchicalsharing" a sua solicitação de consulta delta.

Quando o cabeçalho "Prefer: hierarchicalsharing" é fornecido, as informações de compartilhamento serão retornadas para a raiz da hierarquia de permissões, bem como os itens que explicitamente têm alterações de compartilhamento. Nos casos onde a mudança de compartilhamento é remover o compartilhamento de um item, você encontrará uma faceta de compartilhamento vazia para diferenciar entre os itens que herdam de seus pais e aqueles que são únicos, mas sem links de compartilhamento. Você também verá essa faceta de compartilhamento vazia na raiz de uma hierarquia de permissões que não é compartilhada para estabelecer o escopo inicial.

Em muitos cenários de verificação, você pode estar interessado especificamente em alterações nas permissões. Para deixar claro na resposta da consulta delta quais alterações são o resultado das permissões que estão sendo alteradas, você pode fornecer o cabeçalho "Prefer: deltashowsharingchanges". Quando esse cabeçalho for fornecido, todos os itens que aparecem na resposta da consulta delta devido a alterações de permissão terão a anotação OData "@microsoft.graph.sharedChanged":" True" presente ao chamar o Microsoft Graph, ao usar a API do Microsoft Office SharePoint Online ou do OneDrive diretamente, a anotação será "@oneDrive.sharedChanged":" True". Assim como os webhooks de segurança, esse recurso é aplicável ao Microsoft Office SharePoint Online e OneDrive for Business mas não às contas do OneDrive do consumidor.

O que acontece quando você é limitado?

Em alguns cenários, seu aplicativo pode obter uma resposta 429 ou 503 do Microsoft Graph. Isso indica que sua solicitação está sendo limitada no momento. Uma coisa a ter em mente é que o Microsoft Office SharePoint Online limita os aplicativos com base no uso de um aplicativo com cada locatário do cliente. Atender a uma solicitação de um recurso em um locatário fornecerá, de forma correspondente, menos recursos para fazer uma chamada a outro recurso para esse mesmo locatário. Por fim, pode haver vários motivos pelos quais seu aplicativo recebe uma resposta de limitação e é fundamental que seu aplicativo responda corretamente nessas situações.

Para recuperar-se de receber um código de resposta 429 ou 503, tente novamente depois de aguardar a duração especificada no campo Retry-After no cabeçalho da resposta. Se a limitação persistir, o valor Retry-After poderá se tornar mais longo ao longo do tempo, permitindo que o sistema se recupere. Os aplicativos que não respeitam a repetição após a duração antes da chamada de volta serão bloqueados devido a padrões de chamada abusivas.

Ao aguardar a recuperação 429 ou 503, você deve garantir que pause todas as solicitações adicionais que está fazendo no serviço. Isso é especialmente importante em cenários de vários threads. Fazer chamadas adicionais enquanto recebe respostas de aceleração estenderá o tempo que leva para que seu aplicativo fique desenfreado.

Para obter informações mais detalhadas sobre como os recursos do Microsoft Graph funcionam com a limitação, consulte as Diretrizes de limitação do Microsoft Graph.