Découvrir et apprendre à programmer avec l'API Cloud Orange

Pour Python, il est nécessaire de posséder … Python ! Pour télécharger l'installeur, c'est par ici.

Nous utiliserons la version 3.5 de Python pour cet exemple. Cependant, vous pouvez décider de prendre la version 2.7 pour l'intégrer à votre projet, cela n'a pas d'importance.

Une fois l'installation de Python terminée, on démarre « Python » et « IDLE », il s'agit de l'interpréteur Python et de la console Python. C'est dans cette dernière que nous allons coder notre application.

La première étape va être de s'assurer du consentement de l'utilisateur dont on veut avoir accès à son compte Cloud.

Cela se fait avec la requête passer à l'URL suivant :

https://api.orange.com/oauth/v2/authorize?prompt=login%20consent&state=orangeCloud&redirect_uri=[REDIRECT_URI]&response_type=code&client_id=[CLIENT_ID]&scope=openid%20Cloud

Pensez à utiliser la bibliothèque urllib avec :

import urllib
f = { 'redirect_uri' : 'http://www.masuperapplication.com/'}
urllib.urlencode(f)

En effet, cette dernière vous facilitera la tâche. Les espaces doivent être remplacés par des %20, les slash par des %2F.

Notre utilisateur arrivera donc sur la page de connexion Orange Cloud puis, une fois authentifié, il sera redirigé sur la page spécifiée dans votre redirect_uri :

http://www.masuperapplication.com/?code=OFR-3987d7…d5r47eff&state=state

Il ne vous reste plus qu'à récupérer ce code lors de la redirection. Vous devrez passer le code au constructeur de la classe OrangeCloudClient. Lors de l'instanciation, la classe se chargera seule de l'entière gestion des tokens d'authentification. Vous n'aurez pas à gérer cette partie.

Attention, avant de donner son consentement, l'utilisateur doit avoir accepté le contrat général d'utilisation du Cloud Orange. S'il ne l'a pas encore accepté, la demande retournera une erreur CGU_NOT_ACCEPTED. Toutefois, une page pour accepter le contrat est présentée automatiquement à l'utilisateur lors de sa connexion.

Avant toute chose, il faut commencer par importer les bonnes bibliothèques. Pour cela, il suffit de rentrer la ligne ci-dessous :

from pyorangeCloud import OrangeCloudClient

Ensuite, l'instanciation est simple, elle se fait comme suit :

app = {'clientId':'CLIENT_ID','clientSecret':'CLIENT_SECRET','redirectUri':'REDIRECT_URI'} client = OrangeCloudClient(app,authCode='CODE_RECUPERE_LORS_RECUPERATION_DEMANDE_CONSENTEMENT')

Pour lister le contenu d'un dossier, le code est le suivant :

folderInfo = client.listFolder()  
for f in folderInfo['subfolders']+folderInfo['files']:     
    print (f['name'] + ' ' + f.get('type',''))

Ce code permet d'avoir la liste des fichiers et dossiers à la racine du Cloud.

Pour lister le contenu d'un dossier spécifique, il est nécessaire de passer un identifiant de dossier à la méthode « listFolder(FILE_ID) ».
Aussi, si vous souhaitez récupérer récursivement le contenu de dossier et des sous-dossiers, vous utiliserez la méthode « listAllFiles() » en lieu et place de « listFolder() ».

Dans l'exemple précédent, nous avons vu comment récupérer le contenu du dossier racine. Cependant, pour passer un FILE_ID à notre méthode, il est nécessaire de pouvoir récupérer ce FILE_ID. Pour cela, voici comment faire :

folderInfo = client.listFolder()
for d in folderInfo['subfolders']:
     print (d['name']) 
files = folderInfo['files'] 
for f in files:
     details = client.getFileInfo(f['id'])
     print ("%(name)s: type:%(type)s size:%(size)s date:%(creationDate)s" % details)

Vous avez maintenant toutes les informations pour lister le contenu du Cloud Orange. Nous allons maintenant voir comment télécharger du contenu.

