Usando a pasta do aplicativo no OneDrive e no SharePoint

A pasta do aplicativo é uma das pastas especiais expostas por meio do caminho no OneDrive e no /special SharePoint. Projetado principalmente como um local para armazenar configurações de aplicativo no OneDrive de um usuário, ele pode ser aplicado a muitos cenários. Este artigo discute a pasta do aplicativo, a segurança e como você pode usá-la em seus aplicativos.

Com suporte de um escopo dedicado, Files.ReadWrite.AppFoldero , você pode criar aplicativos consistentes com privilégios mínimos para compartilhar dados entre experiências de dispositivo.

Pasta do aplicativo Acessar

Para começar, você precisa de um aplicativo do Microsoft Entra ID consentido com o Files.ReadWrite.AppFolder escopo. As permissões de aplicativo e delegadas têm suporte, conforme necessário para seu cenário.

Para acessar uma pasta do aplicativo, faça uma chamada no Microsoft Graph para:

GET /{drive_Resource}/special/approot

Importante

O nome approot diferencia maiúsculas de minúsculas.

Na primeira vez que você solicitar a pasta, ela será criada se não existir. Todas as pastas especiais são criadas dentro da unidade de destino com o caminho Apps/{Entra ID application name}, o que significa que se seu aplicativo for chamado de "My Amazing App", o caminho resultante dentro da unidade será Apps/My Amazing App.

A resposta é um driveItem que representa a pasta, com as facetas folder e specialFolder presentes. Este item da unidade permite que você execute todas as operações esperadas na pasta do seu aplicativo, incluindo o upload de arquivos, a listagem de filhos e o compartilhamento de arquivos contidos.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('c9d6a7bd-c1e0-4cb6-bf3c-48bf6dc571ad')/drive/special/$entity",
  "id": "692b2511-cca3-487d-b972-e6487bba0aff",
  "lastModifiedDateTime": "2023-12-12T19:33:45Z",
  "webUrl": "https://contoso-my.sharepoint.com/personal/someone_contoso_com/Documents/Apps/MyApp",
  "size": 0,
  "folder": {
    "childCount": 0
  },
  "specialFolder": {
    "name": "approot"
  }
}

Vantagens da pasta do aplicativo

Uma pasta de aplicativo oferece vários benefícios, dependendo do cenário, sendo a principal vantagem a capacidade de acessar facilmente a pasta por meio de um caminho constante. Por exemplo, para acessar a pasta do aplicativo de um usuário, você sempre pode usar https://{graph}/me/special/approoto , sem a necessidade de rastrear IDs ou caminhos para usuários individuais.

A pasta do aplicativo não funciona apenas para o OneDrive; você também pode usá-lo com qualquer recurso de unidade, incluindo bibliotecas do SharePoint. Nesse caso, você precisa do caminho completo para a unidade, usando a ID da unidade.

GET /drives/{drive_Id}/special/approot

Os sites também têm uma unidade padrão. Use a seguinte URL de solicitação para acessá-la:

GET /sites/{site_Id}/drive/special/approot

Observação

É possível, por mais raro que seja, que a unidade padrão de um site não exista mais. Sua inscrição deve levar em conta essa possibilidade.

A solicitação anterior cria uma Apps pasta na raiz da biblioteca com uma pasta dentro, com o nome do seu aplicativo.

Outra vantagem importante das pastas de aplicativos é o isolamento. Os arquivos do seu aplicativo são armazenados em um local exclusivo para garantir que eles não sobrecarreguem o OneDrive de um usuário ou sejam excluídos acidentalmente. Criar uma pasta do aplicativo permite um espaço seguro para manter arquivos específicos do aplicativo fora da estrutura de pastas raiz do OneDrive, mantendo as coisas mais limpas para os usuários.

A pasta do aplicativo funciona no OneDrive corporativo ou de estudante e no OneDrive para uso doméstico, garantindo que você possa fornecer uma experiência consistente para todos os usuários.

A pasta do aplicativo também usa permissões mínimas para salvar arquivos, o que é abordado em detalhes na próxima seção.

Segurança

A criação de aplicativos seguros é fundamental para criar confiança. Muitas vezes, os aplicativos do SharePoint ou do OneDrive têm permissões amplas, que podem ser limitadas usando permissões de aplicativo do SharePoint, mas essa limitação requer configuração e altos privilégios para atribuir. Com a pasta aplicativo, nenhum trabalho extra é necessário depois que o aplicativo é consentido em usar Files.ReadWrite.AppFolder. O serviço limita automaticamente o acesso a uma única pasta, garantindo que seu aplicativo tenha acesso apenas aos arquivos dessa pasta.

