Compartir a través de

Enero de 2016

Volumen 31, número 1

Windows 10: usar la API de REST de OneDrive en una aplicación Windows 10

Por Laurent Bugnion

En marcos anteriores, como Windows Phone 8, el equipo de OneDrive proporcionó un SDK que era bastante cómodo de usar, pero que no daba mucha libertad al desarrollador. Por ejemplo, el mecanismo de inicio de sesión solo era posible mediante un control de botón integrado, cuyo aspecto y comportamiento el desarrollador no podía cambiar. Sin embargo, la parte más difícil era que esta experiencia predefinida no permitía compartir código entre plataformas.

Ahora, el equipo de OneDrive proporciona una API de REST moderna basada en solicitudes HTTP (GET, POST, PUT, etc.). Esta es una manera flexible de interactuar con el gigantesco almacenamiento de archivos en la nube y generar código de varias plataformas con conocidas técnicas de uso compartido de código que se pueden ejecutar en todas las plataformas de Windows e incluso en iOS y Android con las plataformas Xamarin.

En el primer artículo de una serie de dos partes se mostrará cómo sacar provecho de la nueva API de OneDrive para crear aplicaciones para la Plataforma universal de Windows (UWP). En primer lugar, verá cómo funciona la API de REST y cómo se espera que los desarrolladores interactúen con ella. Verá cómo el usuario puede iniciar sesión en el sistema con oAuth y cómo se puede sacar provecho de las operaciones del sistema de archivos (examinar carpetas, obtener información de archivo, obtener contenido de archivo, cargar archivos, etc.). También verá cómo ejecutar operaciones adicionales, por ejemplo, acceder a la carpeta Aplicación y compartir con amigos un vínculo a un elemento.

En el siguiente artículo, hablaré sobre la nueva Biblioteca de clases portable (PCL) del equipo de OneDrive, que encapsula las operaciones que se describen aquí en una cómoda biblioteca que se puede agregar a las aplicaciones para UWP, así como a otros marcos compatibles, como ASP.NET, Xamarin.iOS, Xamarin.Android o Xamarin.Forms.

Nota: Además de la PCL que se puede usar en las plataformas Xamarin.Android y Xamarin.iOS, el equipo de OneDrive también proporciona SDK nativos para ambas plataformas.

El código de ejemplo

Puede descargar el código de ejemplo desde galasoft.ch/s/msdnonedrive. En él se muestra cómo una simple aplicación para UWP puede usar la API de REST de bajo nivel para realizar operaciones en el servicio de OneDrive. Para demostrar la facilidad de portabilidad del código, la misma aplicación también se implementa para Xamarin.Android, y los mismos principios se pueden aplicar a otras plataformas.

Descripción de la API de REST

Las API de REST usan HTTP como protocolo de transporte y dependen de los métodos (GET, POST, PUT, DELETE, etc.) del protocolo y de los códigos de error estándares (200 Correcto, 400 Solicitud incorrecta, 500 Error de servidor, etc.). Cada punto de entrada de la API es accesible a través de un URI único que también puede contener parámetros. En algunos casos, se puede usar un sencillo método GET y una cadena de consulta para enviar información al servicio y obtener un resultado. Sin embargo, también es posible crear solicitudes más complejas al aplicar POST en algunos objetos serializados en JSON.

El uso de las API de REST se está extendiendo y los desarrolladores deberían estar contentos de ello, ya que ofrece una manera familiar de comunicarse con los servicios web. Y lo más importante, permiten crear componentes portables en C# y usar estos en todas las plataformas admitidas. Otra gran ventaja es que HTTP se base en texto y las solicitudes puedan atravesar fácilmente los firewall y proxy.

Sin embargo, la comunicación con los métodos HTTP de bajo nivel puede parecer como mucho trabajo, especialmente para los desarrolladores que no están habituados a los últimos avances en la programación asincrónica. La creación de un cliente asincrónico mediante devoluciones de llamada no era la experiencia más agradable para los desarrolladores debido al anidado profundo y a los posibles problemas de procesamiento que podían surgir. Afortunadamente, dos avances relativamente recientes facilitaron las cosas para los programadores de C#: el componente HttpClient y las palabras clave async/await. Por ejemplo, el acceso a la carpeta Música de OneDrive es tan fácil como crear un URI y enviar una solicitud GET:

var uri = new Uri(
  "https://api.onedrive.com/v1.0/drive/special/music");
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
  new AuthenticationHeaderValue("Bearer", AccessToken);