Pour télécharger du contenu, c'est extrêmement simple. Il suffit de donner un identifiant de fichier à cette fonction et un répertoire de téléchargement. Cette simple ligne se charge de tout !

client.downloadFile(fileId,"/my/target/directory-or-file")

Pour envoyer du contenu, l'opération est simple aussi, il s'agit de la fonction suivante :

fileId = client.uploadFile("mypicture.jpg",folderInfo['id'],"@/my/file/location/mypicture.jpg")

Cette dernière prend trois arguments en paramètre :

-            le premier est le nom du fichier qui va être envoyé ;

-            le second est l'identifiant du répertoire dans lequel on upload le fichier ;

-            le troisième est le lieu de stockage local du fichier (le path du fichier à envoyer).

Ces deux fonctions prennent en argument l'identifiant du répertoire à supprimer.

#Pour un fichier
client.deleteFile(fileId)

#Pour un dossier
client.deleteFolder(folderId)

Pour créer un répertoire sur le Cloud Orange, il est nécessaire de passer en paramètre à la fonction suivante le nom du répertoire à créer ainsi que l'identifiant du dossier parent (dans l'arborescence du Cloud).

folderInfo = client.createFolder("myfoldername",myFolderId)

Voici un résumé des fonctions disponibles dans le SDK officiel en Python ; cependant, libre à vous d'utiliser votre propre langage. L'API étant une API REST, vous pouvez utiliser n'importe quel langage que vous maîtrisez, ou même directement cURL.

Il est nécessaire de télécharger et d'installer Android Studio téléchargeable sur ce lien.

L'installation d'Android Studio requiert Java :

• JRE ;
• JDK.

Après installation, on démarre Android Studio, puis on clique sur « Import project (Eclipse ADT, Gradle, etc.) ».

Le menu au démarrage d'Android Studio se présente comme suit :

Nous sélectionnons alors le chemin (path) du dossier exemple (sample) (OrangeCloudAndroidSdk-master/sample), puis on clique sur OK, comme indiqué ci-dessous :

À ce stade, il est important de remplacer le APP_KEY, le APP_SECRET et le APP_REDIRECT_URI par les clés d'API données dans votre espace client Orange dans le fichier MainActivity.java :

final static private String APP_KEY = "votre api key";
final static private String APP_SECRET = "votre app secret";
final static private String APP_REDIRECT_URI = "votre url de redirection";

Maintenant, nous allons vérifier les deux conditions qui font que cela va fonctionner.

II-B-2-a. Vérifier le AndroidManifest.xml ▲

<activity
    android:name="com.orange.labs.sdk.activity.AuthActivity"
    android:launchMode="singleTask"
    android:configChanges="orientation|keyboard"/>

<uses-permission android:name="android.permission.INTERNET"></uses-permission>

II-B-2-b. Vérifier le Activity.java▲

final static private String APP_KEY = "votre api key";
final static private String APP_SECRET = "votre app secret";
final static private String APP_REDIRECT_URI = "votre url de redirection";

