Abrir archivos con el SDK del selector de archivos de OneDrive para JavaScript v7.2

Artículo
04/08/2023

En el siguiente tutorial se muestra cómo integrar el SDK del selector de archivos en la aplicación de JavaScript del lado cliente.

1. Registrar la aplicación

Para usar el selector de OneDrive, debe registrar la aplicación a través de la página de registros de App de Azure y recibir un identificador de aplicación. También debe agregar un URI de redireccionamiento válido para la aplicación web mediante el selector. Este puede ser la página que hospeda el SDK del selector o una dirección URL personalizada que defina. Para obtener más información, vea Configuración.

2. Agregar una referencia al SDK

Inserte el SDK de OneDrive para JavaScript en la página.

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

3. Iniciar el selector de archivos

Para abrir archivos desde OneDrive, la aplicación debe proporcionar un botón para abrir mediante programación el selector de archivos de OneDrive. Como este código iniciará una ventana emergente en el explorador, necesita llamarse como parte de una acción de usuario explícita para evitar que se bloquee mediante un bloqueador de elementos emergentes.

Como parte del método OneDrive.open(...), especifique las opciones de cómo debe comportarse el selector y cómo volverá a llamar a su código mediante un objeto de opciones.

<script type="text/javascript">
  function launchOneDrivePicker(){
    var odOptions = { /* ... specify the desired options ... */ };
    OneDrive.open(odOptions);
  }
</script>
<button onClick="launchOneDrivePicker()">Open from OneDrive</button>

Nota: cuando se abre el selector de OneDrive, se abrirá una ventana nueva con la página y el SDK usará una cadena de consulta para redirigir la ventana al selector. Si el SDK no está presente en la página al cargarse (si se carga de forma diferida en respuesta a una interacción del usuario, por ejemplo), puede que el selector no se abra correctamente. Puede que quiera usar la redirectUri opción avanzada para redirigir el menú emergente a una página que carga el SDK sin intervención del usuario.

Opciones del selector

Puede especificar cómo se comporta el selector de archivos proporcionando un objeto con parámetros que controlen el comportamiento del selector. Este objeto también incluye las funciones de devolución de llamada cuando el selector de archivos ha finalizado o detecta un error.

Ejemplo de la opciones del selector de archivos

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

Nombre del parámetro	Descripción
clientId	El id. de aplicación que se ha generado mediante la consola de registro de aplicaciones para su integración.
action	El tipo de acción que se realiza con los archivos seleccionados. Puede especificar `share` para generar una dirección URL que se puede compartir, `download` para recibir una dirección URL de corta duración que descarga el contenido de los archivos o `query` para devolver identificadores que pueden usarse con la API de Microsoft Graph o la API de OneDrive.
multiSelect	El valor predeterminado es False, que requiere al usuario seleccionar un único archivo, o True que permite al usuario seleccionar varios archivos.
viewType	El tipo de elemento que se puede seleccionar. El valor predeterminado es `files`. Puede especificar `folders` para limitar la selección a solo carpetas o especificar `all` que permite la selección de ambos archivos y carpetas.
accountSwitchEnabled	El valor predeterminado es `true`, que representa la interfaz de usuario "Cambiar cuenta" en la página hospedada de Selector de archivos.
advanced	Una colección de propiedades adicionales que pueden personalizar el comportamiento del selector, pero no son necesarias para la mayoría de los escenarios. Vea Opciones avanzadas para obtener más información.
success	Se llama cuando el usuario termina de seleccionar archivos y toma un objeto de respuesta que incluye la colección de los archivos seleccionados. Es necesario si openInNewWindow es `true`.
cancel	Se llama si el usuario cancela el selector. Esta función no toma ningún parámetro.
error	Se llama cuando se ha producido un error en el servidor o cuando el usuario no tiene permiso para obtener un vínculo en el archivo seleccionado. Esta función toma un parámetro, un objeto de error.

Tipos de acciones

Con el parámetro action del selector puede especificar qué tipo de dirección URL debe devolverse después de que el usuario seleccione un archivo o una carpeta. Se permiten los siguientes valores:

Valor	Descripción
`download`	Devuelve el id. de archivo, el nombre y una dirección URL de descarga de corta duración para los archivos seleccionados.
`share`	Devuelve una dirección URL de uso compartido de solo lectura para los archivos seleccionados que puede compartirse con otros usuarios.
`query`	Devuelve metadatos solo para los archivos seleccionados. Use la API para realizar acciones adicionales en los archivos según corresponda.

4. Controlar el objeto de respuesta del selector

Cuando el usuario haya terminado de seleccionar los archivos, la devolución de llamada success recibe un objeto response. Este objeto contiene propiedades, incluida la propiedad value que es una colección de recursos Item con un subconjunto de las propiedades del elemento.

{
  "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"
}

Propiedades de la respuesta

Nombre de la propiedad	Tipo	Descripción
value	Matriz de driveItems	Metadatos sobre los archivos que se han seleccionado.
webUrl	Url	Se devuelve para varios escenarios de selección desde las cuentas de OneDrive Personal.
accessToken	string	El token de acceso recibido mediante el selector de archivos para la aplicación. Puede usarse para realizar solicitudes adicionales a Microsoft Graph sin necesitar otro flujo de autenticación.
apiEndpoint	Url	El punto de conexión de API con el que puede usarse accessToken.

Opciones avanzadas

El selector también admite escenarios avanzados adicionales. Esto permite al selector usarse junto con la API de OneDrive para obtener escenarios avanzados.

El parámetro avanzado del objeto de opciones tiene las siguientes propiedades definidas:

Nombre del parámetro	Descripción	Escenarios
queryParameters	Un conjunto de parámetros de consulta adicionales como se ha especificado mediante la API de OneDrive que define cómo se devuelve un elemento. Normalmente incluye un valor de selección o expansión.	Consultar un archivo o carpeta
createLinkParameters	Se cambian los parámetros usados para generar un vínculo para la acción de compartir.	Compartir un archivo
filter	Un conjunto de tipos de archivo puede aplicarse para mostrar solo los tipos específicos. Admitimos el tipo de sistema "photo" y "folder", y tipos personalizados de cualquier extensión como ".docx". Una opción de filtro aplicable es "folder,.png" donde cada filtro está separado por una `,`.	Mostrar archivos
redirectUri	De manera predeterminada, el selector usa la página desde la que se ha iniciado como el URI de redireccionamiento para la autenticación. Esto puede no ser adecuado en todos los escenarios, por lo que puede establecer una dirección URL personalizada para usarse en su lugar. Esta dirección URL debe estar registrada en el Portal de registro de aplicaciones como una dirección URL de redireccionamiento. La página de destino debe hacer referencia al SDK del selector de OneDrive de la misma manera que la página de llamada.	OAuth
endpointHint	La sugerencia de punto de conexión se usa para que el SDK redirija la aplicación al punto de conexión de OAuth correcto en función de con qué puntos de conexión de la API de OneDrive quiera comunicarse la aplicación. Los puntos de conexión de API de OneDrive incluyen OneDrive Personal, OneDrive para la Empresa o SharePoint Online. El valor de `endpointHint` puede ser `api.onedrive.com` para OneDrive Personal, la dirección URL de OneDrive para la Empresa o una dirección URL de biblioteca de documentos de SharePoint, por ejemplo `https://contoso-my.sharepoint.com/personal/foo_contoso_onmicrosoft_com/` o `https://contoso.sharepoint.com/shared%20documents/`. No es necesario si la aplicación se comunica con la API de Microsoft Graph.	OAuth
accessToken	Un accessToken que ha concedido acceso a los puntos de conexión de la API de OneDrive para OneDrive Personal, OneDrive para la Empresa o SharePoint Online puede pasarse omitiendo el flujo de OAuth que le proporciona una experiencia más rápida. `endpointHint` se necesita si accessToken está presente.	OAuth
loginHint	Si un usuario ha iniciado sesión anteriormente en la aplicación, puede proporcionar un valor loginHint que habilitará el inicio de sesión único.	OAuth
isConsumerAccount	Cuando se comunica con la API de Microsoft Graph y el `loginHint` especificado, el SDK también necesita que la aplicación indique si el usuario que ha iniciado sesión es una cuenta de cliente (conocida como cuenta Microsoft) o una cuenta empresarial.	OAuth
scopes	El SDK solicitará automáticamente el ámbito `Files.Read.All` para abrir flujos y el ámbito `Files.ReadWrite.All` para guardarlos. En cambio, si quiere solicitar permisos adicionales, puede agregar ámbitos adicionales aquí.	OAuth
navigation	En el SDK del selector 7.2 hemos presentado una nueva interfaz de usuario donde pueden establecerse varias configuraciones. Todas las configuraciones se encuentran en el objeto `navigation`.	Interfaz de usuario del selector