var json = await client.GetStringAsync(uri);

El código JSON resultante se puede deserializar (con la biblioteca JSON.NET, por ejemplo) para obtener un objeto .NET que se usa en la aplicación. En este código (ciertamente sin inicio de sesión ni control de errores) se muestra cómo lo que sería una operación compleja se hace sencilla y fluida. Además, este código se ejecutará perfectamente en cualquier plataforma que HttpClient admita, lo que incluye Windows Presentation Foundation (WPF), ASP.NET, Windows 10, Xamarin y mucho más.

Registrar la aplicación

Antes de que se pueda hacer la llamada a la API de OneDrive, debe registrar la aplicación en el Centro para desarrolladores de OneDrive, configurarla y obtener la clave de id. de cliente. El mecanismo de registro se describe en bit.ly/1GPBaWL.

Al registrar la aplicación, asegúrese de ir a la página de configuración de la API y establecer la opción “Aplicación de cliente móvil o de escritorio” en “Sí”. Las demás opciones de configuración se pueden dejar en sus valores predeterminados. Luego, recupere el id. de cliente de la página de configuración de la aplicación y guárdelo para más adelante.

Es importante comprender los distintos términos y para qué se necesita cada identificador:

  • Id. de cliente: este es un identificador único de su aplicación para UWP. Puede tener varias aplicaciones clientes que se conectan a los servicios Microsoft con el mismo id. de cliente. Sin embargo, en general, es recomendable usar un id. de cliente por aplicación. El id. de cliente está vinculado a información sobre la aplicación para UWP, como su nombre, el icono, etc. El id. de cliente se genera cuando se crea la aplicación y no cambia nunca.
  • Secreto de cliente: este es un identificador único que se genera cuando se crea la aplicación para UWP. Sin embargo, este código puede cambiar durante el ciclo de vida de la aplicación. Por ejemplo, si cree que se pirateó el secreto de cliente de la aplicación, puede generar uno nuevo, actualizar las aplicaciones y se les denegará el acceso a las aplicaciones pirateadas. Tenga en cuenta que el secreto de cliente suele usarse solo en las aplicaciones de servidor.
  • Id. de usuario y contraseña: cuando el usuario inicia sesión, se le pide que especifique su nombre de usuario y contraseña. Gracias a OAuth, la interacción de inicio de sesión se produce solo entre el usuario y OneDrive, sin el conocimiento de la aplicación cliente. En la práctica, esto se hace con un objeto WebView en el que se muestra el cuadro de diálogo de inicio de sesión.
  • Token de acceso: cuando un usuario inicia sesión correctamente, el servicio de autenticación devuelve un token de acceso. Este token es válido solo durante un tiempo determinado (60 minutos), después del cual el usuario tiene que iniciar sesión de nuevo. El token se debe enviar con cada solicitud para demostrar que el usuario se ha autenticado. En la documentación, este modo de autenticación se denomina “flujo de tokens”.
  • Token de actualización: este token lo puede solicitar la aplicación y se puede guardar para actualizar el token de acceso, en caso de que este haya expirado. Esto puede ser de utilidad si la aplicación se usa en modo en segundo plano durante un tiempo prolongado y debe actualizar los datos periódicamente sin la interacción del usuario. Este modo de autenticación se llama CodeFlow y se describe en bit.ly/1MQ3KOb. En este artículo, solo usaré el flujo de tokens, que es más fácil de implementar.

Probar todo con un token de prueba

Si quiere probar algunas solicitudes REST sin primero implementar la autenticación, el Centro para desarrolladores de OneDrive permite obtener un token de prueba, válido durante una hora, que se puede usar siguiendo estos pasos:

  • Vaya a bit.ly/1MQ3KOb.
  • Busque la sección “Try it now” y haga clic en el botón Obtener token.
  • Si fuera necesario, inicie sesión y confirme que autoriza al Centro para desarrolladores a acceder a su cuenta de OneDrive.
  • Después de iniciar sesión correctamente, aparecerá un token de prueba en la ventana web principal.
  • Cree una nueva aplicación para UWP denominada TrialOneDrive.
  • Abra MainPage.xaml y agregue un botón denominado TrialButton.
  • Abra MainPage.xaml.cs y agregue un controlador de eventos para el evento TrialButton Click, tal como se muestra en el código de la Figura 1. Tenga en cuenta que este controlador de eventos debe usar la palabra clave “async” porque todas las operaciones de OneDrive son asincrónicas.
  • En el código de la Figura 1, reemplace la cadena YOUR TRIAL TOKEN con el token de prueba copiado del sitio web del Centro para desarrolladores. No copie las palabras “Authorization: bearer”.
  • Coloque un punto de interrupción en la última línea del controlador de eventos para inspeccionar la variable JSON.
  • Ejecute la aplicación y haga clic en el botón.
  • Inspeccione el código JSON recibido en la ventana Inspección. Debería ver información sobre la carpeta Música, como su nombre, fecha de creación, fecha de última modificación, recuento de elementos secundarios, identificador de la carpeta (que se puede usar más adelante en distintas operaciones del sistema de archivos), nombre de usuario conectado, etc.