Attention, dans cette partie nous allons traiter de l'authentification de l'API (comprendre que votre application se connecte aux serveurs Orange) et de l'authentification de l'utilisateur (qui doit lui aussi s'authentifier pour que notre application puisse utiliser son espace de stockage Cloud). Il est important de ne pas les confondre, aussi, l'utilisateur doit posséder un espace sur le Cloud Orange. S'il n'en a pas, c'est par ici.

Rien d'étonnant, avant d'utiliser l'API, il est nécessaire d'authentifier l'application auprès d'Orange, et cela se fait simplement :

// Dans la déclaration de classe
public OrangeCloudAPI<AuthSession> mApi;

// On instancie un objet de type AuthSession que l'on appelle session. La magie du SDK s'occupe du reste.
AuthSession session = new AuthSession(Activity.this, APP_KEY, APP_SECRET, APP_REDIRECT_URI);
mApi = new OrangeCloudAPI<AuthSession>(session);

Comme dans toute API, il est nécessaire de définir un « scope » pour notre accès, dans le fichier AndroidManifest.xml. Un « scope » est un paramètre qui permet de définir la portée des droits de la demande d'autorisation. Les différents scopes sont définis dans le Getting Started de l'API Cloud d'Orange.

On définit le scope avec cette ligne de code :

mApi.addScope("Cloud");

Le « scope » dépend de l'utilisation que votre application va avoir avec le Cloud d'Orange.

Il est possible d'utiliser de multiples « scope ». Il suffit de les écrire les uns à la suite des autres avec des espaces. Par exemple :

mApi.addScope("Cloud Cloudfullread") ;

Maintenant, il est nécessaire d'authentifier l'utilisateur auprès d'Orange. Pour cela, s'il s'agit de la première connexion de l'utilisateur, la méthode ouvre une AuthActivity (déclarée dans le AndroidManifest.xml). Cette étape permet d'authentifier l'utilisateur ainsi que d'autoriser l'accès aux services Cloud d'Orange.

mApi.getSession().startAuthentication();

Lors de l'authentification, l'utilisateur est renvoyé vers votre Activity.java. À ce moment, pour finir l'authentification de l'utilisateur, vous devez compléter votre méthode onResume avec le code suivant :

@Override
protected void onResume() {
    super.onResume();
    // Récupère la session et regarde ou en est le processus d'authentification
    final AuthSession session = mApi.getSession();
    session.checkAuthentication(new OrangeListener.Success<String>() {
        @Override
        public void onResponse(String response) {
            // La session est valide, vous pouvez utiliser les fonctions du Cloud Orange.
        }
    }, new OrangeListener.Error() {
        @Override
        public void onErrorResponse(OrangeAPIException error) {
            // Il y a eu une erreur lors du processus
        }
    });
}

II-B-4-a. Lister le contenu du Cloud Orange▲

mApi.listEntries(anEntry, parameters, new OrangeListener.Success<OrangeCloudAPI.Entry>() {
    Override
    public void onResponse(OrangeCloudAPI.Entry response) {
        // success
    }
}, new OrangeListener.Error() {
    @Override
    public void onErrorResponse(OrangeAPIException error) {
        // Error occurred
    }
});

file_def {
    id (string, optional),
    name (string, optional),
    size (integer, optional),
    creationDate (date-time, optional),
    lastUpdateDate (date-time, optional),
    type (string, optional) = ["FILE" or "PICTURE" or "VIDEO" or "AUDIO"],
    downloadUrl (string, optional),
    previewUrl (string, optional),
    thumbUrl (string, optional),
    metaData (object, optional)
}

II-B-4-b. Envoyer un fichier vers le Cloud d'Orange▲

  mApi.upload(fileUri, filename, entryToUpload, new OrangeListener.Success<JSONObject>() {
        @Override
        public void onResponse(JSONObject response) {
            // Le fichier est envoyé
        }
    }, new OrangeListener.Progress() {
        @Override
        public void onProgress(float ratio) {
            // Progress bar (ratio = [0,1])
        }
    }, new OrangeListener.Error() {
        @Override
        public void onErrorResponse(OrangeAPIException error) {
            // Une erreur a été levée
        }
});

En rappel, vous devez avant tout développement posséder un Client ID et un Client Token pour pouvoir appeler l'API.

Pour programmer en Swift, vous devez disposer de Xcode et d'un Mac en mode développeur. Pour cela rien de plus simple, rendez-vous dans l'App Store de votre Mac puis cherchez « Xcode ».

L'installation est simplifiée et vous n'avez rien à faire pour que cela fonctionne.

À présent, rendez-vous sur le lien de téléchargement du SDK Swift de l'API Cloud Orange.

Pour ceux qui utilisent Git, vous pouvez cloner le repo git. Pour cela, ouvrez votre terminal, et lancez successivement les commandes :

git init
git clone https://github.com/Orange-OpenSource/OrangeCloudIOSSdk.git

Pour les autres, vous pouvez cliquer sur « Download in Zip » comme présenté dans la figure ci-dessous.

Vous vous retrouvez donc avec un répertoire zip à décompresser. Après la décompression, lancez le fichier « OrangeCloudSDK.xcodeproj ».

Vous êtes à présent dans Xcode. Avec le projet lancé, vous avez l'arborescence suivante :

À ce stade, il est important de remplacer le APP_KEY, le APP_SECRET et le APP_REDIRECT_URI par les clés d'API données dans votre espace client Orange dans le fichier BrowseController.m.

(void)viewDidLoad {
    [super viewDidLoad];
    self.view.backgroundColor = [UIColor whiteColor];

    // Créez un objet connexion qui fera la première authentification utilisateur et une session avec l'API Cloud Orange

    self.CloudManager = [[CloudManager alloc] initWithAppKey:@"APP_KEY"
                                                   appSecret:@"APP_SECRET"
                                                 redirectURI:@"APP_REDIRECT_URI"];
    
    [self.CloudManager setUseWebView:TRUE];
    [self.CloudManager setForceLogin:TRUE];
}

À présent, vous n'avez plus qu'à compiler et démarrer votre simulateur iOS pour obtenir un projet fonctionnel.

Bien que le SDK ait été écrit en Objective-C, ce dernier a été conçu de manière à maximiser la compatibilité avec Swift. Ainsi, si vous souhaitez utiliser le SDK dans un projet Swift, vous n'avez qu'à ajouter la ligne suivante dans le bridging header de votre application :

#import "CloudManager.h"

L'authentification est automatiquement gérée par le SDK. Aussi, vous n'avez pas à gérer cette partie dans votre code.

La gestion du « scope » est automatique en fonction des usages de votre application. Aussi, cette partie n'a pas à être gérée dans votre code.

Il s'agit de la classe principale du SDK, cette dernière vous autorise l'accès à l'intégralité des fonctionnalités du Cloud (Authentification utilisateur, liste des fichiers, informations de fichiers…).

Lors du développement de votre application, vous n'avez qu'à instancier un objet CloudManager avec votre CLIENT_ID et votre CLIENT_TOKEN dans la vue principale. Ensuite, lorsque l'utilisateur a donné son consentement, vous pourrez accéder à ses fichiers.

II-C-3-a. Lister le contenu du Cloud Orange▲

func listFolder (context : TestContext, result : (TestState)->Void) {
    if let folder = context.testFolder {
        context.manager.listFolder(folder, restrictedMode: false, showThumbnails: true, filter: .All, flat: false, tree: false, limit: 0, offset: 0) { items, status in
            if let items = items as? [CloudItem] where items.count > 0 {
                context.testFile = items[0]
            }
            result (status == StatusOK ? .Succeeded : .Failed)
        }
    } else {
        result (.Failed)
    }
}

file_def {
    id (string, optional),
    name (string, optional),
    size (integer, optional),
    creationDate (date-time, optional),
    lastUpdateDate (date-time, optional),
    type (string, optional) = ["FILE" or "PICTURE" or "VIDEO" or "AUDIO"],
    downloadUrl (string, optional),
    previewUrl (string, optional),
    thumbUrl (string, optional),
    metaData (object, optional)
}

Il est important de noter que cette tâche pouvant être longue, elle doit être appelée en tâche de fond, cela pour ne pas faire patienter l'utilisateur durant le processus.

 func uploadFile (context : TestContext, result : (TestState)->Void) {
    let bundle = NSBundle.mainBundle()
    if let folder = context.testFolder,
        path = bundle.pathForResource("image", ofType: "jpg"),
        data = NSData (contentsOfFile: path) {
        context.manager.uploadData(data, filename: "image.jpg", folderID: folder.identifier, progress: nil) { item, status in //) { CloudItem, status in
            if status == StatusOK {
                context.testFile = item
                result (.Succeeded)
            } else {
                result (.Failed)
            }
        }
    } else {
        result (.Failed)
    }
}