Nota
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Integración de OneDrive en sus aplicaciones de la Tienda Windows
Descargar el código de muestra
Hoy en día, no hay conversación que tarde o temprano no termine en el desarrollo en la nube. Públicas, privadas, locales, remotas, las ofertas en la nube vienen en todas las formas y tamaños. Pero cuando hablamos de aplicaciones basadas en clientes que administran archivos de usuarios, es probable que se centre en ofertas como la de Microsoft OneDrive.
Microsoft OneDrive, que cambió de nombre hace poco, les proporciona a los clientes una manera cómoda de almacenar, compartir y acceder a sus archivos personales desde cualquier lugar y desde cualquier dispositivo. OneDrive se ha integrado por completo en todas las plataformas Microsoft y es compatible con la mayoría de las demás plataformas que se utilizan en la actualidad. Los distintos dispositivos pueden compartir, sincronizar o acceder de manera sencilla a documentos, fotos, vídeos y muchos otros tipos de archivos. Entonces, si está compilando una aplicación que involucra archivos de usuarios, integrar OneDrive e su aplicación puede ser una característica importante.
Si compila aplicaciones de la Tienda Windows, recibe de forma gratuita y automática un cierto nivel de capacidad de OneDrive. En Windows 8.1, encontrará una aplicación OneDrive en la Tienda Windows, así como la integración de escritorio en el sistema de archivos que incluye una implementación de los contratos del Selector de archivos para abrir y del Selector de guardar archivo. Esto significa que si usa los selectores de archivos para abrir o de guardar archivo en su aplicación, el usuario tendrá automáticamente la capacidad de abrir o guardar documentos en su cuenta de OneDrive. Lo mismo sucede con los cuadros de diálogo de abrir y guardar archivo en las aplicaciones de escritorio.
No obstante, ¿qué pasa si quiere controlar un poco más cómo funciona esta interacción? ¿Qué pasa si quiere mostrar los datos del usuario en otro formato, o controlar la carga y descarga de varios archivos en segundo plano? Para abordar estos escenarios, Microsoft ofrece una API a la que se puede acceder desde cualquier plataforma para que los desarrolladores integren OneDrive en sus soluciones. Este artículo explora esa API y analiza las consecuencias de usar esta API en sus aplicaciones de la Tienda Windows.
Presentación del SDK de Live
El SDK de Live facilita el acceso al contenido de OneDrive. En su núcleo, el SDK de Live es una colección de API de REST basadas en JSON que se pueden consumir en cualquier plataforma. El SDK de Live usa inicio de sesión único para aplicaciones de la Tienda Windows y de la Tienda de Windows Phone, y autenticación OAuth 2.0 para otras plataformas. Para ayudar a los desarrolladores a crear aplicaciones correctas que usen OneDrive, Microsoft también ha publicado SKD específicos para clientes. Actualmente, hay SKD para plataformas Microsoft Windows y Windows Phone, así como SDK para Android e iOS. Los vínculos para todos estos SDK se pueden encontrar en msdn.microsoft.com/onedrive/dn630256. El SDK de Live también se puede agregar mediante NuGet (nuget.org/packages/LiveSDK).
Con respecto a OneDrive, la función principal del SDK de live es permitir el acceso mediante programación a los archivos y las carpetas dentro de la cuenta de un usuario. Estos son los servicios básicos que presta el SDK:
- Navegar por la jerarquía de carpetas
- Crear y eliminar carpetas
- Leer y modificar las propiedades de carpeta
- Cargar y descargar archivos
- Leer y modificar las propiedades de archivo
- Copiar y mover archivos y carpetas
- Obtener vínculos para compartir archivos y carpetas
- Establecer permisos para archivos y carpetas
Uso Visual Studio 2013 Update 2 y el SDK de Live versión 5.6 para explorar cómo usar el SDK en una aplicación de la Tienda Windows 8.1 escrita en XAML. Gracias a la disponibilidad de SDK específicas para clientes para la mayoría de las plataformas, los mismos conceptos se pueden migrar fácilmente al lenguaje y a la plataforma de su elección.
Desarrollo de aplicaciones con el SDK de Live
Antes de empezar a desarrollar aplicaciones con el SDK de Live, hay algunas cuestiones “domésticas” que debe atender. Dado que el SDK de Live no forma parte del SDK básico de Windows, debe descargar el SDK de Live y luego agregar una referencia a él desde su aplicación. Para agregar la referencia, haga clic con el botón derecho en su solución en Visual Studio 2013 y seleccione Agregar referencia. El SDK de Live se puede encontrar en la sección Extensiones de Windows 8.1 del Administrador de referencias, como se ve en la Figura 1.
Figura 1 Agregar una referencia al SDK de Live
De forma predeterminada, una aplicación de la Tienda Windows 8.1 tiene la capacidad de Internet (cliente) habilitada en su appxmanifest. Esta es una capacidad obligatoria para usar el SDK de Live, y su proyecto debe tenerla habilitada. Para comprobar esta capacidad o habilitarla, abra el appxmanifest de su proyecto en el diseñador y asegúrese de que Internet (cliente) esté activado en la pestaña Capacidades.
Una vez que haya agregado el SDK de Live a su proyecto, encontrará todo el SDK en el espacio de nombres Microsoft.Live. Sin embargo, usar el SDK en este momento producirá un error de referencia de objeto nulo. Esto se debe a que hay que registrar la aplicación en los servicios de Live antes de poder acceder a OneDrive. Según la plataforma en la que desarrolle, esto se puede hacer de varias maneras. Para una aplicación de la Tienda Windows, simplemente asocie la aplicación a la Tienda Windows. La forma más directa de hacerlo es usar el asistente de Visual Studio.
Para iniciar el asistente, haga clic con el botón secundario en el proyecto de la Tienda en el Explorador de soluciones y seleccione Tienda | Asociar aplicación con la Tienda. El asistente se abrirá con una descripción de lo que necesitará para continuar. Si selecciona Siguiente, le pedirá que inicie sesión en una cuenta de Microsoft asociada a la Tienda Windows (si aún no ha iniciado sesión). Puede que también tenga que pasar por un segundo proceso de comprobación, como la recepción de un código de autorización por mensaje de texto enviado al número de teléfono asociado a su cuenta. Una vez que haya completado el proceso de inicio de sesión, verá una lista de todos los nombres de aplicaciones reservados asociados a su cuenta, como se ve en la Figura 2. Si se trata de una aplicación nueva, también puede reservar un nuevo nombre de aplicación desde esta pantalla. Cuando tenga un nombre para asociar a la aplicación, seleccione Siguiente para ver una pantalla de resumen y haga clic en Asociar para completar el proceso.
Figura 2 Asociar un nombre reservado a una aplicación
Ahora la aplicación está configurada y lista para usarse con el SDK de Live.
Acceso a los datos del usuario
El primer paso para habilitar la integración de OneDrive con su aplicación es obtener la capacidad de acceder a la información del usuario. Como ya se dijo anteriormente, el SDK de Live usa 0Auth 2.0 para la autenticación. No obstante, hay algunos aspectos adicionales que se deben tener en cuenta además de la simple autenticación de la aplicación.
Uso correcto de OneDrive Si está familiarizado con el desarrollo y la implementación de aplicaciones de la Tienda Windows, sabrá que hay algunas directrices que detallan lo puede hacer dentro de su aplicación y lo que no. OneDrive agrega su propio conjunto de directrices que también se deben tener en cuenta.
El principal motivo para las restricciones es evitar que perjudique la confianza del usuario en OneDrive. Cuando un usuario tiene un origen central para almacenar su información personal, tiene una confianza inherente en ese origen o, de lo contrario, no lo usaría. Al acceder a OneDrive con su aplicación, el usuario extiende esa confianza a su aplicación. Así, si su aplicación comienza a eliminar los datos del usuario sin su consentimiento ni conocimiento, perjudica esa confianza y afecta no solo a la percepción que ese usuario tiene de su aplicación, sino también a su percepción de OneDrive. Por este motivo, debe tener sumo cuidado en la forma en que su aplicación interactúa con OneDrive, en particular, cuando realiza funciones que actualizan o quitan información del usuario. Una descripción de estas directrices se puede encontrar en bit.ly/1rQ8iXK.
Uso del inicio de sesión único Al usar el SDK de Live en una aplicación de la Tienda Windows, Microsoft sugiere aprovechar las características de inicio de sesión único (SSO). Al igual que con el SDK de Live, agregar SSO a su aplicación implica algunos requisitos adicionales, como una declaración de privacidad y un panel de configuración de la cuenta. Para conocer los detalles completos para agregar los componentes necesarios a su aplicación, vea bit.ly/TJvTxB.
Una vez que su aplicación está preparada para SSO, el inicio de sesión en la cuenta del usuario se completa mediante una instancia de la clase LiveAuthClient. LiveAuthClient tiene un método LoginAsync que usará las credenciales de la cuenta de Microsoft que ha iniciado sesión en el dispositivo Windows 8.1. Si el inicio de sesión es correcto, el objeto LiveLoginResult devuelto contendrá una instancia LiveConnectSession que se usará para todas las llamadas al SDK de Live. El código siguiente hará que el usuario inicie sesión y devolverá el objeto Session:
LiveAuthClient authClient = new LiveAuthClient();
LiveLoginResult authResult =
await authClient.LoginAsync(new List<string>() {
"wl.signin",
"wl.basic", "wl.skydrive", "wl.skydrive_update" });
if (authResult.Status == LiveConnectSessionStatus.Connected)
{
// Add code to handle session held in the Session property
}
Ámbitos Probablemente haya notado el uso de ámbitos, como “wl.signin”, en el código anterior. Cuando su aplicación inicia sesión en la cuenta de un usuario, debe identificar qué tipo de acceso necesita. Si intenta usar porciones de la API para las que no ha solicitado acceso, se producirá un error. Para las aplicaciones de la Tienda Windows, esto no es diferente de intentar usar porciones del SDK de Windows para las que no haya solicitado acceso en la sección de capacidades del paquete appxmanifest.
Los ejemplos de este artículo usarán los cuatro ámbitos únicamente. El ámbito wl.signin le permite aprovechar el comportamiento de SSO que debe usar en las aplicaciones de la Tienda Windows. El ámbito wl.basic permite el acceso a algunos datos comunes sobre el usuario.
Para las aplicaciones de OneDrive, hay solo dos ámbitos adicionales que debe tener en cuenta: wl.skydrive y wl.skydrive_update. Como los nombres lo sugieren, wl.skydrive es necesario para el acceso de lectura y exploración de la cuenta de OneDrive del usuario. Si la aplicación necesita la capacidad de cargar archivos, crear carpetas o eliminarlas, o cambiar las propiedades de un objeto, usará el ámbito wl.skydrive_update. Este ámbito también le concede permisos de lectura en OneDrive, por lo que no es necesario incluir ambos ámbitos, wl.skydrive y wl.skydrive_update, en la lista de acceso.
A fin de mantener la compatibilidad inversa con las aplicaciones que usaban la nomenclatura anterior, no se cambiaron los nombres de los ámbitos de OneDrive. Sin embargo, no me sorprendería ver un par de ámbitos adicionales con la nomenclatura OneDrive en las versiones futuras de la API.
Dado que el SDK de Live abarca mucho más que apenas OneDrive, existen muchos otros ámbitos que no voy a tratar en este artículo. Puede encontrar una lista descriptiva completa en msdn.microsoft.com/library/dn631845.
Obtener el consentimiento del usuario La primera vez que un usuario ejecuta una aplicación que solicita acceso a su cuenta de OneDrive, se le pedirá que conceda a esa aplicación permisos para los ámbitos establecidos en la llamada de inicio de sesión. La Figura 3 muestra un ejemplo de este aviso en una aplicación de la Tienda Windows. Una vez que el usuario concede el permiso, no se le volverá a pedir siempre y cuando no cambie la lista de ámbitos. Si una versión actualizada de la aplicación solicita características adicionales de la API, nuevamente se le pedirá permiso al usuario.
Figura 3 Solicitud de consentimiento del usuario para acceder a OneDrive
Objetos en OneDrive
Para la API de OneDrive, todos son objetos. Ya sea una carpeta, una foto o una hoja de cálculo, todo lo que se almacena en OneDrive tiene un conjunto de propiedades similares, y comparten las llamadas de la API. Cada objeto tiene una colección de propiedades y puede tener una colección de objetos secundarios. Los tipos de objetos en los que me voy a concentrar en este artículo son: carpeta, archivo, álbum y foto. Encontrará una lista completa de los objetos disponibles con su descripción y uso en msdn.microsoft.com/library/dn631843.
Una vez que la aplicación obtiene una instancia de LiveConnectionSession del método LoginAsync de LiveAuthClient, esa instancia de sesión se puede usar para crear una instancia de la clase LiveConnectClient, que contiene todas las llamadas de la API que usará para interactuar con OneDrive. El ejemplo siguiente muestra la creación de una instancia de la clase LiveConnectClient y la consulta a OneDrive por el objeto carpeta raíz del usuario, que se puede recuperar con la ruta “me/skydrive”:
public async Task<object> GetRootFolder()
{
LiveConnectClient client = new LiveConnectClient(_session);
LiveOperationResult liveOpResult =
await client.GetAsync("me/skydrive");
dynamic dynResult = liveOpResult.Result;
return dynResult;
}
Este código usa la palabra clave dinámica para crear una instancia de clase de la cadena subyacente con formato JSON en tiempo de ejecución. Si bien es algo rápido y sencillo, tenga en cuenta que puede encontrarse con algunas limitaciones que puedan exigir una estructura de clases más formal.
Los resultados devueltos a partir del método GetAsync contendrán todas las propiedades para el objeto solicitado. La Figura 4 muestra un ejemplo de la cadena con formato JSON devuelta para la carpeta raíz de un usuario.
Figura 4 JSON devuelto a partir de una consulta de objeto carpeta
{
"id": "folder.abced3a35e6d1b",
"from": {
"name": null,
"id": null
},
"name": "SkyDrive",
"description": "",
"parent_id": null,
"size": 2957188732,
"upload_location":
"https://apis.live.net/v5.0/folder.abced3a35e6d1b/files/",
"comments_count": 0,
"comments_enabled": false,
"is_embeddable": false,
"count": 25,
"link": "https://onedrive.live.com?cid=abced3a35e6d1b",
"type": "folder",
"shared_with": {
"access": "Just me"
},
"created_time": null,
"updated_time": "2014-06-13T18:00:54+0000",
"client_updated_time": "2012-10-22T19:50:04+0000"
}
Al consultar en OneDrive, puede ser útil crear una consulta más específica. Por ejemplo, lo siguiente devolverá todos los objetos secundarios en el directorio raíz:
LiveOperationResult liveOpResult = await client.GetAsync("me/skydrive/files");
Esto incluye carpetas y archivos y, posiblemente, muchísimos datos.
¿Qué puede hacer si quiere ver solo una lista de las fotos en este directorio? Esto se puede hacer con los parámetros de consulta de filtro. La API de OneDrive admite varios tipos distintos de parámetros de consulta además del filtrado, como limitación, desplazamiento y búsqueda. Los parámetros le permiten obtener solo los datos que necesita y limitan no solo la cantidad de datos que se deben descargar, sino también la cantidad de código necesario para tratar los datos devueltos.
Por ejemplo, la consulta siguiente devuelve solo una lista de fotos en el directorio raíz, lo que le ahorra escribir código para separar las fotos de las carpetas:
LiveOperationResult liveOpResult =
await client.GetAsync("me/skydrive/files?filter=photos");
Para obtener una lista completa de los parámetros de consulta y su uso, vea msdn.microsoft.com/library/dn631842.
Trabajar con carpetas
Si va a trabajar con un sistema de archivos de algún tipo, un lugar lógico donde empezar es la estructura de carpetas. Al consultar por una carpeta, puede usar dos tipos distintos de identificadores: una ruta fácil de recordar, como me/skydrive, o un identificador de carpeta que se vea como folder.abcde86dfb3a35e6d1b.ABCDED3A35E6D1B!532. Si quiere consultar por una lista de objetos secundarios de una carpeta, puede anexar “/files” a la ruta. Por ejemplo, el código siguiente devolverá una lista de todos los archivos, carpetas y álbumes para un identificador de carpeta dado:
LiveOperationResult liveOpResult =
await client.GetAsync("folder.abcde86dfb3a35e6d1b.ABCDED3A35E6D1B!532/files");
OneDrive contiene dos tipos de objetos de carpeta: carpeta y álbum. Un álbum puede considerarse un tipo especial de carpeta que se encuentra en el directorio raíz del usuario en OneDrive. Los álbumes pueden contener fotos y vídeos, así como una estructura de carpetas y archivos adicionales.
Es importante comprender la diferencia entre una carpeta y un álbum, dado que la consulta siguiente devolvería solo las carpetas en su directorio raíz y omitiría todos los álbumes. Esto puede provocar resultados inesperados:
LiveOperationResult liveOpResult =
await client.GetAsync("me/skydrive/files?filter=folders");
Para devolver tanto carpetas como álbumes, use un valor de filtro de “folders,albums.”
La consulta anterior le permite explorar en su totalidad la estructura de carpetas de la cuenta de OneDrive de un usuario al obtener las carpetas secundarias de cada carpeta. La descarga asociada de este artículo contiene una aplicación de muestra, MyPhotoAlbum, una aplicación de la Tienda Windows en XAML que contiene dos páginas. La primera página, FolderPage, le permite explorar la estructura de directorios y muestra los resultados en una vista GridView. Todas las llamadas del SDK de Live están empaquetadas en la clase OneDriveDataProvider.
La Figura 5 muestra el método usado para atravesar la estructura de carpetas al pasar el identificador de carpeta actual y usar “folders,albums” como valor de filtro. Si el identificador de carpeta no existe, el método toma el directorio raíz como valor predeterminado.
Figura 5 Método GetFolderItems
public async Task<List<object>>
GetFolderItems(string path, string filter)
{
if (_session == null)
{
await InitProvider();
}
if (String.IsNullOrEmpty(path))
{
path = "me/skydrive";
}
if (!String.IsNullOrEmpty(filter))
{
filter = "?filter=" + filter;
}
LiveConnectClient client = new LiveConnectClient(_session);
LiveOperationResult liveOpResult =
await client.GetAsync(path + "/files" + filter);
dynamic dynResult = liveOpResult.Result;
return new List<object>(dynResult.data);
}
La Figura 6 muestra un ejemplo de los resultados devueltos en FolderPage. Al seleccionar una carpeta secundaria, irá a la misma FolderPage, con la carpeta secundaria como parámetro. Esto permite que la pila de navegación preserve la funcionalidad inversa de volver a subir la estructura de carpetas.
Figura 6 FolderPage
Si ha solicitado el acceso a actualizaciones con el ámbito wl.skydrive_update, también puede crear y eliminar carpetas con la API. Una carpeta contiene solo tres propiedades que puede crear o cambiar: name, description y sort_by. Al crear una carpeta, debe especificar un directorio principal, ya sea por su ruta o identificador, y proporcionar una matriz JSON con un nombre como mínimo. Este es un ejemplo del código JSON necesario para crear una carpeta:
{
"name": "My Favorite Photos",
"description": "A folder full of my favorite photos."
}
El SDK se encarga de esto mediante el método PostAsync de la clase LiveConnectClient. La Figura 7 muestra el método usado para crear una carpeta.
Figura 7 Método CreateFolder
public async Task<bool> CreateFolder(string path, string name)
{
try
{
var folderData = new Dictionary<string, object>();
folderData.Add("name", name);
LiveConnectClient liveClient = new LiveConnectClient(_session);
LiveOperationResult operationResult =
await liveClient.PostAsync(path, folderData);
dynamic result = operationResult.Result;
return true;
}
catch (LiveConnectException exception)
{
return false;
}
}
La eliminación de una carpeta se logra con el método DeleteAsync, que también se puede utilizar para eliminar archivos. Es importante recordar mantener la integridad de OneDrive y usar cualquier función de eliminación con cuidado:
LiveOperationResult operationResult = await liveClient.DeleteAsync(path);
Trabajar con archivos
Si bien el método GetAsync devuelve las propiedades de un archivo, no devuelve el propio archivo. La única manera de obtener un archivo de OneDrive es descargarlo. El SDK de Live para las aplicaciones de la Tienda Windows abordan esto mediante la creación de una tarea de descarga en segundo plano, que se encarga de la descarga de manera asíncrona sin atorar al dispositivo. El código siguiente se puede usar para descargar un archivo de OneDrive:
try
{
LiveConnectClient liveClient = new LiveConnectClient(_session);
LiveDownloadOperation op =
await liveClient.CreateBackgroundDownloadAsync(filePath);
var result = await op.StartAsync();
// Handle result
}
catch
{
// Handle errors
}
Una vez que se devuelve la operación de descarga en segundo plano, debe llamarse al método StartAsync de la instancia LiveDownloadOperation para iniciarla.
Al igual que para descargar un archivo, la única manera de agregar o actualizar un archivo en OneDrive es cargarlo. Para cargar un archivo, la aplicación debe haber solicitado acceso de escritura con el ámbito wl.skydrive_update. El método CreateBackgroundUploadAsync toma la ruta de una carpeta, el flujo que contiene el archivo y una opción de sobrescritura. Si ya existe un archivo, la opción de sobrescritura puede sobrescribir el archivo original, o puede mantener el archivo original y cambiar el nombre del nuevo archivo que va a cargar. Al igual que con las funciones de actualización de carpetas, tenga cuidado al usar esta característica a fin de no destruir archivos por accidente. El siguiente es un ejemplo de cómo cargar un archivo:
try
{
LiveConnectClient liveClient = new LiveConnectClient(_session);
LiveUploadOperation op = await liveClient.CreateBackgroundUploadAsync(
path, filename, fileStream, OverwriteOption.Rename);
var result = await op.StartAsync();
// Handle result
}
catch
{
// Handle errors
}
Antes de cargar un archivo, es importante asegurarse de que el usuario tenga espacio suficiente para el nuevo archivo. Puede comprobar la cantidad de espacio disponible si usa la ruta “me/skydrive/quota” en el método GetObjectAsync. Esto devolverá dos propiedades, quota y available, que le permiten calcular el número de bytes restantes en la cuenta del usuario.
Hay dos funciones adicionales en la API que resultan útiles al tratar con archivos. Si quiere hacer una copia de un archivo, puede descargar el archivo y luego volver a cargarlo con otro nombre. No obstante, esto puede consumir mucho ancho de banda para una operación bastante sencilla. Además, ¿qué pasaría si quisiera copiar una carpeta entera o mover una carpeta secundaria a otra carpeta principal? El código y el ancho de banda para hacer esto con descargas y cargas harían que estas operaciones fueran bastante engorrosas. Para atender estas funciones, la API de OneDrive tiene comandos para mover y copiar: MoveAsync y CopyAsync. Ambos toman dos parámetros: el objeto (archivo o carpeta) que quiere mover y la ruta de destino. La Figura 8 muestra el método usado para copiar un archivo.
Figura 8 Copiar un archivo
public async Task<bool> CopyObject(string path, string destination)
{
if (_session == null)
{
await InitProvider();
}
try
{
LiveConnectClient liveClient = new LiveConnectClient(_session);
LiveOperationResult operationResult =
await liveClient.CopyAsync(path, destination);
return true;
}
catch (LiveConnectException exception)
{
return false;
}
}
Resumen
En un solo artículo no es mucho lo que se puede cubrir acerca de una API. El SDK de Live incluye muchas otras características, en especial para administrar fotos y vídeos. Si piensa en integrar OneDrive a su solución, sería recomendable explorar estas otras características. Microsoft ha creado el Centro de desarrollo de OneDrive para un punto de acceso único para todo lo relacionado con la API de OneDrive en dev.onedrive.com.
Ya sea que compile aplicaciones de la Tienda Windows, aplicaciones de la Tienda de Windows Phone o una aplicación para cualquier otra plataforma que necesite acceso al archivo de un usuario, agregar OneDrive es una forma estupenda de integrar su aplicación a la vida diaria del usuario, ya que le concede el acceso a los archivos que más le importan. Entonces, si quiere generar una excelente experiencia de usuario, asegúrese de incluir OneDrive.
Tony Champion es presidente de Champion DS, es un Microsoft MVP y participa de manera activa en la comunidad como orador, blogger y autor. Tiene un blog en tonychampion.net. Para ponerse en contacto con él, escríbale a tony@tonychampion.net.
Gracias al siguiente experto técnico de Microsoft por revisar este artículo: Mimi Sasouvanh
Mimi Sasouvanh es desarrolladora de contenido en el equipo de Operation Systems Group Content de Microsoft, ha escrito sobre el desarrollo de OneDrive y Azure Intelligent Systems Service, entre otras cosas. Dedica su tiempo a su familia, la jardinería y el dibujo.