Figura 1 Agregar un controlador de eventos para el evento de clic TrialButton

TrialButton.Click += async (s, e) =>
{
  var uri = new Uri(
    "https://api.onedrive.com/v1.0/drive/special/music");
  var client = new HttpClient();
  client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR TRIAL TOKEN");
  var json = await client.GetStringAsync(uri);
};

Recuerde que el token de prueba expira después de una hora, por lo que no olvide obtener uno nuevo para hacer una demostración de la aplicación a su jefe.

Autenticar con OAuth

Ahora que ha registrado la aplicación y comprende los términos importantes, puede implementar la autenticación. Estos son los pasos para hacerlo, que se muestran en la Figura 2:

  1. El usuario inicia la autenticación, por ejemplo, haciendo clic en un botón.
  2. La aplicación comprueba si hay un token de acceso disponible.
  3. Si lo hay, la aplicación ya está autenticada y el usuario puede pasar a la siguiente operación. Si no hay ningún token de acceso disponible, la aplicación navega a una página XAML que contiene un objeto WebView.
  4. En la página XAML se establece la dirección URL inicial del objeto WebView para cargar la página del punto de conexión de autenticación. En la página XAML también se describe el evento WebNavigationCompleted del objeto WebView para poder supervisar el tráfico de este control. Obtendrá más información sobre cómo se estructura la dirección URL inicial más adelante en este artículo.
  5. El objeto WebView carga el código HTML desde el punto de conexión de autenticación.
  6. El usuario especifica su nombre de usuario y contraseña en la página de autenticación HTML. Tenga en cuenta que esta interacción se produce solamente entre el usuario y el servidor de OneDrive. La página XAML solamente actúa como contenedor.
  7. El usuario presiona el botón HTML que envía el formulario al servidor de autenticación. Si el usuario lo configuró, se muestran páginas adicionales para controlar la autenticación en dos fases.
  8. Si las credenciales son correctas, el servidor de autenticación redirecciona el objeto WebView a una dirección URL especial que indica el inicio de sesión correcto. Esta dirección URL también tiene el token de acceso como uno de sus parámetros de cadena de consulta. La página XAML detecta que se produjo el redireccionamiento y puede analizar el token de acceso desde la nueva dirección URL del objeto WebView.
  9. La página de autenticación analiza el token de acceso desde el URI redireccionado.
  10. La aplicación regresa a la página XAML original. El token de acceso se guarda para solicitudes adicionales.

Flujo de trabajo de OAuth
Figura 2 Flujo de trabajo de OAuth

Nota: Si bien es importante comprender cómo funciona OAuth, los desarrolladores de Windows 10 tienen la ventaja de disponer de una alternativa más fácil denominada WebAuthenticationBroker. En este artículo, uso el mecanismo OAuth de “bajo nivel” y hablaré sobre el objeto WebAuthenticationBroker en el siguiente artículo.

Descripción de los ámbitos

Cuando el usuario inicia sesión, la aplicación debe informar al servicio de OneDrive sobre el alcance de características que necesitará. Para ello, se especifican ámbitos en la dirección URL de autenticación. Actualmente, el servicio admite los siguientes ámbitos:

  • Inicio de sesión único: wl.signin.
  • Acceso sin conexión: wl.offline_access. Esto permite a la aplicación obtener un token de actualización. Este ámbito se omite cuando se usa la autenticación de flujo de tokens.
  • Acceso de solo lectura: onedrive.readonly. Esto da a la aplicación acceso de solo lectura a los archivos y carpetas. Si la aplicación intenta modificar un archivo o cargar un archivo nuevo, el servicio devuelve el código de error 403 Prohibido.
  • Acceso de lectura y escritura: onedrive.readwrite. Esto da a la aplicación acceso de lectura y escritura a los archivos y carpetas.
  • Carpeta de la aplicación: onedrive.appfolder. Esto permite a la aplicación acceder a la carpeta denominada Aplicación. Daré más detalles sobre esta carpeta especial en este artículo. Tenga en cuenta que este ámbito se concede automáticamente cuando solicita el ámbito de lectura y escritura. Sin embargo, solicitar la carpeta de aplicaciones explícitamente hará que este ámbito se mencione en el cuadro de diálogo que se muestra en la Figura 3, que ofrece una mejor experiencia de usuario.