Nota: Actualmente, el tipo de filtro "photo" solo se admite en las cuentas de OneDrive Personal.

Uso conjunto del selector y la API

Puede usar el valor actionquery junto con la configuración de queryParameters del objeto avanzado para devolver un conjunto de propiedades personalizado de la API sobre el objeto seleccionado. Por ejemplo, cuando se selecciona un archivo, para incluir detalles de foto (si está disponible):

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 */ }
}

Esto indica al SDK del selector que seleccione las propiedades id, name, size, file, folder y photo en la respuesta.

Devolver un vínculo que se puede compartir con la empresa de lectura y escritura

De manera predeterminada, el selector de archivos de OneDrive devuelve una dirección URL de uso compartido de solo vista cuando action se establece en share. En cambio, puede usar la propiedad createLinkParameters para cambiar los parámetros que se han pasado a la acción 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 un URI de redireccionamiento personalizado

Si la aplicación es una aplicación de JavaScript del lado cliente grande o usa parámetros de cadena de consulta para conservar el estado, puede que no sea adecuado usar la página para iniciar el selector de archivos como el URI de redireccionamiento. Esto requiere que la aplicación entera se vuelva a cargar dentro de la ventana emergente, lo que puede ocasionar problemas de rendimiento. Puede especificar un URI de redireccionamiento alternativo mediante el objeto avanzado que se usa en su lugar.

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 puntos de conexión de API alternativos

La API de Microsoft Graph proporciona un acceso unificado a los archivos almacenados en OneDrive Personal, OneDrive para la Empresa y SharePoint Online. En cambio, en algunos escenarios limitados, puede que sea necesario usar una dirección URL de sitio de SharePoint determinada en lugar de Microsoft Graph.

En este caso, la aplicación puede especificar el punto de conexión de la API de OneDrive para el sitio de SharePoint en lugar del punto de conexión de la API de Microsoft Graph. El SDK del selector de OneDrive redirigirá al punto de conexión de OAuth correcto para obtener un token de acceso. La asignación entre los puntos de conexión de la API de OneDrive y la autoridad de OAuth es:

Punto de conexión de API	Punto de conexión 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/

Redirige al punto de conexión OAuth de 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 */ }
}

Redirige a la biblioteca de documentos directamente, y la aplicación controla el flujo de OAuth en otro 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 */ }

La página a la que se redirige solo necesita cargar el script del SDK de OneDrive:

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

Personalizar funciones

Aunque el selector de archivos permite a los usuarios seleccionar archivos desde Office 365, incluidas las bibliotecas de documentos de SharePoint y OneDrive, puede que quiera restringir el origen desde donde puede abrirse un archivo. Puede usar estas propiedades para restringir las funciones solo a las que quiera habilitar:

Nombre del parámetro	Descripción
disable	Si se establece el valor, el panel de navegación no se mostrará.
entryLocation	Establezca la biblioteca de documentos representada en la IU del selector de OneDrive.
sourceTypes	Los orígenes de archivos que el usuario puede seleccionar en el panel de navegación.

La aplicación puede especificar sourceTypes como OneDrive, Recent, Sites o varios orígenes en una matriz [`OneDrive`, `Recent`]. La aplicación también puede especificar una ubicación de entrada personalizada en lugar de la predeterminada al especificar el objeto entryLocation. La ubicación de entrada personalizada está limitada a una biblioteca de documentos de SharePoint. La ubicación de entrada predeterminada es el OneDrive para la Empresa del usuario.

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 */ }

Compartir a través de