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

Artigo
04/08/2023

O passo a passo abaixo mostra como integrar o SDK do seletor de arquivos ao aplicativo cliente JavaScript.

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 abrir arquivos do 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.open(...), 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 launchOneDrivePicker(){
    var odOptions = { /* ... specify the desired options ... */ };
    OneDrive.open(odOptions);
  }
</script>
<button onClick="launchOneDrivePicker()">Open from OneDrive</button>

Observação: Quando o seletor do OneDrive for aberto, uma nova janela com a página será aberta e o SDK usará uma cadeia de caracteres de consulta para redirecionar a janela para o seletor. Se o SDK não estiver presente na página que está sendo carregada (se o carregamento estiver lento em resposta a uma interação do usuário, por exemplo), o seletor de não pode abrir corretamente. Você poderá usar a redirectUri opção avançada para redirecionar o pop-up para uma página que carregue o SDK sem nenhuma interação do usuário.

Opções do seletor

Você pode especificar como o seletor de arquivos se comporta 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: "query",
  multiSelect: true,
  advanced: {},
  success: function(files) { /* success 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 `share` para gerar uma URL compartilhável, `download` para receber uma URL de curta duração que baixa o conteúdo dos arquivos, ou `query` para retornar identificadores que podem ser usados com a API do Microsoft Graph ou a API do OneDrive.
multiSelect	O valor padrão é false, que exige que o usuário selecione um arquivo único somente ou true para permitir que o usuário selecione vários arquivos.
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 Opções avançadas para obter mais detalhes.
success	Chamado quando o usuário termina de escolher arquivos e exige um objeto de resposta que inclui a coleção de arquivos selecionados. Isso é necessário se openInNewWindow for `true`.
cancel	Chamado se o usuário cancela o seletor. Essa função não usa parâmetros.
error	Chamado quando ocorre um erro no servidor ou o usuário não tem permissão para obter um link para o arquivo escolhido. Esta função usa um parâmetro, um objeto de erro.

Tipos de ações

Usando o parâmetro action do seletor, você pode especificar qual tipo de URL deve ser retornado depois que o usuário seleciona um arquivo ou pasta. Os seguintes valores são permitidos:

Valor	Descrição
`download`	Retorna a ID do arquivo, o nome e uma URL de download de curta duração para os arquivos selecionados.
`share`	Retorna uma URL de compartilhamento de somente leitura para os arquivos selecionados que podem ser compartilhados com outros usuários.
`query`	Retorna metadados somente para os arquivos selecionados. Use a API para executar ações adicionais nos arquivos de acordo.

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.

{
  "value": [
    {
      "id": "123456",
      "name": "document1.docx",
      "size": 12340,
      "@microsoft.graph.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/..." }
        }
      ]
    }
  ],
  "accessToken": "ey...",
  "apiEndpoint": "https://graph.microsoft.com"
}

Propriedades de resposta

Nome da propriedade	Tipo	Descrição
value	Matriz de driveItems	Metadados sobre os arquivos que foram selecionados.
webUrl	URL	Retornado para vários cenários de seleção de contas do OneDrive Personal.
accessToken	string	O token de acesso recebido pelo seletor de arquivos para seu aplicativo. Isso pode ser usado para fazer solicitações adicionais para o Microsoft Graph sem a necessidade de outro fluxo de autenticação.
apiEndpoint	URL	Ponto de extremidade da API com o qual o accessToken pode ser usado.

Opções avançadas

O seletor também oferece suporte a cenários avançados adicionais. Isso permite que o seletor seja usado junto com a API do OneDrive para criar cenários avançados.

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

Nome do parâmetro	Descrição	Cenários
queryParameters	Um conjunto de parâmetros de consulta adicionais conforme especificado pela API do OneDrive que define como um item é retornado. Isso geralmente inclui selecionar e/ou expandir o valor.	Consultar um arquivo ou pasta
createLinkParameters	Altera os parâmetros usados para gerar um link para a ação de compartilhamento.	Compartilhar um arquivo
filter	Um conjunto de tipos de arquivo pode ser aplicado para exibir apenas os tipos específicos. Oferecemos suporte para o tipo de sistema 'foto' e 'pasta' e tipos personalizados de qualquer extensão como '. docx'. Uma configuração do filtro aplicável é "pasta,. png", em que cada filtro é separado por um `,`.	Exibir arquivos
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 ser registrada no portal de registro do seu aplicativo como uma URL de redirecionamento. A página de destino deve fazer referência ao SDK do seletor do OneDrive da mesma forma que a página de chamada.	OAuth
endpointHint	A dica de ponto de extremidade é usada para o SDK redirecionar o aplicativo para o ponto de extremidade OAuth direito com base em com quais pontos de extremidade da API do OneDrive o aplicativo quer se comunicar. Os pontos de extremidade da API do OneDrive API incluem OneDrive Personal, OneDrive for Business ou SharePoint Online. O valor de `endpointHint` poderia ser `api.onedrive.com` para OneDrive Personal, a URL do OneDrive for Business ou URL da biblioteca de documentos SharePoint, por exemplo `https://contoso-my.sharepoint.com/personal/foo_contoso_onmicrosoft_com/` ou `https://contoso.sharepoint.com/shared%20documents/`. Não é necessário se o aplicativo se comunica com a API do Microsoft Graph.	OAuth
accessToken	Um acesso accessToken concedido a pontos de extremidade da API do OneDrive para OneDrive – Pessoal, OneDrive for Business ou SharePoint Online pode ser pulado no fluxo OAuth, o que proporciona uma experiência mais rápida. O `endpointHint` é necessário se um accessToken for apresentado.	OAuth
loginHint	Se um usuário já fez login no seu aplicativo, você pode fornecer um valor loginHint que permitirá o logon único.	OAuth
isConsumerAccount	Quando se comunica com a API do Microsoft Graph e o `loginHint` especificado, o SDK também exige que o aplicativo diga se o usuário conectado é uma conta de consumidor (ou seja, Microsoft Account) ou uma conta comercial.	OAuth
scopes	O SDK automaticamente solicitará o escopo `Files.Read.All` para abrir fluxos e `Files.ReadWrite.All` para salvar fluxos. No entanto, se desejar solicitar permissões adicionais, você pode adicionar escopos adicionais aqui.	OAuth
navigation	No SDK do Seletor 7.2 apresentamos a nova UI do seletor que pode apresentar várias configurações. Todas as configurações estão sob o objeto `navigation`.	UI do seletor

Observação: Atualmente, o tipo de filtro 'foto' só é suportado para contas do OneDrive Personal.

Usar o seletor e a API juntos

Você pode usar o valor de açãoquery juntamente com a configuração do queryParameters do objeto avançado para retornar um conjunto de propriedades personalizado da API sobre o objeto selecionado. Por exemplo, quando um arquivo é escolhido, para incluir detalhes da foto (se disponível):

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "query",
  multiSelect: false,
  advanced: {
    queryParameters: "select=id,name,size,file,folder,photo,@microsoft.graph.downloadUrl",
    filter: "folder,.png" /* display folder and files with extension '.png' only */
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

Isso informa ao SDK do seletor as propriedades de id, nome, tamanho, arquivo, pasta, e foto na resposta.

Retornar um link compartilhável de leitura e gravação da empresa

Por padrão, o seletor de arquivos do OneDrive retorna uma URL de compartilhamento somente para exibição quando a ação está definida como share. No entanto, você pode usar a propriedade createLinkParameters para alterar os parâmetros passados para a ação createLink.

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "share",
  multiSelect: false,
  advanced: {
    createLinkParameters: { type: "edit", scope: "organization" }
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

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",
  advanced: {
    redirectUri: "https://contoso.com/filePickerRedirect.htm"
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

Usar pontos de extremidade de API alternativos

A API do Microsoft Graph API fornece acesso unificado a arquivos armazenados no OneDrive Personal, OneDrive for Business e SharePoint Online. No entanto, em alguns cenários limitados, pode ser necessário usar uma URL específica do site do SharePoint em vez do Microsoft Graph.

Nesse caso, o aplicativo pode especificar o ponto de extremidade da API do OneDrive para o site do SharePoint, em vez do ponto de extremidade da API do Microsoft Graph. O SDK do Seletor do OneDrive redirecionará para o ponto de extremidade de OAuth direito para obter um token de acesso. O mapeamento entre os pontos de extremidade da API do OneDrive e a autoridade OAuth é:

Ponto de extremidade de API	Ponto de extremidade de OAuth	`endpointHint`
https://graph.microsoft.com/v1.0/	https://login.microsoftonline.com/common/oauth2/v2.0/authorize	N/D
https://api.onedrive.com/v1.0/	https://login.live.com/oauth20_authorize.srf	https://api.onedrive.com
https://contoso-my.sharepoint.com/personal/ryan_contoso_com/	https://login.microsoftonline.com/common/oauth2/authorize	https://contoso-my.sharepoint.com/personal/ryan_contoso_com/

Redireciona para o ponto de extremidade de OAuth MSA

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "query",
  advanced: {
    endpointHint: "api.onedrive.com",
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

Redireciona diretamente para a biblioteca de documentos, e o aplicativo controla o fluxo OAuth em outro lugar.

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "download",
  advanced: {
    endpointHint: "https://contoso.sharepoint.com/shared%20documents/",
    accessToken "INSERT-ACCESS-TOKEN-HERE"
  },
  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>

Personalizar recursos

Enquanto o seletor de arquivos permite aos usuários selecionar arquivos de todo o Office 365, incluindo bibliotecas de documentos do OneDrive e SharePoint, você pode restringir a origem de onde um arquivo pode ser aberto. Você pode usar essas propriedades para restringir os recursos apenas àqueles que você deseja habilitar:

Nome do parâmetro	Descrição
disable	Se este valor estiver definido, o painel de navegação não aparecerá.
entryLocation	Configure a biblioteca de documentos processada na IU do seletor do OneDrive.
sourceTypes	Fontes de arquivos que o usuário pode selecionar no painel de navegação.

O aplicativo pode especificar sourceTypes como OneDrive, Recent, Sites ou várias fontes em uma matriz [`OneDrive`, `Recent`]. O aplicativo também pode especificar um local de entrada personalizado em vez de padrão especificando o objeto entryLocation. O local de entrada personalizada está limitado a uma biblioteca de documentos do SharePoint. O local de entrada padrão é o OneDrive for Business do usuário.

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "download",
  advanced: {
    navigation: {
      entryLocation: {
        sharePoint: {
          sitePath: "THE-SITE-PATH",
          listPath: "THE-LIST-PATH",
          itemPath: "THE-ITEM-PATH"
        }
      },
      sourceTypes: "Sites" /* or an array like ["OneDrive", "Sites"] */
    }
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }

Compartilhar via