Figura 3 Iniciar la autenticación

if (!_service.CheckAuthenticate(
  async () =>
  {
    var dialog = new MessageDialog("You are authenticated!", "Success!");
    await dialog.ShowAsync();
    Frame.GoBack();
  },
  async () =>
  {
    var dialog = new MessageDialog("Problem when authenticating!", "Sorry!");
    await dialog.ShowAsync();
    Frame.GoBack();
  }))
{
  Frame.Navigate(typeof (AuthenticationPage));
};

Después de que el usuario especifique sus credenciales en la página web de autenticación, se le mostrará un cuadro de diálogo en el que se le pide que confirme los permisos que solicita la aplicación, tal como se muestra en la Figura 4. El usuario puede cambiar de idea en cualquier momento y revocar parte de los permisos. Para ello, inicia sesión en su cuenta en el sitio web de OneDrive, navega a Seguridad y privacidad y selecciona el vínculo Administrar los permisos en Aplicaciones y servicios. En el ejemplo, siempre solicitará acceso de inicio de sesión único, de lectura y escritura y de appfolder.

Confirmación de la autenticación
Figura 4 Confirmación de la autenticación

Crear una dirección URL inicial

La dirección URL que se usa para iniciar el proceso de autenticación debe transportar información a la aplicación en sí, las características solicitadas (ámbitos), el modo de autenticación y el URI de redireccionamiento.

El modo de autenticación puede ser Token o Código. En este artículo y ejemplo, usé el modo Token, lo que significa que el usuario debe confirmar el inicio de sesión cada vez que se inicie nuevamente la aplicación o después de una hora. Esto parece fastidioso, pero, de hecho, el usuario solo tiene que confirmar el inicio de sesión presionando el botón Sí en el cuadro de diálogo de autenticación, tal como se muestra en la Figura 4.

El URI de redireccionamiento es la dirección a la que el servicio de OneDrive redireccionará la aplicación cuando el inicio de sesión se realice correctamente. Para una aplicación web, se trata del URI de una página de la aplicación y se configura en el Centro para desarrolladores de OneDrive, en la pestaña de configuración de la API. Sin embargo, en el caso de una aplicación para UWP, debería dejar este campo vacío. En cambio, dependerá en un URI de redireccionamiento predefinido:

htt://login.live.com/oauth20_desktop.srf

Juntar todas las piezas

Ahora que comprende cómo funciona la autenticación según OAuth, echemos un vistazo a un poco de código. Puede seguir este ejemplo sencillo haciendo clic en el botón Autenticar.

Puede usar una clase denominada OneDriveService, que se implementa en una PCL. Se crea una instancia de la clase OneDriveService en App.xaml.cs y se le pasa el id. de cliente.

En primer lugar, el objeto MainPage pregunta al servicio de OneDrive si ya está autenticado, lo que significa que ya hay un token de acceso presente. Pasa dos delegados a la llamada al método CheckAuthenticate: un delegado Action que se invocará si la autenticación se realiza correctamente y un delegado Action en caso de que se produzca un error.

Si el servicio todavía no se autenticó, el objeto MainPage usa su propiedad Frame para navegar a la página de autenticación, tal como se muestra en la Figura 5. Esta página es una página XAML simple con un objeto WebView que ocupa toda la pantalla, donde el usuario especificará su nombre de usuario y contraseña, y confirmará.

Figura 5 Código para el objeto AuthenticationPage

public sealed partial class AuthenticationPage
{
  private readonly OneDriveService _service;
  public AuthenticationPage()
  {
    InitializeComponent();
    _service = ((App)Application.Current).ServiceInstance;
    Loaded += (s, e) =>
    {
      var uri = _service.GetStartUri();
      Web.Navigate(uri);
    };
    Web.NavigationCompleted += (s, e) =>
    {
      if (_service.CheckRedirectUrl(e.Uri.AbsoluteUri))
      {
        _service.ContinueGetTokens(e.Uri);
      }
    };
    Web.NavigationFailed += (s, e) =>
    {
      _service.ContinueGetTokens(null);
    };
  }
}

