Compartilhar via

Salvar arquivos com o SDK do Seletor de Arquivos do OneDrive para JavaScript v7.2

  • Artigo

Para salvar arquivos do OneDrive, o aplicativo deve fornecer um botão para iniciar a experiência do seletor do OneDrive via programação.

1. Registrar o aplicativo

Para usar o seletor do OneDrive, você precisa registrar seu aplicativo por meio da página Azure App registros e receber uma ID do Aplicativo. Você também precisa adicionar um URI de redirecionamento válido para seu aplicativo Web usando o seletor. As opções são: a página que está hospedando o SDK do seletor ou uma URL personalizada definida por você. Para saber mais, confira Configuração.

2. Adicionar uma referência ao SDK

Incorpore o SDK do OneDrive para JavaScript na sua página.

<script type="text/javascript" src="https://js.live.net/v7.2/OneDrive.js"></script>

3. Iniciar o seletor de arquivos

Para salvar arquivos no OneDrive, o aplicativo deve fornecer um botão para abrir o seletor de arquivos do OneDrive de forma programática. Como este código iniciará uma janela suspensa no navegador, ela precisa ser chamada como parte de uma ação explícita do usuário para evitar o bloqueio por um bloqueador de pop-up.

Como parte do método OneDrive.save(...), você especifica as opções de como o seletor deve se comportar e como o seletor chamará de volta ao seu código por meio de um objeto de opções.

<script type="text/javascript">
  function launchSaveToOneDrive(){
    var odOptions = { /* ... specify the desired options ... */ };
    OneDrive.save(odOptions);
  }
</script>

<input id="fileUploadControl" name="fileUploadControl" type="file" />
<button onclick="launchSaveToOneDrive">Save to OneDrive</button>

Opções do seletor

Você pode especificar como o seletor de arquivos se comporta ao salvar arquivos fornecendo um objeto com parâmetros que controlam o comportamento do seletor. Esse objeto também inclui as funções de retorno de chamada para quando o seletor de arquivos é concluído ou encontra um erro.