Observação

Um usuário sempre tem controle total de seu próprio OneDrive e pode adicionar ou remover arquivos da pasta do aplicativo. Se um usuário adicionar um arquivo à pasta, seu aplicativo obterá acesso a esse arquivo. O controle está na pasta, não em arquivos individuais carregados pelo seu aplicativo.

Além disso, Files.ReadWrite.AppFolder tem suporte em padrões de autenticação delegados e somente aplicativo. Usá-lo com padrões delegados é ideal para acessar arquivos do usuário, e os padrões de aplicativo permitem processar informações armazenadas em pastas criadas pelo aplicativo.

Delegated

O uso mais comum da pasta do aplicativo é a autenticação delegada para armazenar informações no OneDrive do usuário. Essa abordagem cruza as permissões do usuário com as do aplicativo, garantindo que um usuário só possa gravar em seu próprio OneDrive e apenas na pasta do aplicativo.

Somente aplicativo

Com permissões de aplicativo, o aplicativo pode acessar todas as pastas de aplicativo associadas a si mesmo. Como nenhum usuário está presente, o /me/drive/special/approot caminho não está disponível e você deve usá-lo /drives/{drive id}/special/approot para acessar o OneDrive do usuário.

Outras considerações

Com o uso da pasta do aplicativo, você terá algumas outras considerações a serem lembradas ao decidir sobre a solução certa:

  • A pasta do aplicativo conta de acordo com a cota: a cota do OneDrive de um usuário ou a cota de uso de um site do SharePoint. Colocar arquivos grandes na pasta do aplicativo pode causar problemas para os usuários. A pasta do aplicativo é ideal para armazenar arquivos de configuração, armazenamento temporário ou rascunhos.
  • Considere a sua experiência de usuário esperada. Se os usuários precisarem acessar esses arquivos com frequência ou interagir com eles fora do seu aplicativo, Files.ReadWrite podem Files.ReadWrite.All ser opções melhores, permitindo que você apresente uma experiência salvar como e dando aos usuários a capacidade de escolher onde armazenar seus arquivos.
  • Lembre-se de que um usuário pode excluir, editar ou substituir qualquer arquivo em seu próprio OneDrive. Embora seja improvável, seu aplicativo deve levar em conta essa possibilidade e não depender desses arquivos ou esperar que eles sempre existam. Aplicativos com acesso ao OneDrive completo também podem acessar os arquivos da pasta do aplicativo; Preste atenção aos tipos de informações que você está armazenando.

Cenários

Muitos cenários podem se beneficiar imediatamente do uso dos recursos da pasta do aplicativo e do acesso com privilégios mínimos para arquivos de leitura/gravação. Os cenários a seguir fornecem exemplos para você começar a usar as pastas do aplicativo.

Configuração do usuário

Os usuários acessam seu aplicativo do Teams, SharePoint, dispositivos móveis e desktop e precisam armazenar preferências e configurações. Usando a pasta do aplicativo, você pode armazenar facilmente arquivos de configuração e acessá-los de qualquer dispositivo. Tornando as configurações do usuário facilmente portáteis e sempre acessíveis com um caminho conhecido. Você também pode armazenar vários arquivos de configurações se der suporte a diferentes recursos de dispositivo.

Assinatura eletrônica

A assinatura eletrônica de documentos pode levar tempo, dificultando a persistência de um token de acesso do usuário para gravar o documento assinado de volta no OneDrive. Com a pasta do aplicativo somente aplicativo, você sempre pode gravar o documento assinado usando permissões mínimas para garantir que os arquivos do usuário permaneçam seguros.

Rascunhos privados

Talvez seu aplicativo envie mensagens ou seja usado para fazer anotações ou escrever documentos; No entanto, os usuários precisam de uma maneira de armazenar rascunhos antes de enviá-los ao seu destino final. Você pode usar a pasta do aplicativo para armazenar fragmentos e rascunhos facilmente por usuário, fornecendo acesso entre dispositivos para garantir consistência e satisfação do usuário.

Resumo

A pasta do aplicativo é uma maneira flexível e robusta de armazenar arquivos, sem comprometer as permissões mínimas. Fornecendo um caminho consistente e acessibilidade entre dispositivos, a pasta app é uma ótima opção para armazenar os arquivos do seu aplicativo de forma segura e eficiente. Com suporte a padrões de autenticação delegada e somente para aplicativos, ele fornece flexibilidade em seu design, apoiado pelos recursos completos do Microsoft Graph e Microsoft 365.

  • Last updated on