Cuando se carga la página, obtiene el URI de autenticación del objeto OneDriveService:

https://login.live.com/oauth20_authorize.srf?client_id=000000004C169646&
scope=wl.signin+onedrive.readwrite+onedrive.appfolder&response_type=token&
redirect_uri=https%3A%2F%2Flogin.live.com%2Foauth20_desktop.srf

Tal como se explicó, este URI lleva toda la información necesaria, como id. de cliente, secreto de cliente, ámbito, URI de redireccionamiento, etc.

Tenga en cuenta que el objeto WebView se redireccionará varias veces antes de que se devuelva el token de acceso. Es por ello que siempre comprueba el URI de redireccionamiento en el evento NavigationCompleted del objeto WebView. Cuando el URI oauth20_desktop.srf URI se detecte, el objeto OneDriveService recuperará el token de acceso de los parámetros de la cadena de consulta. La información adicional (expiración, tipo de token, ámbito, id. de usuario, etc.) se pasa en la cadena de consulta, pero aquí no se tendrá en cuenta. El URI de redireccionamiento con el token de acceso se abrevia aquí:

https://login.live.com/oauth20_desktop.srf?lc=1033#access_token=EwB4Aq1D...1iiZA%3d&
token_type=bearer&expires_in=3600&scope=wl.signin%20onedrive.readwrite%20onedrive.appfolder
%20onedrive.readonly&user_id=8e5323e8b7c7a0928d03e10811531234

Una vez autenticado el usuario, la aplicación puede comenzar a interactuar con archivos y carpetas. En este artículo, me centraré en unas pocas operaciones, pero ampliar la aplicación para incluir servicios adicionales es relativamente fácil una vez que se comprenden los principios básicos.

Carpeta raíz

En primer lugar, hablaré sobre la carpeta raíz. Esta carpeta es única en su OneDrive y es el elemento primario de cada uno de los demás elementos.

Según la documentación de OneDrive, obtener la carpeta raíz se puede hacer con la siguiente solicitud: GET /drive/root. Esta solicitud devolverá una respuesta JSON, tal como se describe en bit.ly/1M5w4NV. La respuesta JSON se puede deserializar y la información que contiene se puede usar para solicitudes adicionales.

Estructura de archivos y carpetas Llegados a este punto, es importante comprender cómo está estructurado el sistema de archivos. OneDrive depende de un sistema de facetas para proporcionar información sobre los archivos y carpetas. Por ejemplo, un archivo también puede ser una imagen y una foto, y proporcionar información sobre el archivo (por ejemplo, ancho y altura de la imagen y el modelo de la cámara de la foto). En la lista siguiente se muestran las facetas disponibles actualmente y algunas de sus propiedades más importantes:

  • Elemento (nombre, identificador, URL de descarga, referencia de elemento primario, etc.)
  • Carpeta (recuento de elementos secundarios)
  • Archivo
  • Audio (álbum, artista, velocidad de bits, duración, título, etc.)
  • Imagen (ancho, altura)
  • Foto (fabricante y modelo de la cámara, fecha y hora de captura)
  • Vídeo (duración, velocidad de bits, ancho, altura)

Cuando carga un nuevo archivo en OneDrive, se analizará automáticamente y se agregarán algunos metadatos. Por ejemplo, un documento Word es simplemente un archivo. Sin embargo, una imagen capturada con una cámara es una foto y también una imagen, además de ser un archivo. Cada una de estas facetas lleva información adicional sobre el archivo, tal como se muestra en la lista.

Cuando analiza la información JSON que obtiene del servicio de OneDrive, puede asignar estos tipos a clases C#. Al inspeccionar la información JSON, puede saber fácilmente si un elemento es una carpeta, archivo, imagen, vídeo, etc. Por ejemplo, en la Figura 6 se muestra un fragmento de la respuesta JSON para la carpeta raíz. Puede ver que la propiedad de la carpeta lleva información sobre el recuento de elementos secundarios de la carpeta. Si obtiene información sobre una foto, verá las propiedades de la imagen y foto con la información sobre el ancho y la altura, y sobre el fabricante y modelo de la cámara, respectivamente.

En la misma aplicación que se proporciona con este artículo, deserializa la información JSON en las clases incluidas en la carpeta de respuestas, que se asignan al sistema de facetas.