Exemplo de opções do seletor de arquivos

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "save",
  sourceInputElementId: "fileUploadControl",
  sourceUri: "",
  fileName: "file.txt",
  openInNewWindow: true,
  advanced: {},
  success: function(files) { /* success handler */ },
  progress: function(percent) { /* progress handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

Parâmetros

Nome do parâmetro Descrição
clientId A ID do aplicativo, gerada pelo console de registro do aplicativo para a integração.
action O tipo de ação sendo executado com os arquivos selecionados. Você pode especificar save para salvar um arquivo diretamente no OneDrive, ou query para retornar identificadores que podem ser usados com a API do Microsoft Graph API ou a API do OneDrive para salvar uma pasta selecionada.
sourceInputElementId A ID do elemento da entrada de formulário (tipo = arquivo) para o arquivo a ser carregado.
sourceUri URI de dados, http ou https para o arquivo a ser carregado. O OneDrive for Business e o SharePoint oferecem suporte apenas para valores de URI de dados.
fileName Necessário se o parâmetro sourceUri for um URI de dados. Se não for fornecido, o nome do arquivo será inferido do nome do atributo do elemento de entrada.
openInNewWindow O valor padrão é true, que abre a experiência de seleção do OneDrive em uma janela pop-up. false abre a experiência de seleção do OneDrive na mesma janela.
viewType O tipo de item que pode ser selecionado. O valor padrão é files. É possível especificar folders para limitar a seleção a apenas pastas ou especificar all, o que permite a seleção de ambos arquivos e pastas.
accountSwitchEnabled O valor padrão é true, que renderiza a interface do usuário "Mudar de conta" na página do Seletor de Arquivos hospedada.
advanced Um conjunto de propriedades adicionais que podem personalizar ainda mais o comportamento do seletor, mas não são necessárias para a maioria dos cenários. Confira Cenários de armazenamento avançados para obter mais detalhes.
nameConflictBehavior Um parâmetro opcional passado para a situação quando um arquivo de carregamento tem conflito de nome com o arquivo na pasta de destino. Confira a definição de parâmetro para obter mais detalhes.
success Chamado quando o carregamento do arquivo para o servidor é concluído. O parâmetro de arquivos é uma coleção de metadados retornados pelo serviço para o arquivo carregado.
progress Chamado em vários pontos com uma flutuação entre 0,0 e 100,0 para indicar o progresso do carregamento. Ele é chamado pelo menos uma vez com 100,0.
cancel Chamado se o usuário cancela o armazenamento.
error Chamado quando há um erro no servidor, o usuário está fora da cota, o usuário não tem permissão para carregar para o local escolhido ou o usuário não selecionou um arquivo a ser carregado.

Observação: Se openInNewWindow for false, todas as funções de retorno de chamada deverão ser declaradas globalmente na página antes que o SDK seja referenciado para garantir que as funções sejam chamadas. Quando registrados globalmente os nomes das funções de retorno de chamada são renomeados com um prefixo oneDriveFilePicker. Por exemplo, success torna-se oneDriveFilePickerSuccess.

Tipos de ações

Usando o parâmetro action do seletor do SDK você pode especificar como o seletor se comporta. Os seguintes valores são permitidos para a ação save():

Valor Descrição
save Salva o arquivo fornecido por sourceInputElementId ou sourceUri na pasta selecionada no OneDrive do usuário.
query Retorna metadados da API sobre a pasta selecionada. Então o aplicativo carrega um ou mais arquivos na pasta selecionada pelo usuário.

4. Manipular o objeto de resposta do seletor

Quando o usuário acaba de selecionar o(s) arquivo(s), o retorno de chamada success recebe o objeto response. Esse objeto contém propriedades, inclua valor propriedade que é uma coleção de recursos de item com um subconjunto de propriedades do item.

Ao usar a ação save, esta coleção fornece os metadados do item para o arquivo recém-carregado. Para a ação query, essa coleção conterá metadados para a pasta selecionada.

Exemplo ao carregar um documento

{
  "value": [
    {
      "id": "123456",
      "name": "document1.docx",
      "size": 12340,
      "@content.downloadUrl": "https://contoso-my.sharepoint.com/download.aspx?guid=1231231231a",
      "webUrl": "https://cotoso-my.sharepoint.com/personal/user_contoso_com/documents/document1.docx",
      "thumbnails": [
        {
          "id": "0",
          "small": { "url": "https://sn3302files.onedrive.live.com/..." },
          "medium": { "url": "https://sn3302files.onedrive.live.com/..." },
          "large": { "url": "https://sn3302files.onedrive.live.com/..." }
        }
      ]
    }
  ]
}

Exemplo ao usar query para salvar para uma pasta

{
  "value": [
    {
      "id": "1234567!12",
      "name": "Project Vroom",
      "webUrl": "https://cotoso-my.sharepoint.com/personal/user_contoso_com/documents/project%20vroom",
      "folder": { "childCount": 4 }
    }
  ]
}

Cenários de salvamento avançados

O parâmetro avançado no objeto de opções tem as seguintes propriedades definidas:

Nome do parâmetro Descrição
redirectUri Por padrão, o seletor usa a página em que foi lançado como o URI de redirecionamento para autenticação. Isso pode não ser desejável em todos os cenários, então você pode configurar uma URL personalizada para usar em vez disso. Esta URL deve estar no mesmo domínio raiz e usar o mesmo protocolo que a página que hospeda o SDK do seletor. A página de destino deve fazer referência ao SDK do seletor do OneDrive da mesma forma que a página de chamada.

Usar um URI de redirecionamento personalizado

Se o seu aplicativo for um grande aplicativo de JavaScript do lado do cliente ou usar parâmetros de sequência de consulta para manter o estado, talvez não seja desejável usar a página que inicializa o seletor de arquivos como o URI de redirecionamento. Isso exige que todo o aplicativo seja recarregado dentro da janela pop-up, o que pode causar problemas de desempenho. Você pode especificar um URI de redirecionamento alternativo por meio do objeto avançado que é usado em vez disso.

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "download",
  openInNewWindow: true,
  advanced: {
    redirectUri: "https://contoso.com/filePickerRedirect.htm"
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

A página que você redireciona precisa apenas carregar o script do SDK do OneDrive:

<html>
<script type="text/javascript" src="https://js.live.net/v7.2/OneDrive.js"></script>
</html>

Observação: só é possível fornecer um URI de redirecionamento personalizado ao usar o selecionador de arquivo como uma janela pop-up (openInNewWindow é true). Ao usar a experiência em linha, o URI de redirecionamento padrão é sempre usado.