Ahora que comprende cómo funciona la respuesta, puede acceder fácilmente a la información de la carpeta raíz con el código que se muestra aquí:

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
  new AuthenticationHeaderValue("Bearer", AccessToken);
var uri = new Uri("https://api.onedrive.com/v1.0/drive/root");
var json = await client.GetStringAsync(uri);
var rootFolder = JsonConvert.DeserializeObject<ItemInfoResponse>(json);

Para ver el código en acción, puede ejecutar el ejemplo sencillo, presionar primero el botón Autenticar y luego el botón Get Root Folder.

Obtener los elementos secundarios de la carpeta Tal como se muestra en la Figura 6, la respuesta solo contiene metainformación sobre la carpeta. Sabe cuántos elementos secundarios contiene la carpeta, pero necesita ejecutar una o más solicitudes para obtener la lista de elementos secundarios. Aquí también, la documentación de OneDrive ayuda e indica que necesita solicitar un objeto GET para /drive/items/{item-id}/children, tal como se muestra en la Figura 7.

Figura 6 Respuesta JSON para la carpeta raíz

{
  "createdBy": {
    "user": {
      "displayName": "Laurent Bugnion",
      "id": "fb0d8f9700498123"
    }
  },
  "createdDateTime": "2010-11-27T17:09:25.513Z",
  "id": "FB0D8F97004979CD!ABC",
  "lastModifiedBy": {
    "user": {
      "displayName": "Laurent Bugnion",
      "id": " fb0d8f9700498123"
    }
  },
  "lastModifiedDateTime": "2015-10-04T14:36:36.217Z",
  "name": "root",
  "size": 178558187077,
  "webUrl": "https://onedrive.live.com/?cid=fb0d8f9700498123",
  "folder": {
    "childCount": 18
  }
}

Figura 7 Obtener la lista de elementos secundarios

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
  new AuthenticationHeaderValue("Bearer", AccessToken);
var request = string.Format("/drive/items/{0}/children", info.Id);
var uri = new Uri(
  "https://api.onedrive.com/v1.0"
  + request);
var json = await client.GetStringAsync(uri);
var response = JsonConvert.DeserializeObject<ParseChildrenResponse>(json);
return response.Value;

En la Figura 7, la información JSON se deserializa en una clase denominada Parse­ChildrenResponse. Nuevamente, esto se asigna a la respuesta JSON, que encapsula la lista de elementos secundarios en un valor con nombre de la matriz de JavaScript. La clase ParseChildrenResponse se muestra en la Figura 8.

Figura 8 Clase ParseChildrenResponse

public class ParseChildrenResponse
{
  public IList<ItemInfoResponse> Value
  {
    get;
    set;
  }
  [JsonProperty("@odata.nextLink")]
  public string NextLink
  {
    get;
    set;
  }
}

Debido a que cada elemento secundario es un objeto ItemInfoResponse, sabrá cómo controlarlos y podrá decidir si cada elemento secundario es una carpeta, archivo, foto, archivo de audio, etc.

Tenga en cuenta que si quiere evitar hacer dos llamadas para recuperar la información de la carpeta y rellenar su lista de elementos secundarios, también es posible usar la siguiente solicitud, que hace todo en una sola llamada:

 

GET /drive/items/root?expand=children

Descripción de la paginación Cuando accede a una carpeta con muchos elementos secundarios, la respuesta que envía el servicio de OneDrive podría estar incompleta y requerir paginación. De manera predeterminada, el servicio solo devuelve una lista de 200 elementos secundarios, como máximo. Si la carpeta que está examinando contiene más elementos secundarios, se agrega una propiedad a la lista de elementos secundarios, denominada “@odata.nextLink”, tal como se muestra en la Figura 8. Esta propiedad contiene el URI para la siguiente solicitud que la aplicación tendrá que llevar a cabo para llegar a la siguiente “página”. En una aplicación para UWP, tiene la opción de llamar inmediatamente al servicio para obtener la siguiente página de elementos (que estaría bien porque las listas largas se virtualizan) o mostrar un botón Más e implementar la navegación de páginas en la aplicación.

Examinar una subcarpeta Cuanto tenga el identificador de una carpeta, puede examinar la carpeta fácilmente con la siguiente solicitud:

GET /drive/items/{item-id}

Esto es ideal cuando ya tiene el identificador de la carpeta, pero a veces no dispone de esta información. Otra sintaxis permite recuperar la información de la carpeta con su ruta de acceso relativa a la raíz. Puede ver esta sintaxis en la Figura 9.

Figura 9 Examinar una subcarpeta por ruta de acceso

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
  new AuthenticationHeaderValue("Bearer", AccessToken);
var request = string.Format("/drive/root:/{0}", path);
var uri = new Uri(
  "https://api.onedrive.com/v1.0"
  + request);
var json = await client.GetStringAsync(uri);
var result = JsonConvert.DeserializeObject<ItemInfoResponse>(json);
return result;

Carpeta Aplicación

OneDrive tiene algunas carpetas especiales, tales como Música, Documentos, Fotos, etc. Una de las carpetas especiales se introdujo recientemente: la carpeta Aplicación. Esta es una carpeta especial disponible para su aplicación para, por ejemplo, persistir la configuración de itinerancia, cargar copias de seguridad, etc. Tenga en cuenta que la carpeta Aplicación no es segura ni se oculta de ninguna manera. De hecho, reside en una carpeta denominada Aplicaciones, que se encuentra en la raíz del almacenamiento OneDrive del usuario. La carpeta Aplicación de la aplicación lleva el mismo nombre que la aplicación OneDrive, tal como se especificó durante su registro para obtener el id. de cliente. Tenga en cuenta que el nombre de la aplicación puede estar localizado en distintos idiomas, según la configuración de la aplicación OneDrive. El usuario tiene acceso completo a la carpeta Aplicación, a través del sitio web de OneDrive o de cualquier aplicación y puede eliminarla si quiere.

Antes de la introducción del concepto de la carpeta Aplicación, las aplicaciones guardaban (y aún lo hacen) la configuración y otros archivos en la raíz de OneDrive o en una carpeta personalizada. El uso de la carpeta Aplicación para estos elementos es mucho más limpio y ofrece una mejor experiencia de usuario. Según la documentación de OneDrive (bit.ly/1MBUkS2), la solicitud para obtener la información de la carpeta Aplicación es la siguiente:

GET /drive/special/approot

Como puede ver, es fácil implementar la carpeta Aplicación para cualquiera de sus aplicaciones.

Descargar un archivo

¿Para qué serviría OneDrive si no pudiese cargar o descargar archivos? En esta sección y la siguiente, verá cómo realizar esta operación crítica, que es muy fácil.

Para descargar el contenido de un archivo, OneDrive crea un objeto DownloadUrl que guarda como una propiedad en la respuesta del elemento. Sin embargo, observe que la dirección URL solo es válida durante un tiempo breve, por lo que si la información del archivo se almacenó en caché, es posible que primero tenga que obtenerla nuevamente del servicio, tal como se muestra en la Figura 10.

Figura 10 Descargar el contenido de un archivo

public async Task<Stream> RefreshAndDownloadContent(
  ItemInfoResponse model,
  bool refreshFirst)
{
  var client = new HttpClient();
  client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", AccessToken);
  // Refresh the item's information
  if (refreshFirst)
  {
    var request = string.Format("/drive/items/{0}", model.Id);
    var uri = new Uri(
      "https://api.onedrive.com/v1.0"
      + request );
    var json = await client.GetStringAsync(uri);
    var refreshedItem =
      JsonConvert.DeserializeObject<ItemInfoResponse>(json);
    model.DownloadUrl = refreshedItem.DownloadUrl;
  }
  var response = await client.GetAsync(model.DownloadUrl);
  var stream = await response.Content.ReadAsStreamAsync();
  return stream;
}

Cuando obtenga el flujo de contenido del archivo, puede procesarlo localmente, guardarlo, etc. En el ejemplo sencillo, se pide al usuario la ubicación para guardar el archivo con un objeto FileSavePicker.

Cargar un archivo

De manera similar, la carga de un archivo también es muy sencilla una vez que obtenga el flujo de este. En Windows 10, esto se puede hacer con una instancia de StorageFile, por ejemplo, con un objeto FileOpenPicker. Una vez que se lea el flujo, puede cargarlo en OneDrive. Según la documentación, debe usar una operación PUT:

PUT /drive/items/{parent-id}:/{filename}:/content

El objeto HttpClient admite el método PUT con una instancia de HttpContent. En este caso, debido a que tiene un flujo de archivo sin procesar, puede usar una instancia StreamContent. Si lo único que quiere hacer es guardar un archivo de texto, puede usar un objeto StringContent, etc.

La otra información que debe pasar al servicio es el identificador de la carpeta en la que se guardará el archivo. En el ejemplo sencillo que se muestra en la Figura 11, el objeto parentId se pasa al método de carga. Tenga que cuenta que la operación PUT devuelve contenido JSON que describe la nueva información del archivo en OneDrive, como su identificador, URL web, URL de descarga, etc.

Figura 11 Cargar el contenido de un archivo

var content = new StreamContent(stream);
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
  new AuthenticationHeaderValue("Bearer", AccessToken);
var uri = new Uri(
  "https://api.onedrive.com/v1.0"
  + string.Format(
    "/drive/items/{0}:/{1}:/content",
    parentId,
    fileName));
var response = await client.PutAsync(uri, content);
var json = await response.Content.ReadAsStringAsync();
var result = JsonConvert.DeserializeObject<ItemInfoResponse>(json);
return result;

Además de la carga sencilla que se describe aquí, la API de OneDrive también ofrece cargas de varias partes y reanudables con otra sintaxis. La carga sencilla es suficiente para los archivos de menos de 100 MB. Si el archivo es más grande, debe consultar la documentación en bit.ly/1PB31Cn.

Obtener un vínculo único

La última operación que demostraré aquí es cómo obtener un vínculo único “compartir” para un elemento. Esta operación es de utilidad para enviar un vínculo único a un amigo por correo electrónico, mensaje de texto, medios sociales, etc. En la Figura 12 se muestra cómo obtener esta información según el identificador del elemento. En el ejemplo, puede obtener un vínculo al archivo que acaba de cargar en la demostración anterior.

Figura 12 Obtener un vínculo para compartir

public async Task<LinkResponseInfo> GetLink(
  LinkKind kind,
  string fileId)
{
  // LinkKind id View or Edit
  var client = new HttpClient();
  client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", AccessToken);
  var request = string.Format("/drive/items/{0}/action.createLink", fileId);
  var uri = new Uri(
    "https://api.onedrive.com/v1.0"
    + request);
  var requestJson = JsonConvert.SerializeObject(
    new RequestLinkInfo
    {
      Type = kind.ToString().ToLower()
    });
  var content = new StringContent(
    requestJson,
    Encoding.UTF8,
    "application/json");
  var response = await client.PostAsync(uri, content);
  var result = JsonConvert.DeserializeObject<LinkResponseInfo>(
    await response.Content.ReadAsStringAsync());
  return result;
}

Según la documentación, la solicitud es ligeramente diferente que las solicitudes GET que realizó anteriormente, ya que el servicio necesita información más detallada. La solicitud “vínculo para compartir” es la siguiente: POST /drive/items/{item-id}/action.createLink. La información que necesita publicar en el servicio es un fragmento de JSON con el tipo de vínculo: “view” o “edit”, por ejemplo: { "type": "view" }

Resumen

Hay varias operaciones adicionales que no mencioné en este artículo, como la eliminación de un archivo, la actualización del contenido de un archivo y la sincronización de los cambios. Sin embargo, en general las operaciones siguen el mismo patrón y se pueden realizar con HttpClient, métodos HTTP y JSON. Gracias a los avances en la programación asincrónica de Microsoft .NET Framework, este tipo de operaciones son extremadamente fluidas y fáciles de implementar en cualquier marco admitido, por ejemplo, Windows 10, WPF, Windows Phone, Xamarin.iOS, Xamarin.Android, etc. Con esta facilidad de uso, no hay motivo para no incluir algún tipo de interacción con la nube en sus aplicaciones para UWP, por ejemplo, para crear una copia de seguridad del contenido y sincronizar la configuración. En el siguiente artículo, verá cómo la PCL recién lanzada por el equipo de OneDrive le ayudará a que esta integración sea aún más fácil.

Laurent Bugniones director sénior de IdentityMine, una de las empresas líderes, y socio Gold, para las tecnologías de Microsoft. Reside en Zúrich, Suiza. Su libro de 2010, “Silverlight 4 Unleashed”, publicado por Sams, es una continuación avanzada de “Silverlight 2 Unleashed” (2008). Escribe para varias publicaciones, lleva nueve años como Microsoft MVP y lleva dos años como director regional de Microsoft. Es autor del conocido marco de código abierto MVVM Light para Windows, WPF y Xamarin, y del popular curso de referencia Pluralsight sobre MVVM Light. Puede ponerse en contacto con él a través de su blog en galasoft.ch.

Gracias a los siguientes expertos técnicos por revisar este artículo: Corrado Cavalli (Gaia) y Ryan Gregg (Microsoft)